portguard 0.1.1

package/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing to portguard
+
+Thanks for your interest in contributing! 🎉
+
+## Quick Start
+
+1. Fork this repo
+2. Create a branch: `git checkout -b feature/amazing-feature`
+3. Make your changes
+4. Write tests if applicable
+5. Run tests: `npm test`
+6. Commit: `git commit -m 'feat: add amazing feature'`
+7. Push: `git push origin feature/amazing-feature`
+8. Open a Pull Request
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/portguard.git
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Run tests
+npm test
+```
+
+## Code Style
+
+We use:
+- ESLint for linting
+- Prettier for formatting
+- Conventional Commits for commit messages
+
+### Commit Message Format
+
+```
+type(scope): subject
+
+body (optional)
+
+footer (optional)
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style (formatting, semicolons, etc.)
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `perf`: Performance improvement
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+**Example:**
+```
+feat(cli): add --verbose flag for detailed output
+
+Adds a new --verbose flag that shows debug information.
+Useful for troubleshooting issues.
+
+Closes #42
+```
+
+## Testing
+
+Please add tests for new features. We aim for >80% coverage.
+
+```bash
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## Reporting Bugs
+
+Use GitHub Issues with the bug report template.
+
+**Before reporting:**
+1. Check existing issues
+2. Try the latest version
+3. Include reproduction steps
+
+## Feature Requests
+
+Use GitHub Issues with the feature request template.
+
+**Before requesting:**
+1. Check existing issues and discussions
+2. Explain the use case, not just the solution
+3. Be open to alternative approaches
+
+## Pull Request Guidelines
+
+**Before submitting:**
+- [ ] Tests pass locally
+- [ ] Code follows style guide (run `npm run lint`)
+- [ ] Commit messages follow convention
+- [ ] PR description explains what/why, not just how
+- [ ] Breaking changes are clearly marked
+
+**PR Checklist:**
+- [ ] Updated documentation if needed
+- [ ] Added tests for new functionality
+- [ ] Updated CHANGELOG.md (if applicable)
+- [ ] Linked related issues
+
+## Questions?
+
+Open a discussion or reach out on [Twitter @muin_kr](https://twitter.com/muin_kr).
+
+---
+
+## Code of Conduct
+
+Be respectful, inclusive, and constructive.
+
+**Expected behavior:**
+- Use welcoming and inclusive language
+- Respect differing viewpoints and experiences
+- Accept constructive criticism gracefully
+- Focus on what's best for the community
+
+**Unacceptable behavior:**
+- Harassment, trolling, or discriminatory language
+- Publishing others' private information
+- Other conduct which could reasonably be considered inappropriate
+
+---
+
+Thank you for contributing! 🙏
+
+**Run by AI, for humans** - [MUIN Company](https://muin.company)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MUIN
+
+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,202 @@
+# portguard
+
+**Who's stealing your ports? portguard knows.**
+
+[![npm version](https://badge.fury.io/js/portguard.svg)](https://www.npmjs.com/package/portguard)
+[![npm downloads](https://img.shields.io/npm/dm/portguard.svg)](https://www.npmjs.com/package/portguard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/portguard.svg)](https://nodejs.org)
+[![GitHub stars](https://img.shields.io/github/stars/muin-company/portguard.svg?style=social)](https://github.com/muin-company/portguard)
+
+## The Problem
+
+```
+Error: listen EADDRINUSE: address already in use :::3000
+```
+
+You've seen this error a thousand times. You run `lsof -ti:3000 | xargs kill -9` from muscle memory. But can you even remember that command? And which of your 8 abandoned dev servers is hogging port 8080?
+
+## The Solution
+
+```bash
+$ portguard
+
+🔒 Active Ports:
+
+PORT       PID        PROCESS              ADDRESS          UPTIME
+3000       45231      node                 *:3000           2h 15m
+5432       2341       postgres             127.0.0.1:5432   5d 3h
+8080       46123      node                 *:8080           1h 30m
+
+$ portguard kill 3000 -y
+✓ Killed process 45231 (node) on port 3000
+```
+
+No memorizing `lsof` flags. No piping through `xargs`. One command.
+
+## Installation
+
+```bash
+npm install -g portguard
+```
+
+Or run without installing:
+
+```bash
+npx portguard
+```
+
+## Quick Start
+
+```bash
+# What's using my ports?
+portguard
+
+# What's on port 3000?
+portguard 3000
+
+# Kill it
+portguard kill 3000
+
+# Kill without asking
+portguard kill 3000 -y
+
+# Nuke zombie dev servers
+portguard clean
+```
+
+## Examples
+
+### "EADDRINUSE" — the classic
+
+```bash
+$ npm run dev
+Error: listen EADDRINUSE: address already in use :::3000
+
+$ portguard 3000
+🔍 Port 3000: node (PID 45231) — /Users/me/old-project/index.js
+   Running for 2h 15m
+
+$ portguard kill 3000 -y
+✓ Killed process 45231 (node) on port 3000
+
+$ npm run dev
+✓ Server started on http://localhost:3000
+```
+
+### End of day cleanup
+
+```bash
+$ portguard
+
+🔒 Active Ports:
+
+PORT       PID        PROCESS              ADDRESS          UPTIME
+3000       45231      node                 *:3000           4h
+5000       45892      python3              127.0.0.1:5000   2h
+5432       2341       postgres             127.0.0.1:5432   5d
+8080       46123      node                 *:8080           3h
+
+# Kill dev servers, keep database
+$ portguard kill 3000 -y
+$ portguard kill 5000 -y
+$ portguard kill 8080 -y
+```
+
+### Post-crash zombie hunt
+
+```bash
+$ portguard clean
+
+🧟 Found 3 zombie processes:
+
+  PID 98123 - node (port 3001) - idle 2h
+  PID 98124 - node (port 3002) - idle 2h
+  PID 98125 - node (port 3003) - idle 2h
+
+Kill all? (y/N): y
+
+✓ Killed 3 zombie processes
+```
+
+### Finding free ports in a range
+
+```bash
+$ portguard -r 3000-3010
+
+📊 Port Range 3000-3010:
+  Used: 3000, 3003, 3007
+  Free: 3001, 3002, 3004, 3005, 3006, 3008, 3009, 3010
+```
+
+### Watch mode
+
+```bash
+$ portguard watch -i 2
+
+👁️ Watching ports (refresh every 2s, Ctrl+C to stop)
+
+PORT       PID        PROCESS              ADDRESS
+5000       12341      node                 *:5000
+5001       12389      node                 *:5001           NEW!
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `portguard` | List all active ports |
+| `portguard <port>` | Check specific port |
+| `portguard kill <port>` | Kill process on port |
+| `portguard kill <port> -f` | Force kill (SIGKILL) |
+| `portguard kill <port> -y` | Skip confirmation |
+| `portguard watch` | Continuous monitoring |
+| `portguard watch -i <sec>` | Custom refresh interval |
+| `portguard clean` | Kill zombie dev servers |
+| `portguard -r 3000-4000` | Scan port range |
+
+## Integration
+
+### npm scripts
+
+```json
+{
+  "scripts": {
+    "predev": "portguard kill 3000 -y || true",
+    "dev": "next dev"
+  }
+}
+```
+
+### Shell aliases
+
+```bash
+alias ports='portguard'
+alias killport='portguard kill'
+alias kill3000='portguard kill 3000 -y'
+```
+
+### CI cleanup
+
+```yaml
+- name: Clean ports
+  run: npx portguard clean -y || true
+```
+
+## Platform Support
+
+| Platform | Method |
+|----------|--------|
+| macOS | `lsof` |
+| Linux | `lsof` |
+| Windows | `netstat` |
+
+System processes (root-owned) require `sudo portguard kill <port>`.
+
+## License
+
+MIT © [muin](https://github.com/muin-company)
+
+---
+
+*Stop fighting with ports. Start guarding them.*

package/bin/portguard.js

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import chalk from 'chalk';
+import readline from 'readline';
+import {
+  getActivePorts,
+  getPortInfo,
+  getPortRange,
+  killPort,
+  cleanZombies,
+  displayPorts,
+  displayPortInfo,
+  displayPortRange
+} from '../lib/portguard.js';
+
+const program = new Command();
+
+program
+  .name('portguard')
+  .description('Monitor and manage localhost ports')
+  .version('0.1.0');
+
+// Main command - show all ports
+program
+  .argument('[port]', 'specific port to check')
+  .option('-r, --range <range>', 'scan port range (e.g., 3000-4000)')
+  .action(async (port, options) => {
+    if (options.range) {
+      // Scan port range
+      await handleRange(options.range);
+    } else if (port) {
+      // Show specific port
+      await handlePortCheck(port);
+    } else {
+      // Show all ports
+      await handleListAll();
+    }
+  });
+
+// Kill command
+program
+  .command('kill <port>')
+  .description('Kill process on specific port')
+  .option('-f, --force', 'force kill (SIGKILL)')
+  .option('-y, --yes', 'skip confirmation')
+  .action(async (port, options) => {
+    await handleKill(port, options);
+  });
+
+// Watch command
+program
+  .command('watch')
+  .description('Continuous monitoring mode')
+  .option('-i, --interval <seconds>', 'refresh interval in seconds', '3')
+  .action(async (options) => {
+    await handleWatch(options);
+  });
+
+// Clean command
+program
+  .command('clean')
+  .description('Kill common zombie processes (node, python, etc.)')
+  .option('-f, --force', 'force kill (SIGKILL)')
+  .option('-y, --yes', 'skip confirmation')
+  .action(async (options) => {
+    await handleClean(options);
+  });
+
+/**
+ * Handle listing all ports
+ */
+async function handleListAll() {
+  try {
+    const ports = await getActivePorts();
+    displayPorts(ports);
+  } catch (error) {
+    console.error(chalk.red('Error: ') + error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Handle checking specific port
+ */
+async function handlePortCheck(port) {
+  try {
+    const processes = await getPortInfo(port);
+    displayPortInfo(port, processes);
+  } catch (error) {
+    console.error(chalk.red('Error: ') + error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Handle port range scanning
+ */
+async function handleRange(range) {
+  try {
+    // Parse range (e.g., "3000-4000")
+    const match = range.match(/^(\d+)-(\d+)$/);
+    
+    if (!match) {
+      console.error(chalk.red('Error: Invalid range format. Use: portguard --range 3000-4000'));
+      process.exit(1);
+    }
+    
+    const [, start, end] = match;
+    const rangeInfo = await getPortRange(start, end);
+    displayPortRange(rangeInfo);
+  } catch (error) {
+    console.error(chalk.red('Error: ') + error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Handle kill command
+ */
+async function handleKill(port, options) {
+  try {
+    const processes = await getPortInfo(port);
+    
+    if (processes.length === 0) {
+      console.log(chalk.yellow(`Port ${port} is not in use`));
+      return;
+    }
+
+    // Show what will be killed
+    console.log(chalk.bold(`\n⚠️  About to kill:\n`));
+    for (const proc of processes) {
+      console.log(chalk.yellow(`  PID ${proc.pid}: ${proc.process} on port ${proc.port}`));
+    }
+    console.log('');
+
+    // Confirm unless --yes
+    if (!options.yes) {
+      const confirmed = await confirm('Continue?');
+      if (!confirmed) {
+        console.log(chalk.gray('Cancelled'));
+        return;
+      }
+    }
+
+    // Kill processes
+    const results = await killPort(port, options.force);
+    
+    for (const result of results) {
+      if (result.success) {
+        console.log(chalk.green(`✓ Killed PID ${result.pid} (${result.process})`));
+      } else {
+        console.log(chalk.red(`✗ Failed to kill PID ${result.pid}: ${result.error}`));
+      }
+    }
+  } catch (error) {
+    console.error(chalk.red('Error: ') + error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Handle watch mode
+ */
+async function handleWatch(options) {
+  const interval = parseInt(options.interval) * 1000;
+
+  console.log(chalk.bold(`👁️  Watching ports (refresh every ${options.interval}s, Ctrl+C to stop)\n`));
+
+  const refresh = async () => {
+    // Clear screen
+    console.clear();
+    console.log(chalk.bold(`👁️  Watching ports (refresh every ${options.interval}s, Ctrl+C to stop)\n`));
+
+    try {
+      const ports = await getActivePorts();
+      displayPorts(ports);
+    } catch (error) {
+      console.error(chalk.red('Error: ') + error.message);
+    }
+  };
+
+  // Initial display
+  await refresh();
+
+  // Refresh interval
+  const intervalId = setInterval(refresh, interval);
+
+  // Handle Ctrl+C
+  process.on('SIGINT', () => {
+    clearInterval(intervalId);
+    console.log(chalk.gray('\n\nStopped watching'));
+    process.exit(0);
+  });
+}
+
+/**
+ * Handle clean command
+ */
+async function handleClean(options) {
+  try {
+    const zombies = await cleanZombies();
+
+    if (zombies.length === 0) {
+      console.log(chalk.green('✓ No zombie processes found'));
+      return;
+    }
+
+    // Show what will be killed
+    console.log(chalk.bold(`\n🧟 Found ${zombies.length} zombie process${zombies.length > 1 ? 'es' : ''}:\n`));
+    for (const proc of zombies) {
+      console.log(chalk.yellow(`  PID ${proc.pid}: ${proc.process} on port ${proc.port}`));
+    }
+    console.log('');
+
+    // Confirm unless --yes
+    if (!options.yes) {
+      const confirmed = await confirm('Kill all?');
+      if (!confirmed) {
+        console.log(chalk.gray('Cancelled'));
+        return;
+      }
+    }
+
+    // Kill each zombie
+    let killed = 0;
+    let failed = 0;
+
+    for (const zombie of zombies) {
+      try {
+        const results = await killPort(zombie.port, options.force);
+        for (const result of results) {
+          if (result.success) {
+            console.log(chalk.green(`✓ Killed PID ${result.pid} (${result.process})`));
+            killed++;
+          } else {
+            console.log(chalk.red(`✗ Failed to kill PID ${result.pid}: ${result.error}`));
+            failed++;
+          }
+        }
+      } catch (error) {
+        console.log(chalk.red(`✗ Failed: ${error.message}`));
+        failed++;
+      }
+    }
+
+    console.log(chalk.bold(`\n${killed} killed, ${failed} failed`));
+  } catch (error) {
+    console.error(chalk.red('Error: ') + error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Prompt for confirmation
+ */
+function confirm(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question(chalk.yellow(`${question} (y/N) `), (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+program.parse();

package/lib/portguard.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import chalk from 'chalk';
+
+const execAsync = promisify(exec);
+
+const PLATFORM = process.platform;
+
+/**
+ * Get all active ports and their processes
+ */
+export async function getActivePorts() {
+  try {
+    if (PLATFORM === 'win32') {
+      return await getPortsWindows();
+    } else {
+      return await getPortsUnix();
+    }
+  } catch (error) {
+    throw new Error(`Failed to get active ports: ${error.message}`);
+  }
+}
+
+/**
+ * Get ports on Unix-like systems (macOS, Linux)
+ */
+async function getPortsUnix() {
+  // Try different lsof locations
+  const lsofPaths = [
+    'lsof',           // In PATH
+    '/usr/sbin/lsof', // macOS default
+    '/usr/bin/lsof'   // Linux default
+  ];
+
+  let lastError;
+  
+  for (const lsofPath of lsofPaths) {
+    try {
+      const { stdout } = await execAsync(`${lsofPath} -iTCP -sTCP:LISTEN -n -P`);
+      return parseUnixOutput(stdout);
+    } catch (error) {
+      // lsof exits with code 1 when no ports are listening
+      if (error.code === 1 && error.stdout) {
+        return parseUnixOutput(error.stdout || '');
+      }
+      lastError = error;
+      continue;
+    }
+  }
+
+  // All paths failed
+  if (lastError.message.includes('not found') || lastError.code === 'ENOENT') {
+    throw new Error('lsof not found. Please install lsof to use portguard.');
+  }
+  throw lastError;
+}
+
+/**
+ * Get ports on Windows
+ */
+async function getPortsWindows() {
+  const { stdout } = await execAsync('netstat -ano | findstr LISTENING');
+  return parseWindowsOutput(stdout);
+}
+
+/**
+ * Parse lsof output
+ */
+function parseUnixOutput(output) {
+  const lines = output.trim().split('\n').slice(1); // Skip header
+  const ports = [];
+  const seen = new Set();
+
+  for (const line of lines) {
+    const parts = line.split(/\s+/);
+    if (parts.length < 9) continue;
+
+    const command = parts[0];
+    const pid = parts[1];
+    const address = parts[8];
+
+    // Extract port from address (format: *:PORT or IP:PORT)
+    const portMatch = address.match(/:(\d+)$/);
+    if (!portMatch) continue;
+
+    const port = portMatch[1];
+    const key = `${pid}-${port}`;
+
+    if (!seen.has(key)) {
+      seen.add(key);
+      ports.push({
+        port: parseInt(port),
+        pid: parseInt(pid),
+        process: command,
+        address: address
+      });
+    }
+  }
+
+  return ports.sort((a, b) => a.port - b.port);
+}
+
+/**
+ * Parse netstat output (Windows)
+ */
+function parseWindowsOutput(output) {
+  const lines = output.trim().split('\n');
+  const ports = [];
+  const seen = new Set();
+
+  for (const line of lines) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 5) continue;
+
+    const address = parts[1];
+    const pid = parts[4];
+
+    // Extract port from address (format: IP:PORT)
+    const portMatch = address.match(/:(\d+)$/);
+    if (!portMatch) continue;
+
+    const port = portMatch[1];
+    const key = `${pid}-${port}`;
+
+    if (!seen.has(key)) {
+      seen.add(key);
+      ports.push({
+        port: parseInt(port),
+        pid: parseInt(pid),
+        process: 'unknown', // Windows netstat doesn't show process name
+        address: address
+      });
+    }
+  }
+
+  return ports.sort((a, b) => a.port - b.port);
+}
+
+/**
+ * Get process info for a specific port
+ */
+export async function getPortInfo(port) {
+  const ports = await getActivePorts();
+  return ports.filter(p => p.port === parseInt(port));
+}
+
+/**
+ * Get process info for a range of ports
+ */
+export async function getPortRange(startPort, endPort) {
+  const start = parseInt(startPort);
+  const end = parseInt(endPort);
+  
+  if (isNaN(start) || isNaN(end)) {
+    throw new Error('Invalid port range: ports must be numbers');
+  }
+  
+  if (start > end) {
+    throw new Error('Invalid port range: start port must be less than end port');
+  }
+  
+  if (start < 1 || end > 65535) {
+    throw new Error('Invalid port range: ports must be between 1 and 65535');
+  }
+  
+  const allPorts = await getActivePorts();
+  const rangePorts = allPorts.filter(p => p.port >= start && p.port <= end);
+  
+  return {
+    start,
+    end,
+    total: end - start + 1,
+    used: rangePorts.length,
+    free: (end - start + 1) - rangePorts.length,
+    ports: rangePorts
+  };
+}
+
+/**
+ * Kill process by PID
+ */
+export async function killProcess(pid, force = false) {
+  try {
+    if (PLATFORM === 'win32') {
+      await execAsync(`taskkill ${force ? '/F' : ''} /PID ${pid}`);
+    } else {
+      await execAsync(`kill ${force ? '-9' : ''} ${pid}`);
+    }
+    return true;
+  } catch (error) {
+    if (error.message.includes('No such process') || error.message.includes('not found')) {
+      throw new Error(`Process ${pid} not found`);
+    }
+    if (error.message.includes('permission') || error.message.includes('denied')) {
+      throw new Error(`Permission denied. Try running with sudo/administrator privileges.`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Kill process on a specific port
+ */
+export async function killPort(port, force = false) {
+  const processes = await getPortInfo(port);
+  
+  if (processes.length === 0) {
+    throw new Error(`No process found on port ${port}`);
+  }
+
+  const results = [];
+  for (const proc of processes) {
+    try {
+      await killProcess(proc.pid, force);
+      results.push({ success: true, ...proc });
+    } catch (error) {
+      results.push({ success: false, error: error.message, ...proc });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Find and kill zombie processes
+ */
+export async function cleanZombies() {
+  const ports = await getActivePorts();
+  const zombieProcesses = ['node', 'python', 'python3', 'ruby', 'java', 'deno'];
+  
+  const zombies = ports.filter(p => 
+    zombieProcesses.some(name => p.process.toLowerCase().includes(name))
+  );
+
+  return zombies;
+}
+
+/**
+ * Format and display ports
+ */
+export function displayPorts(ports) {
+  if (ports.length === 0) {
+    console.log(chalk.yellow('No active ports found'));
+    return;
+  }
+
+  console.log(chalk.bold('\n🔒 Active Ports:\n'));
+  
+  const header = `${chalk.bold('PORT').padEnd(10)} ${chalk.bold('PID').padEnd(10)} ${chalk.bold('PROCESS').padEnd(20)} ${chalk.bold('ADDRESS')}`;
+  console.log(header);
+  console.log('─'.repeat(70));
+
+  for (const port of ports) {
+    const portStr = chalk.cyan(port.port.toString().padEnd(10));
+    const pidStr = chalk.yellow(port.pid.toString().padEnd(10));
+    const processStr = chalk.green(port.process.padEnd(20));
+    const addressStr = chalk.gray(port.address);
+
+    console.log(`${portStr}${pidStr}${processStr}${addressStr}`);
+  }
+
+  console.log('');
+}
+
+/**
+ * Display single port info
+ */
+export function displayPortInfo(port, processes) {
+  if (processes.length === 0) {
+    console.log(chalk.yellow(`\nPort ${port} is not in use`));
+    return;
+  }
+
+  console.log(chalk.bold(`\n🔍 Port ${port} details:\n`));
+
+  for (const proc of processes) {
+    console.log(chalk.cyan('  Port:    ') + proc.port);
+    console.log(chalk.yellow('  PID:     ') + proc.pid);
+    console.log(chalk.green('  Process: ') + proc.process);
+    console.log(chalk.gray('  Address: ') + proc.address);
+    console.log('');
+  }
+}
+
+/**
+ * Display port range info
+ */
+export function displayPortRange(rangeInfo) {
+  const { start, end, total, used, free, ports } = rangeInfo;
+  
+  console.log(chalk.bold(`\n📊 Port Range ${start}-${end} Analysis:\n`));
+  
+  console.log(chalk.cyan('  Range:       ') + `${start} - ${end}`);
+  console.log(chalk.yellow('  Total ports: ') + total);
+  console.log(chalk.green('  Free ports:  ') + free);
+  console.log(chalk.red('  Used ports:  ') + used);
+  
+  if (used > 0) {
+    console.log(chalk.bold('\n🔒 Active Ports in Range:\n'));
+    
+    const header = `${chalk.bold('PORT').padEnd(10)} ${chalk.bold('PID').padEnd(10)} ${chalk.bold('PROCESS').padEnd(20)} ${chalk.bold('ADDRESS')}`;
+    console.log(header);
+    console.log('─'.repeat(70));
+
+    for (const port of ports) {
+      const portStr = chalk.cyan(port.port.toString().padEnd(10));
+      const pidStr = chalk.yellow(port.pid.toString().padEnd(10));
+      const processStr = chalk.green(port.process.padEnd(20));
+      const addressStr = chalk.gray(port.address);
+
+      console.log(`${portStr}${pidStr}${processStr}${addressStr}`);
+    }
+  } else {
+    console.log(chalk.green('\n✓ All ports in this range are free!'));
+  }
+  
+  console.log('');
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "portguard",
+  "version": "0.1.1",
+  "description": "Monitor and manage localhost ports - kill zombie processes and prevent port conflicts",
+  "main": "lib/portguard.js",
+  "bin": {
+    "portguard": "bin/portguard.js"
+  },
+  "scripts": {
+    "test": "node test/test.js"
+  },
+  "keywords": [
+    "port",
+    "localhost",
+    "process",
+    "monitor",
+    "cli",
+    "developer-tools",
+    "kill-port",
+    "eaddrinuse",
+    "lsof",
+    "zombie",
+    "devtools",
+    "port-scanner",
+    "port-killer",
+    "network",
+    "tcp",
+    "port-conflict",
+    "port-management",
+    "process-manager",
+    "cleanup"
+  ],
+  "homepage": "https://github.com/muin-company/portguard#readme",
+  "author": "muin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/muin-company/portguard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/muin-company/portguard/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0"
+  },
+  "type": "module"
+}