port-hunter-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rebebuca contributors
+
+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,52 @@
+# port-hunter-cli
+
+Interactive terminal UI to list TCP listening ports (with project / command hints on macOS) and kill selected processes. Works on macOS, Linux, and Windows.
+
+## Install (global)
+
+```bash
+npm install -g port-hunter-cli
+```
+
+With pnpm:
+
+```bash
+pnpm add -g port-hunter-cli
+```
+
+## Usage
+
+```bash
+port-hunter          # mouse + keyboard TUI
+port-hunter --once   # print table once, then exit
+port-hunter --help
+```
+
+### TUI shortcuts
+
+- **Mouse**: click a row to toggle selection; bottom buttons for refresh / kill / quit.
+- **Space**: toggle the focused row.
+- **Enter** or **click the same row again**: toggle selection (blessed `action`).
+- **g** / **Kill(g)**: graceful kill (SIGTERM / `taskkill`).
+- **f** / **Force(f)**: force kill (SIGKILL / `taskkill /F`).
+- **r** / **Refresh**: rescan ports.
+- **q** / **Quit**: exit.
+
+## Requirements
+
+- Node.js **18+**
+- Port discovery uses `lsof` / `ss` (Unix) or `netstat` (Windows). Process details on non-macOS Unix are best-effort compared to macOS.
+
+## Publish (maintainers)
+
+```bash
+cd port-hunter-cli
+npm login
+npm publish --access public
+```
+
+Use `npm version patch|minor|major` before publishing when bumping versions.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "port-hunter-cli",
+  "version": "1.0.0",
+  "description": "Interactive terminal UI to list and kill processes listening on TCP ports (macOS, Linux, Windows)",
+  "type": "module",
+  "bin": {
+    "port-hunter": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node ./src/index.js",
+    "prepublishOnly": "node --check ./src/index.js"
+  },
+  "keywords": [
+    "port",
+    "kill-port",
+    "lsof",
+    "netstat",
+    "cli",
+    "tui",
+    "blessed",
+    "process",
+    "devtools"
+  ],
+  "license": "MIT",
+  "author": "Rebebuca contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/langhuihui/rebebuca.git",
+    "directory": "port-hunter-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/langhuihui/rebebuca/issues"
+  },
+  "homepage": "https://github.com/langhuihui/rebebuca/tree/main/port-hunter-cli#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "blessed": "^0.1.81",
+    "chalk": "^5.4.1",
+    "cli-table3": "^0.6.5"
+  }
+}

package/src/index.js

@@ -0,0 +1,561 @@
+#!/usr/bin/env node
+
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import Table from 'cli-table3';
+import blessed from 'blessed';
+import chalk from 'chalk';
+
+const execFileAsync = promisify(execFile);
+const EXEC_TIMEOUT_MS = 15000;
+const argv = process.argv.slice(2);
+
+function runCommand(command, args, timeout = EXEC_TIMEOUT_MS) {
+  return execFileAsync(command, args, {
+    timeout,
+    windowsHide: true,
+    maxBuffer: 1024 * 1024 * 8,
+  });
+}
+
+function formatMemory(rssKB) {
+  if (rssKB > 1048576) return `${(rssKB / 1048576).toFixed(1)}G`;
+  if (rssKB > 1024) return `${(rssKB / 1024).toFixed(1)}M`;
+  return `${rssKB}K`;
+}
+
+function findProjectRoot(dir) {
+  const markers = ['package.json', 'Cargo.toml', 'go.mod', 'pyproject.toml', 'Gemfile'];
+  let current = dir;
+  let depth = 0;
+  while (current !== '/' && current !== path.dirname(current) && depth < 15) {
+    for (const marker of markers) {
+      if (fs.existsSync(path.join(current, marker))) return current;
+    }
+    current = path.dirname(current);
+    depth += 1;
+  }
+  return dir;
+}
+
+function detectFramework(projectRoot, command = '', processName = '') {
+  const cmd = String(command || '').toLowerCase();
+  if (cmd.includes('next')) return 'Next.js';
+  if (cmd.includes('vite')) return 'Vite';
+  if (cmd.includes('nuxt')) return 'Nuxt';
+  if (cmd.includes('webpack')) return 'Webpack';
+  if (cmd.includes('flask')) return 'Flask';
+  if (cmd.includes('django')) return 'Django';
+  if (cmd.includes('rails')) return 'Rails';
+  const pkgPath = path.join(projectRoot || '', 'package.json');
+  if (projectRoot && fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if (deps.next) return 'Next.js';
+      if (deps.vite) return 'Vite';
+      if (deps.nuxt || deps.nuxt3) return 'Nuxt';
+      if (deps.react) return 'React';
+      if (deps.vue) return 'Vue';
+      if (deps.express) return 'Express';
+    } catch {
+      // Ignore parse errors.
+    }
+  }
+  const lowerName = String(processName || '').toLowerCase();
+  if (lowerName === 'node') return 'Node.js';
+  if (lowerName.startsWith('python')) return 'Python';
+  if (lowerName === 'java') return 'Java';
+  return '-';
+}
+
+async function listPortsUnixRaw() {
+  const platform = os.platform();
+  const portMap = new Map();
+  if (platform !== 'darwin') {
+    try {
+      const { stdout } = await runCommand('ss', ['-tlnp']);
+      for (const line of stdout.split('\n').slice(1)) {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length < 4) continue;
+        const localAddr = parts[3];
+        const portMatch = localAddr.match(/:(\d+)$/);
+        if (!portMatch) continue;
+        const port = parseInt(portMatch[1], 10);
+        if (portMap.has(port)) continue;
+        const pidMatch = line.match(/pid=(\d+)/);
+        const procMatch = line.match(/users:\(\("([^"]+)"/);
+        if (port > 0) {
+          portMap.set(port, {
+            port,
+            pid: pidMatch ? parseInt(pidMatch[1], 10) : 0,
+            process: procMatch ? procMatch[1] : '',
+            protocol: 'tcp',
+          });
+        }
+      }
+      if (portMap.size > 0) return [...portMap.values()];
+    } catch {
+      // Fallback to lsof.
+    }
+  }
+  const { stdout } = await runCommand('lsof', ['-iTCP', '-sTCP:LISTEN', '-n', '-P']);
+  for (const line of stdout.split('\n').slice(1)) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 9) continue;
+    const processName = parts[0];
+    const pid = parseInt(parts[1], 10);
+    const addrPort = parts[8];
+    const portMatch = addrPort.match(/:(\d+)$/);
+    if (!portMatch) continue;
+    const port = parseInt(portMatch[1], 10);
+    if (port > 0 && !portMap.has(port)) {
+      portMap.set(port, { port, pid, process: processName, protocol: 'tcp' });
+    }
+  }
+  return [...portMap.values()];
+}
+
+async function listPortsWindowsRaw() {
+  const portMap = new Map();
+  const { stdout } = await runCommand('netstat', ['-ano']);
+  for (const line of stdout.split('\n')) {
+    const parts = line.trim().split(/\s+/);
+    if (parts[0] !== 'TCP' || parts[3] !== 'LISTENING') continue;
+    const portMatch = parts[1].match(/:(\d+)$/);
+    if (!portMatch) continue;
+    const port = parseInt(portMatch[1], 10);
+    const pid = parseInt(parts[4], 10);
+    if (port > 0 && !portMap.has(port)) {
+      portMap.set(port, { port, pid, process: 'unknown', protocol: 'tcp' });
+    }
+  }
+  return [...portMap.values()];
+}
+
+const PS_LINE = /^(\d+)\s+(\d+)\s+(\S+)\s+(\d+)\s+(\S+)\s+(.*)$/;
+
+async function batchProcessInfoDarwin(pids) {
+  const map = new Map();
+  if (pids.length === 0) return map;
+  const { stdout } = await runCommand(
+    'ps',
+    ['-ww', '-p', pids.join(','), '-o', 'pid=,ppid=,stat=,rss=,etime=,command='],
+    10000,
+  );
+  for (const line of stdout.trim().split('\n')) {
+    const m = line.trim().match(PS_LINE);
+    if (!m) continue;
+    map.set(parseInt(m[1], 10), {
+      ppid: parseInt(m[2], 10),
+      stat: m[3],
+      rss: parseInt(m[4], 10),
+      etime: m[5],
+      command: m[6],
+    });
+  }
+  return map;
+}
+
+async function batchCwdDarwin(pids) {
+  const map = new Map();
+  if (pids.length === 0) return map;
+  try {
+    const { stdout } = await runCommand('lsof', ['-a', '-d', 'cwd', '-p', pids.join(',')], 10000);
+    for (const line of stdout.trim().split('\n').slice(1)) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length < 9) continue;
+      const pid = parseInt(parts[1], 10);
+      const cwdPath = parts.slice(8).join(' ');
+      if (cwdPath && cwdPath.startsWith('/')) map.set(pid, cwdPath);
+    }
+  } catch {
+    // Best effort.
+  }
+  return map;
+}
+
+async function enrichRows(rawRows) {
+  const pids = [...new Set(rawRows.map((r) => r.pid).filter((p) => p > 0))];
+  let psMap = new Map();
+  let cwdMap = new Map();
+  if (os.platform() === 'darwin') {
+    psMap = await batchProcessInfoDarwin(pids);
+    cwdMap = await batchCwdDarwin(pids);
+  }
+
+  return rawRows.map((row) => {
+    const ps = psMap.get(row.pid);
+    const cwdRaw = cwdMap.get(row.pid);
+    const command = ps?.command || '';
+    const root = cwdRaw ? findProjectRoot(cwdRaw) : '';
+    const project = root ? path.basename(root) : '-';
+    const status = ps?.stat?.includes('Z') ? 'zombie' : 'healthy';
+    return {
+      ...row,
+      command,
+      cwd: root || '-',
+      project,
+      framework: detectFramework(root, command, row.process),
+      uptime: ps?.etime || '-',
+      memory: ps?.rss ? formatMemory(ps.rss) : '-',
+      status,
+    };
+  });
+}
+
+async function listPortsDetailed() {
+  const raw = os.platform() === 'win32' ? await listPortsWindowsRaw() : await listPortsUnixRaw();
+  const rows = await enrichRows(raw);
+  return rows.sort((a, b) => a.port - b.port);
+}
+
+async function killPid(pid, force) {
+  if (pid === process.pid) throw new Error(`Refusing to kill current process ${pid}`);
+  if (os.platform() === 'win32') {
+    await runCommand('taskkill', force ? ['/F', '/PID', String(pid)] : ['/PID', String(pid)]);
+    return;
+  }
+  process.kill(pid, force ? 'SIGKILL' : 'SIGTERM');
+}
+
+/** Blessed treats `{` / `}` as inline tags; strip to avoid parseContent blowing the stack. */
+function blessedPlain(text) {
+  return String(text).replace(/\{/g, '\uFF5B').replace(/\}/g, '\uFF5D');
+}
+
+/**
+ * blessed uses its own EventEmitter (no `prependListener`). Run `listener` before existing ones.
+ */
+function prependBlessedListener(emitter, type, listener) {
+  if (typeof emitter.prependListener === 'function') {
+    emitter.prependListener(type, listener);
+    return;
+  }
+  if (!emitter._events) emitter._events = {};
+  const existing = emitter._events[type];
+  if (!existing) {
+    emitter.on(type, listener);
+    return;
+  }
+  if (typeof existing === 'function') {
+    emitter._events[type] = [listener, existing];
+  } else {
+    existing.unshift(listener);
+  }
+  if (typeof emitter._emit === 'function') {
+    emitter._emit('newListener', [type, listener]);
+  }
+}
+
+function formatRowLine(row, selected) {
+  const mark = selected ? '[x]' : '[ ]';
+  const command = blessedPlain((row.command || '-').slice(0, 28));
+  const processName = blessedPlain((row.process || '-').slice(0, 14));
+  const project = blessedPlain((row.project || '-').slice(0, 14));
+  const framework = blessedPlain((row.framework || '-').slice(0, 10));
+  return `${mark} ${String(row.port).padEnd(5)} ${String(row.pid).padEnd(7)} ${processName.padEnd(14)} ${project.padEnd(14)} ${framework.padEnd(10)} ${String(row.uptime || '-').padEnd(10)} ${String(row.memory || '-').padEnd(8)} ${blessedPlain(row.status || '-').padEnd(8)} ${command}`;
+}
+
+function tableHeaderLine() {
+  return '[ ] Port  PID     Process        Project        Framework  Uptime     Memory   Status   Command';
+}
+
+function printTableOnce(rows) {
+  const table = new Table({
+    head: [
+      chalk.cyan('Port'),
+      chalk.cyan('PID'),
+      chalk.cyan('Process'),
+      chalk.cyan('Project'),
+      chalk.cyan('Framework'),
+      chalk.cyan('Uptime'),
+      chalk.cyan('Memory'),
+      chalk.cyan('Status'),
+      chalk.cyan('Command'),
+    ],
+    style: { head: [], border: [] },
+    wordWrap: true,
+  });
+  for (const row of rows) {
+    table.push([
+      row.port,
+      row.pid || '-',
+      row.process || '-',
+      row.project || '-',
+      row.framework || '-',
+      row.uptime || '-',
+      row.memory || '-',
+      row.status || '-',
+      (row.command || '-').slice(0, 40),
+    ]);
+  }
+  console.log(table.toString());
+}
+
+async function runInteractiveTui() {
+  const screen = blessed.screen({
+    smartCSR: true,
+    title: 'Port Hunter CLI',
+    fullUnicode: true,
+  });
+
+  const title = blessed.box({
+    parent: screen,
+    top: 0,
+    left: 0,
+    width: '100%',
+    height: 1,
+    content: ' Port Hunter CLI | Mouse: click row toggle | Space/Enter toggle | g: graceful kill | f: force kill | r: refresh | q: quit ',
+    style: { fg: 'black', bg: 'cyan' },
+  });
+
+  const info = blessed.box({
+    parent: screen,
+    top: 1,
+    left: 0,
+    width: '100%',
+    height: 1,
+    content: ' Loading...',
+    style: { fg: 'yellow' },
+  });
+
+  const list = blessed.list({
+    parent: screen,
+    top: 2,
+    left: 0,
+    width: '100%',
+    height: '100%-4',
+    keys: true,
+    mouse: true,
+    vi: true,
+    tags: false,
+    border: 'line',
+    style: {
+      selected: { bg: 'blue' },
+      item: { fg: 'white' },
+      border: { fg: 'gray' },
+    },
+    scrollbar: { ch: ' ', inverse: true },
+  });
+
+  const status = blessed.box({
+    parent: screen,
+    bottom: 0,
+    left: 0,
+    width: '100%',
+    height: 1,
+    content: ' Ready',
+    style: { fg: 'green' },
+  });
+
+  const btnRefresh = blessed.button({
+    parent: screen,
+    bottom: 0,
+    right: 30,
+    mouse: true,
+    keys: true,
+    shrink: true,
+    padding: { left: 1, right: 1 },
+    content: 'Refresh',
+    style: { bg: 'blue', focus: { bg: 'cyan' }, hover: { bg: 'cyan' } },
+  });
+  const btnKill = blessed.button({
+    parent: screen,
+    bottom: 0,
+    right: 19,
+    mouse: true,
+    keys: true,
+    shrink: true,
+    padding: { left: 1, right: 1 },
+    content: 'Kill(g)',
+    style: { bg: 'yellow', fg: 'black', focus: { bg: 'green' }, hover: { bg: 'green' } },
+  });
+  const btnForce = blessed.button({
+    parent: screen,
+    bottom: 0,
+    right: 8,
+    mouse: true,
+    keys: true,
+    shrink: true,
+    padding: { left: 1, right: 1 },
+    content: 'Force(f)',
+    style: { bg: 'red', focus: { bg: 'magenta' }, hover: { bg: 'magenta' } },
+  });
+  const btnQuit = blessed.button({
+    parent: screen,
+    bottom: 0,
+    right: 0,
+    mouse: true,
+    keys: true,
+    shrink: true,
+    padding: { left: 1, right: 1 },
+    content: 'Quit',
+    style: { bg: 'gray', focus: { bg: 'white', fg: 'black' }, hover: { bg: 'white', fg: 'black' } },
+  });
+
+  let rows = [];
+  const selectedPorts = new Set();
+  /** When true, ignore `select item` from blessed (setItems/select re-emit synchronously). */
+  let ignoreSelectItem = false;
+  /** After arrow / wheel navigation, blessed calls `select()` which emits `select item` — do not treat that as a checkbox toggle. */
+  let skipToggleOnNextSelectItem = false;
+
+  function selectedRows() {
+    const byPort = new Map(rows.map((r) => [r.port, r]));
+    return [...selectedPorts].map((port) => byPort.get(port)).filter(Boolean);
+  }
+
+  function updateList() {
+    ignoreSelectItem = true;
+    try {
+      const items = [tableHeaderLine(), ...rows.map((r) => formatRowLine(r, selectedPorts.has(r.port)))];
+      const prevIdx = list.selected;
+      list.setItems(items);
+      if (items.length > 1) {
+        const nextIdx = prevIdx >= 1 && prevIdx < items.length ? prevIdx : 1;
+        list.select(nextIdx);
+      }
+      info.setContent(
+        blessedPlain(` ${rows.length} ports | selected: ${selectedPorts.size}`),
+      );
+      screen.render();
+    } finally {
+      ignoreSelectItem = false;
+    }
+  }
+
+  async function refresh() {
+    status.setContent(' Scanning ports...');
+    status.style.fg = 'yellow';
+    screen.render();
+    try {
+      rows = await listPortsDetailed();
+      for (const port of [...selectedPorts]) {
+        if (!rows.some((r) => r.port === port)) selectedPorts.delete(port);
+      }
+      status.setContent(` Refreshed: ${rows.length} listening ports`);
+      status.style.fg = 'green';
+      updateList();
+    } catch (error) {
+      status.setContent(` Scan failed: ${error.message || error}`);
+      status.style.fg = 'red';
+      screen.render();
+    }
+  }
+
+  async function killSelected(force) {
+    const targets = selectedRows();
+    if (targets.length === 0) {
+      status.setContent(' No ports selected');
+      status.style.fg = 'yellow';
+      screen.render();
+      return;
+    }
+    let fail = 0;
+    for (const row of targets) {
+      try {
+        await killPid(row.pid, force);
+      } catch {
+        fail += 1;
+      }
+    }
+    status.setContent(
+      ` ${force ? 'Force kill' : 'Graceful kill'} finished: ok=${targets.length - fail}, failed=${fail}`,
+    );
+    status.style.fg = fail > 0 ? 'yellow' : 'green';
+    selectedPorts.clear();
+    await refresh();
+  }
+
+  function toggleCurrent() {
+    if (ignoreSelectItem) return;
+    const idx = list.selected;
+    if (idx <= 0) return;
+    const row = rows[idx - 1];
+    if (!row) return;
+    if (selectedPorts.has(row.port)) selectedPorts.delete(row.port);
+    else selectedPorts.add(row.port);
+    updateList();
+  }
+
+  function markNavigationSelectItem() {
+    skipToggleOnNextSelectItem = true;
+    queueMicrotask(() => {
+      skipToggleOnNextSelectItem = false;
+    });
+  }
+
+  prependBlessedListener(list, 'keypress', (ch, key) => {
+    if (key.name === 'up' || key.name === 'down') markNavigationSelectItem();
+    if (list.options.vi && (key.name === 'k' || key.name === 'j')) markNavigationSelectItem();
+  });
+  prependBlessedListener(list, 'element wheeldown', () => markNavigationSelectItem());
+  prependBlessedListener(list, 'element wheelup', () => markNavigationSelectItem());
+
+  list.on('select item', () => {
+    if (ignoreSelectItem) return;
+    if (skipToggleOnNextSelectItem) return;
+    toggleCurrent();
+  });
+  list.on('action', (_el, index) => {
+    if (ignoreSelectItem) return;
+    if (typeof index !== 'number' || index <= 0) return;
+    toggleCurrent();
+  });
+  list.on('keypress', (_, key) => {
+    if (key.full === 'space') toggleCurrent();
+  });
+
+  screen.key(['q', 'C-c'], () => process.exit(0));
+  screen.key(['r'], () => void refresh());
+  screen.key(['g'], () => void killSelected(false));
+  screen.key(['f'], () => void killSelected(true));
+
+  btnRefresh.on('press', () => void refresh());
+  btnKill.on('press', () => void killSelected(false));
+  btnForce.on('press', () => void killSelected(true));
+  btnQuit.on('press', () => process.exit(0));
+
+  screen.append(title);
+  screen.append(info);
+  screen.append(list);
+  screen.append(status);
+  screen.render();
+  await refresh();
+  list.focus();
+}
+
+function printHelp() {
+  console.log(`
+Port Hunter CLI
+
+Usage:
+  port-hunter               Start mouse-enabled TUI
+  port-hunter --once        Scan and print detailed listening ports once
+  port-hunter --help        Show this help
+`);
+}
+
+async function runOnce() {
+  const rows = await listPortsDetailed();
+  if (rows.length === 0) {
+    console.log('No listening ports found.');
+    return;
+  }
+  printTableOnce(rows);
+}
+
+async function main() {
+  if (argv.includes('--help') || argv.includes('-h')) return printHelp();
+  if (argv.includes('--once')) return runOnce();
+  return runInteractiveTui();
+}
+
+main().catch((error) => {
+  console.error(error?.message || error);
+  process.exit(1);
+});