offmyport 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.2.0] - 2025-12-31
+
+### Added
+
+- GitHub Actions workflows for CI and automated releases
+- Comprehensive unit tests for CLI argument and port parsing
+- Development tooling with vitest test runner
+- Claude Code release command for streamlined releases
+
+### Changed
+
+- Refactored CLI to use meow for argument parsing
+- Improved cross-platform support with dedicated Unix and Windows adapters
+
+## [1.1.0] - 2025-12-31
+
+### Changed
+
+- Internal refactoring and code organization
+
+## [1.0.0] - 2025-12-31
+
+### Added
+
+- Interactive TUI for selecting and killing processes by port
+- Filter by single port, multiple ports (comma-separated), or port ranges
+- Choose between SIGTERM (gentle) or SIGKILL (force) termination
+- `--kill` flag for non-interactive batch killing
+- `--force` flag to skip confirmation prompts
+- `--json` flag for JSON output (scripting/piping)
+- Press `q` to quit during selection
+- Graceful cancellation with Ctrl+C or ESC
+- Cross-platform support (macOS, Linux, Windows)
+- Extended process metadata in JSON output (CPU, memory, path, cwd)

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Helge Sverre
+
+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,168 @@
+# offmyport 🔪
+
+[![npm version](https://img.shields.io/npm/v/offmyport.svg)](https://www.npmjs.com/package/offmyport)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Bun](https://img.shields.io/badge/Bun-%23000000.svg?style=flat&logo=bun&logoColor=white)](https://bun.sh)
+
+Interactive CLI tool to find and kill processes by port. No more memorizing `lsof -i :8080` or `netstat` flags.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Features](#features)
+- [CLI Reference](#cli-reference)
+- [Requirements](#requirements)
+- [License](#license)
+
+## Installation
+
+```bash
+# Using bun (recommended)
+bun install -g offmyport
+
+# Using npm
+npm install -g offmyport
+
+# Run without installing
+npx offmyport
+```
+
+### Install from Source
+
+```shell
+git clone https://github.com/HelgeSverre/offmyport.git
+cd offmyport
+
+# Install dependencies and  make it accessible globally
+bun install
+bun link
+
+```
+
+## Usage
+
+```shell
+# List all listening ports, pick one to kill
+offmyport
+
+# Filter to a specific port
+offmyport 8080
+
+# Filter multiple ports (comma-separated)
+offmyport 80,443,8080
+
+# Filter port ranges (inclusive)
+offmyport 3000-3005
+
+# Mix and match
+offmyport 80,443,3000-3005
+```
+
+### Non-Interactive Mode
+
+```shell
+# Kill all processes on port(s) with confirmation prompt
+offmyport 3000 --kill
+
+# Skip confirmation (use with caution)
+offmyport 3000 --kill --force
+
+# Shorthand flags
+offmyport 3000 -k -f
+```
+
+### JSON Output
+
+```shell
+# Output process info as JSON (no TUI)
+offmyport --json
+
+# Filter and output as JSON
+offmyport 3000-3005 --json
+```
+
+## Features
+
+- Lists all TCP listening ports with process info
+- Interactive selection with arrow keys
+- Choose between SIGTERM (gentle) or SIGKILL (force)
+- Filter by single port, multiple ports, or port ranges
+- Non-interactive mode with `--kill` for scripting
+- JSON output with `--json` for scripting and piping
+- Press `q` to quit during selection
+- Graceful cancellation with Ctrl+C or ESC
+
+## Example
+
+### Interactive Mode
+
+```shell
+$ offmyport 3000
+
+Found 1 listening process (q to quit)
+
+? Select a process to kill:
+❯ Port  3000 │ node            │ PID 12345 │ user
+
+? Kill node (PID 12345) with:
+❯ SIGTERM (gentle - allows cleanup)
+  SIGKILL (force - immediate)
+
+Sent SIGTERM to PID 12345 (node on port 3000)
+```
+
+### Kill Mode
+
+```shell
+$ offmyport 3000-3005 --kill
+
+Processes to kill (3):
+
+  Port  3000 │ node            │ PID 12345 │ user
+  Port  3001 │ python          │ PID 12346 │ user
+  Port  3002 │ ruby            │ PID 12347 │ user
+
+? Kill 3 processes? (y/N)
+```
+
+### JSON Output
+
+```
+$ offmyport 3000 --json
+[
+  {
+    "pid": 12345,
+    "name": "node",
+    "port": 3000,
+    "protocol": "TCP",
+    "user": "helge",
+    "cpuPercent": 0.5,
+    "memoryBytes": 46137344,
+    "startTime": "2025-12-31T10:30:15.000Z",
+    "path": "/usr/local/bin/node server.js",
+    "cwd": "/Users/helge/projects/myapp"
+  }
+]
+```
+
+## CLI Reference
+
+| Flag        | Shorthand | Description                                    |
+| ----------- | --------- | ---------------------------------------------- |
+| `--json`    |           | Output as JSON (no TUI, for scripting)         |
+| `--kill`    | `-k`      | Non-interactive mode, kills matching processes |
+| `--force`   | `-f`      | Skip confirmation prompt (use with `--kill`)   |
+| `--version` | `-v`      | Show version number                            |
+| `--help`    | `-h`      | Show help                                      |
+
+## Requirements
+
+- **macOS**: Works out of the box (uses `lsof`)
+- **Linux**: Uses `lsof` or falls back to `ss` (from iproute2)
+- **Windows**: Requires PowerShell 5.0+ (uses `Get-NetTCPConnection`)
+- Node.js 18+ or Bun
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "offmyport",
+  "version": "1.2.0",
+  "description": "Interactive CLI tool to find and kill processes by port.",
+  "type": "module",
+  "scripts": {
+    "setup": "bun link offmyport",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "bunx prettier --write ."
+  },
+  "bin": {
+    "offmyport": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "cli",
+    "port",
+    "process",
+    "cross-platform",
+    "tui"
+  ],
+  "author": "Helge Sverre <helge.sverre@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HelgeSverre/offmyport.git"
+  },
+  "homepage": "https://github.com/HelgeSverre/offmyport#readme",
+  "bugs": {
+    "url": "https://github.com/HelgeSverre/offmyport/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.5",
+    "@types/node": "^24.10.4",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.1.0",
+    "meow": "^14.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,452 @@
+#!/usr/bin/env bun
+
+import { select, confirm } from "@inquirer/prompts";
+import { ExitPromptError } from "@inquirer/core";
+import * as readline from "readline";
+import meow from "meow";
+import { getAdapter, type ProcessInfo } from "./platform/index.js";
+
+export interface CliFlags {
+  ports: string | null;
+  kill: boolean;
+  force: boolean;
+  murder: boolean; // 🔪 undocumented: uses SIGKILL instead of SIGTERM
+  json: boolean;
+}
+
+const helpText = `
+  Usage
+    $ offmyport [ports] [options]
+
+  Options
+    --kill, -k    Kill matching processes (with confirmation)
+    --force, -f   Skip confirmation prompt (use with --kill)
+    --json        Output process info as JSON (no TUI)
+    --version     Show version number
+    --help        Show this help
+
+  Examples
+    $ offmyport              List all listening ports
+    $ offmyport 3000         Filter to port 3000
+    $ offmyport 80,443       Filter multiple ports
+    $ offmyport 3000-3005    Filter port range
+    $ offmyport 3000 --kill  Kill process on port 3000
+    $ offmyport 3000 -k -f   Kill without confirmation
+    $ offmyport --json       Output all ports as JSON
+`;
+
+/**
+ * Parse CLI arguments using meow.
+ * Exported for testing compatibility.
+ */
+export function parseArgs(argv: string[]): CliFlags {
+  const cli = meow(helpText, {
+    importMeta: import.meta,
+    argv: argv.slice(2), // skip 'bun' and script path
+    flags: {
+      kill: {
+        type: "boolean",
+        shortFlag: "k",
+        default: false,
+      },
+      force: {
+        type: "boolean",
+        shortFlag: "f",
+        default: false,
+      },
+      murder: {
+        type: "boolean",
+        default: false,
+      },
+      json: {
+        type: "boolean",
+        default: false,
+      },
+    },
+    autoHelp: false, // Handle manually to avoid auto-exit during tests
+    autoVersion: false, // Handle manually to avoid auto-exit during tests
+  });
+
+  // Handle --help and --version manually when running as CLI
+  if (import.meta.main) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+      cli.showHelp(0);
+    }
+    if (argv.includes("--version") || argv.includes("-v")) {
+      cli.showVersion();
+    }
+  }
+
+  const murder = cli.flags.murder;
+
+  return {
+    ports: cli.input[0] ?? null,
+    kill: cli.flags.kill || murder, // --murder implies --kill
+    force: cli.flags.force || murder, // --murder implies --force
+    murder,
+    json: cli.flags.json,
+  };
+}
+
+// Calculate page size as half the terminal height (min 5, max 20)
+function getPageSize(): number {
+  const rows = process.stdout.rows || 24;
+  return Math.min(20, Math.max(5, Math.floor(rows / 2)));
+}
+
+/**
+ * Setup keyboard listener for 'q' to quit.
+ * Returns cleanup function and AbortController for cancelling prompts.
+ */
+function setupQuitHandler(): {
+  cleanup: () => void;
+  controller: AbortController;
+} {
+  const controller = new AbortController();
+
+  // Save original raw mode state
+  const wasRaw = process.stdin.isRaw;
+
+  if (process.stdin.isTTY) {
+    readline.emitKeypressEvents(process.stdin);
+
+    const onKeypress = (char: string, key: readline.Key) => {
+      if (char === "q" || char === "Q") {
+        controller.abort();
+      }
+    };
+
+    process.stdin.on("keypress", onKeypress);
+
+    const cleanup = () => {
+      process.stdin.removeListener("keypress", onKeypress);
+    };
+
+    return { cleanup, controller };
+  }
+
+  return { cleanup: () => {}, controller };
+}
+
+// JSON output format (--json flag)
+// Uses common denominator fields across macOS, Linux, and Windows
+export interface ProcessJsonOutput {
+  pid: number;
+  name: string;
+  port: number;
+  protocol: string;
+  user: string;
+  cpuPercent: number | null; // Can be null if unavailable (Windows edge cases)
+  memoryBytes: number | null; // Working set (Win) or RSS (Unix), null if unavailable
+  startTime: string | null; // ISO 8601 format, null if unavailable
+  path: string | null; // Full executable path, null if unavailable (Win 32-bit accessing 64-bit)
+  cwd: string | null; // Current working directory of the process
+}
+
+/**
+ * Parse port specification supporting:
+ * - Single port: "80" → [80]
+ * - Comma-separated: "80,8080,3000" → [80, 8080, 3000]
+ * - Ranges (inclusive): "3000-3005" → [3000, 3001, 3002, 3003, 3004, 3005]
+ * - Mixed: "80,8080,3000-3005" → [80, 8080, 3000, 3001, 3002, 3003, 3004, 3005]
+ */
+export function parsePorts(input: string): number[] {
+  const ports: number[] = [];
+  const segments = input
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  for (const segment of segments) {
+    if (segment.includes("-")) {
+      const rangeParts = segment.split("-").map((s) => s.trim());
+      const startStr = rangeParts[0] ?? "";
+      const endStr = rangeParts[1] ?? "";
+      const start = parseInt(startStr, 10);
+      const end = parseInt(endStr, 10);
+
+      if (isNaN(start) || isNaN(end)) {
+        console.error(`Invalid port range: ${segment}`);
+        process.exit(1);
+      }
+
+      if (start > end) {
+        console.error(`Invalid port range (start > end): ${segment}`);
+        process.exit(1);
+      }
+
+      if (start < 1 || end > 65535) {
+        console.error(`Port out of range (1-65535): ${segment}`);
+        process.exit(1);
+      }
+
+      for (let p = start; p <= end; p++) {
+        ports.push(p);
+      }
+    } else {
+      const port = parseInt(segment, 10);
+
+      if (isNaN(port)) {
+        console.error(`Invalid port number: ${segment}`);
+        process.exit(1);
+      }
+
+      if (port < 1 || port > 65535) {
+        console.error(`Port out of range (1-65535): ${port}`);
+        process.exit(1);
+      }
+
+      ports.push(port);
+    }
+  }
+
+  // Deduplicate and sort
+  return [...new Set(ports)].sort((a, b) => a - b);
+}
+
+// Platform adapter instance (lazy initialized)
+let adapter: ReturnType<typeof getAdapter> | null = null;
+
+function getPlatformAdapter() {
+  if (!adapter) {
+    adapter = getAdapter();
+  }
+  return adapter;
+}
+
+/**
+ * Convert ProcessInfo to ProcessJsonOutput with extended metadata.
+ */
+function toJsonOutput(p: ProcessInfo): ProcessJsonOutput {
+  const platform = getPlatformAdapter();
+  const meta = platform.getProcessMetadata(p.pid);
+  return {
+    pid: p.pid,
+    name: p.command,
+    port: p.port,
+    protocol: p.protocol,
+    user: p.user,
+    cpuPercent: meta.cpuPercent,
+    memoryBytes: meta.memoryBytes,
+    startTime: meta.startTime,
+    path: meta.path,
+    cwd: meta.cwd,
+  };
+}
+
+async function main() {
+  const flags = parseArgs(Bun.argv);
+  const filterPorts = flags.ports ? parsePorts(flags.ports) : null;
+  const platform = getPlatformAdapter();
+
+  let processes = platform.getListeningProcesses();
+
+  if (filterPorts && filterPorts.length > 0) {
+    const portSet = new Set(filterPorts);
+    processes = processes.filter((p) => portSet.has(p.port));
+  }
+
+  // Sort by port
+  processes.sort((a, b) => a.port - b.port);
+
+  // --json mode: output JSON and exit (no TUI)
+  if (flags.json) {
+    const output = processes.map(toJsonOutput);
+    console.log(JSON.stringify(output, null, 2));
+    process.exit(0);
+  }
+
+  if (processes.length === 0) {
+    if (filterPorts && filterPorts.length > 0) {
+      const portDisplay =
+        filterPorts.length === 1
+          ? `port ${filterPorts[0]}`
+          : `ports ${filterPorts.join(", ")}`;
+      console.log(`No process found listening on ${portDisplay}`);
+    } else {
+      console.log("No listening TCP processes found");
+    }
+    process.exit(0);
+  }
+
+  // --kill mode: kill all matching processes without interactive selection
+  if (flags.kill) {
+    await handleKillMode(processes, flags.force, flags.murder, flags.ports);
+    return;
+  }
+
+  // Interactive mode
+  console.log(
+    `\nFound ${processes.length} listening process${processes.length > 1 ? "es" : ""} \x1b[2m(q to quit)\x1b[0m\n`,
+  );
+
+  const pageSize = getPageSize();
+  const { cleanup, controller } = setupQuitHandler();
+
+  let selectedPid: number;
+  let selectedProcess: ProcessInfo;
+
+  try {
+    // Show the list and let user pick
+    selectedPid = await select(
+      {
+        message: "Select a process to kill:",
+        pageSize,
+        choices: processes.map((p) => ({
+          name: `Port ${p.port.toString().padStart(5)} │ ${p.command.padEnd(15)} │ PID ${p.pid} │ ${p.user}`,
+          value: p.pid,
+        })),
+      },
+      { signal: controller.signal },
+    );
+
+    selectedProcess = processes.find((p) => p.pid === selectedPid)!;
+
+    // Ask for kill method
+    const signal = await select(
+      {
+        message: `Kill ${selectedProcess.command} (PID ${selectedPid}) with:`,
+        pageSize: 2,
+        choices: [
+          {
+            name: "SIGTERM (gentle - allows cleanup)",
+            value: "SIGTERM" as const,
+          },
+          { name: "SIGKILL (force - immediate)", value: "SIGKILL" as const },
+        ],
+      },
+      { signal: controller.signal },
+    );
+
+    cleanup();
+
+    platform.killProcess(selectedPid, signal);
+    console.log(
+      `\nSent ${signal} to PID ${selectedPid} (${selectedProcess.command} on port ${selectedProcess.port})`,
+    );
+  } catch (err: any) {
+    cleanup();
+
+    const isAbortError =
+      err instanceof ExitPromptError ||
+      err.name === "AbortError" ||
+      err.code === "ABORT_ERR" ||
+      (typeof err.message === "string" &&
+        err.message.toLowerCase().includes("abort"));
+
+    if (isAbortError) {
+      // User pressed Ctrl+C, ESC, or 'q'
+      console.log("\nCancelled");
+      process.exit(0);
+    }
+    if (err.code === "EPERM") {
+      console.error(
+        `\nPermission denied. Try: sudo offmyport ${flags.ports || ""}`,
+      );
+    } else if (err.code === "ESRCH") {
+      console.error(`\nProcess no longer exists`);
+    } else {
+      console.error(`\nFailed to kill process: ${err.message}`);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Handle --kill mode: kill all matching processes with optional confirmation.
+ */
+async function handleKillMode(
+  processes: ProcessInfo[],
+  force: boolean,
+  murder: boolean,
+  portArg: string | null,
+): Promise<void> {
+  const signal: "SIGTERM" | "SIGKILL" = murder ? "SIGKILL" : "SIGTERM";
+  const platform = getPlatformAdapter();
+
+  // Display what will be killed
+  console.log(`\nProcesses to kill (${processes.length}):\n`);
+  for (const p of processes) {
+    console.log(
+      `  Port ${p.port.toString().padStart(5)} │ ${p.command.padEnd(15)} │ PID ${p.pid} │ ${p.user}`,
+    );
+  }
+  console.log();
+
+  // Require confirmation unless --force is set
+  if (!force) {
+    try {
+      const confirmed = await confirm({
+        message: `Kill ${processes.length} process${processes.length > 1 ? "es" : ""}?`,
+        default: false,
+      });
+
+      if (!confirmed) {
+        console.log("Cancelled");
+        process.exit(0);
+      }
+    } catch (err: any) {
+      const isAbortError =
+        err instanceof ExitPromptError ||
+        err.name === "AbortError" ||
+        err.code === "ABORT_ERR" ||
+        (typeof err.message === "string" &&
+          err.message.toLowerCase().includes("abort"));
+
+      if (isAbortError) {
+        console.log("\nCancelled");
+        process.exit(0);
+      }
+      throw err;
+    }
+  }
+
+  // Kill all processes
+  let killed = 0;
+  let failed = 0;
+
+  for (const p of processes) {
+    try {
+      platform.killProcess(p.pid, signal);
+      if (murder) {
+        console.log(
+          `Process ${p.command} \x1b[91mELIMINATED\x1b[0m! 👁️👅👁️ 🔪`,
+        );
+      } else {
+        console.log(`Killed PID ${p.pid} (${p.command} on port ${p.port})`);
+      }
+      killed++;
+    } catch (err: any) {
+      if (err.code === "EPERM") {
+        console.error(
+          `Permission denied for PID ${p.pid}. Try: sudo offmyport ${portArg || ""} --kill`,
+        );
+      } else if (err.code === "ESRCH") {
+        console.error(`PID ${p.pid} no longer exists`);
+      } else {
+        console.error(`Failed to kill PID ${p.pid}: ${err.message}`);
+      }
+      failed++;
+    }
+  }
+
+  console.log(
+    `\nKilled ${killed} process${killed !== 1 ? "es" : ""}${failed > 0 ? `, ${failed} failed` : ""}`,
+  );
+
+  if (failed > 0) {
+    process.exit(1);
+  }
+}
+
+// Only run when executed directly (not when imported for testing)
+if (import.meta.main) {
+  main().catch((err) => {
+    if (err instanceof ExitPromptError) {
+      console.log("\nCancelled");
+      process.exit(0);
+    }
+    console.error(err);
+    process.exit(1);
+  });
+}

package/src/platform/index.ts

@@ -0,0 +1,16 @@
+import type { PlatformAdapter } from "./types.js";
+import { UnixAdapter } from "./unix.js";
+import { WindowsAdapter } from "./windows.js";
+
+export type { PlatformAdapter, ProcessInfo, ProcessMetadata } from "./types.js";
+
+/**
+ * Get the platform-specific adapter for the current OS.
+ */
+export function getAdapter(): PlatformAdapter {
+  if (process.platform === "win32") {
+    return new WindowsAdapter();
+  }
+  // macOS (darwin) and Linux both use Unix adapter
+  return new UnixAdapter();
+}

package/src/platform/types.ts

@@ -0,0 +1,42 @@
+/**
+ * Process information from port listing.
+ */
+export interface ProcessInfo {
+  command: string;
+  pid: number;
+  user: string;
+  port: number;
+  protocol: string;
+}
+
+/**
+ * Extended process metadata for JSON output.
+ */
+export interface ProcessMetadata {
+  cpuPercent: number | null;
+  memoryBytes: number | null;
+  startTime: string | null;
+  path: string | null;
+  cwd: string | null;
+}
+
+/**
+ * Platform-specific adapter interface.
+ * Implementations exist for Unix (macOS/Linux) and Windows.
+ */
+export interface PlatformAdapter {
+  /**
+   * Get all processes listening on TCP ports.
+   */
+  getListeningProcesses(): ProcessInfo[];
+
+  /**
+   * Get extended metadata for a process.
+   */
+  getProcessMetadata(pid: number): ProcessMetadata;
+
+  /**
+   * Kill a process with the specified signal.
+   */
+  killProcess(pid: number, signal: "SIGTERM" | "SIGKILL"): void;
+}

package/src/platform/unix.ts

@@ -0,0 +1,341 @@
+import type { PlatformAdapter, ProcessInfo, ProcessMetadata } from "./types.js";
+
+/**
+ * Unix (macOS/Linux) platform adapter.
+ * Uses lsof with ss fallback for port discovery.
+ */
+export class UnixAdapter implements PlatformAdapter {
+  /**
+   * Get all processes listening on TCP ports.
+   * Tries lsof first, falls back to ss on Linux.
+   */
+  getListeningProcesses(): ProcessInfo[] {
+    // Try lsof first (available on macOS, usually on Linux)
+    const lsofResult = this.tryLsof();
+    if (lsofResult !== null) {
+      return lsofResult;
+    }
+
+    // Fallback to ss (Linux when lsof unavailable)
+    const ssResult = this.trySs();
+    if (ssResult !== null) {
+      return ssResult;
+    }
+
+    console.error("Neither lsof nor ss available. Install lsof or iproute2.");
+    process.exit(1);
+  }
+
+  /**
+   * Try to get listening processes using lsof.
+   * Returns null if lsof is not available.
+   */
+  private tryLsof(): ProcessInfo[] | null {
+    try {
+      const proc = Bun.spawnSync(["lsof", "-iTCP", "-sTCP:LISTEN", "-P", "-n"]);
+
+      if (proc.exitCode !== 0) {
+        // Check if lsof is not found vs other errors
+        const stderr = proc.stderr.toString();
+        if (stderr.includes("not found") || proc.exitCode === 127) {
+          return null; // lsof not available, try fallback
+        }
+        // lsof exists but failed (e.g., no listening processes)
+        return [];
+      }
+
+      return this.parseLsofOutput(proc.stdout.toString());
+    } catch (err: unknown) {
+      // Bun throws ENOENT when executable not found
+      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Parse lsof output into ProcessInfo array.
+   */
+  private parseLsofOutput(output: string): ProcessInfo[] {
+    const lines = output.split("\n").slice(1); // skip header
+    const processes: ProcessInfo[] = [];
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+
+      const parts = line.split(/\s+/);
+      // COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
+      // node    123 user 45u IPv4 0x123  0t0      TCP  127.0.0.1:3000 (LISTEN)
+
+      const command = parts[0];
+      const pidStr = parts[1];
+      const user = parts[2];
+      const name = parts[8] ?? "";
+
+      if (!command || !pidStr || !user) continue;
+
+      const pid = parseInt(pidStr, 10);
+      if (isNaN(pid)) continue;
+
+      // Extract port from name like "127.0.0.1:3000" or "*:8080"
+      const portMatch = name.match(/:(\d+)$/);
+      if (!portMatch?.[1]) continue;
+
+      const port = parseInt(portMatch[1], 10);
+
+      processes.push({
+        command,
+        pid,
+        user,
+        port,
+        protocol: "TCP",
+      });
+    }
+
+    // Deduplicate by pid+port (same process may have multiple file descriptors)
+    const seen = new Set<string>();
+    return processes.filter((p) => {
+      const key = `${p.pid}:${p.port}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+
+  /**
+   * Try to get listening processes using ss (Linux fallback).
+   * Returns null if ss is not available.
+   */
+  private trySs(): ProcessInfo[] | null {
+    try {
+      // ss -tulnp shows TCP/UDP listening with process info
+      const proc = Bun.spawnSync(["ss", "-tulnp"]);
+
+      if (proc.exitCode !== 0) {
+        const stderr = proc.stderr.toString();
+        if (stderr.includes("not found") || proc.exitCode === 127) {
+          return null; // ss not available
+        }
+        return [];
+      }
+
+      return this.parseSsOutput(proc.stdout.toString());
+    } catch (err: unknown) {
+      // Bun throws ENOENT when executable not found
+      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Parse ss output into ProcessInfo array.
+   * Example line: LISTEN 0 128 *:3000 *:* users:(("node",pid=1234,fd=20))
+   */
+  private parseSsOutput(output: string): ProcessInfo[] {
+    const lines = output.split("\n").slice(1); // skip header
+    const processes: ProcessInfo[] = [];
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+
+      // Only process LISTEN state
+      if (!line.startsWith("LISTEN")) continue;
+
+      // Extract port from local address (4th column)
+      // Format: *:3000 or 0.0.0.0:3000 or [::]:3000
+      const parts = line.split(/\s+/);
+      const localAddr = parts[3] ?? "";
+      const portMatch = localAddr.match(/:(\d+)$/);
+      if (!portMatch?.[1]) continue;
+      const port = parseInt(portMatch[1], 10);
+
+      // Extract process info from users:((... ))
+      // Format: users:(("node",pid=1234,fd=20))
+      const usersMatch = line.match(/users:\(\("([^"]+)",pid=(\d+)/);
+      if (!usersMatch) continue;
+
+      const command = usersMatch[1] ?? "unknown";
+      const pid = parseInt(usersMatch[2] ?? "0", 10);
+      if (isNaN(pid) || pid === 0) continue;
+
+      // ss doesn't show user, get it from /proc
+      const user = this.getProcessUser(pid) ?? "unknown";
+
+      processes.push({
+        command,
+        pid,
+        user,
+        port,
+        protocol: "TCP",
+      });
+    }
+
+    // Deduplicate
+    const seen = new Set<string>();
+    return processes.filter((p) => {
+      const key = `${p.pid}:${p.port}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+
+  /**
+   * Get the user owning a process from /proc on Linux.
+   */
+  private getProcessUser(pid: number): string | null {
+    try {
+      const proc = Bun.spawnSync(["stat", "-c", "%U", `/proc/${pid}`]);
+      if (proc.exitCode === 0) {
+        return proc.stdout.toString().trim();
+      }
+    } catch {
+      // Ignore errors
+    }
+    return null;
+  }
+
+  /**
+   * Get extended metadata for a process.
+   */
+  getProcessMetadata(pid: number): ProcessMetadata {
+    const cwd = this.getProcessCwd(pid);
+
+    try {
+      // ps -p PID -o %cpu=,%mem=,rss=,lstart=,args=
+      const proc = Bun.spawnSync([
+        "ps",
+        "-p",
+        String(pid),
+        "-o",
+        "%cpu=,%mem=,rss=,lstart=,args=",
+      ]);
+
+      if (proc.exitCode !== 0) {
+        return {
+          cpuPercent: null,
+          memoryBytes: null,
+          startTime: null,
+          path: null,
+          cwd,
+        };
+      }
+
+      const output = proc.stdout.toString().trim();
+      if (!output) {
+        return {
+          cpuPercent: null,
+          memoryBytes: null,
+          startTime: null,
+          path: null,
+          cwd,
+        };
+      }
+
+      // Output format varies by locale:
+      // "0.0  0.1  12345 Mon Jan  1 12:00:00 2025     /usr/bin/node server.js"
+      // "0,0  0,1  12345 ons 31 des 06:04:50 2025     /usr/bin/node server.js"
+      // Note: lstart uses multiple spaces before args
+
+      // Parse numbers first (handle both . and , as decimal separator)
+      const parts = output.trim().split(/\s+/);
+      const cpuStr = (parts[0] ?? "").replace(",", ".");
+      const rssStr = parts[2] ?? "";
+
+      const cpuParsed = parseFloat(cpuStr);
+      const cpuPercent = isNaN(cpuParsed) ? null : cpuParsed;
+      const rssKb = parseInt(rssStr, 10) || null;
+
+      // Find the path - it's after the year (4 digits) and multiple spaces
+      // lstart format: "Day Mon DD HH:MM:SS YYYY" then spaces then args
+      const yearMatch = output.match(/\d{4}\s{2,}(.+)$/);
+      const path = yearMatch?.[1]?.trim() ?? null;
+
+      // Extract start time - between RSS and path
+      // parts[3..7] is typically: Day Mon DD HH:MM:SS YYYY
+      let startTime: string | null = null;
+      if (parts.length >= 8) {
+        const dateStr = parts.slice(3, 8).join(" ");
+        try {
+          const date = new Date(dateStr);
+          if (!isNaN(date.getTime())) {
+            startTime = date.toISOString();
+          } else {
+            // Keep raw string for non-English locales
+            startTime = dateStr;
+          }
+        } catch {
+          startTime = dateStr;
+        }
+      }
+
+      return {
+        cpuPercent,
+        memoryBytes: rssKb ? rssKb * 1024 : null,
+        startTime,
+        path,
+        cwd,
+      };
+    } catch {
+      return {
+        cpuPercent: null,
+        memoryBytes: null,
+        startTime: null,
+        path: null,
+        cwd,
+      };
+    }
+  }
+
+  /**
+   * Get the current working directory of a process.
+   * Tries lsof first, falls back to /proc on Linux.
+   */
+  private getProcessCwd(pid: number): string | null {
+    // Try lsof first
+    try {
+      const proc = Bun.spawnSync([
+        "lsof",
+        "-a",
+        "-p",
+        String(pid),
+        "-d",
+        "cwd",
+        "-Fn",
+      ]);
+      if (proc.exitCode === 0) {
+        const output = proc.stdout.toString();
+        // Output format: "p12345\nn/path/to/cwd\n"
+        const match = output.match(/^n(.+)$/m);
+        if (match?.[1]) {
+          return match[1];
+        }
+      }
+    } catch {
+      // Ignore, try fallback
+    }
+
+    // Fallback: read /proc/PID/cwd symlink (Linux only)
+    try {
+      const proc = Bun.spawnSync(["readlink", `/proc/${pid}/cwd`]);
+      if (proc.exitCode === 0) {
+        const cwd = proc.stdout.toString().trim();
+        if (cwd) return cwd;
+      }
+    } catch {
+      // Ignore
+    }
+
+    return null;
+  }
+
+  /**
+   * Kill a process with the specified signal.
+   */
+  killProcess(pid: number, signal: "SIGTERM" | "SIGKILL"): void {
+    process.kill(pid, signal);
+  }
+}

package/src/platform/windows.ts

@@ -0,0 +1,146 @@
+import type { PlatformAdapter, ProcessInfo, ProcessMetadata } from "./types.js";
+
+/**
+ * Windows platform adapter.
+ * Uses PowerShell for port discovery and process metadata.
+ */
+export class WindowsAdapter implements PlatformAdapter {
+  /**
+   * Get all processes listening on TCP ports using PowerShell.
+   */
+  getListeningProcesses(): ProcessInfo[] {
+    // PowerShell script to get listening ports with process info
+    const script = `
+      Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue |
+      ForEach-Object {
+        $proc = Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue
+        [PSCustomObject]@{
+          Port = $_.LocalPort
+          PID = $_.OwningProcess
+          Name = if ($proc) { $proc.ProcessName } else { "unknown" }
+          User = try { (Get-Process -Id $_.OwningProcess -IncludeUserName -ErrorAction SilentlyContinue).UserName } catch { "unknown" }
+        }
+      } | ConvertTo-Json -Compress
+    `;
+
+    const proc = Bun.spawnSync([
+      "powershell",
+      "-NoProfile",
+      "-Command",
+      script,
+    ]);
+
+    if (proc.exitCode !== 0) {
+      console.error("Failed to query listening ports via PowerShell.");
+      process.exit(1);
+    }
+
+    const output = proc.stdout.toString().trim();
+    if (!output || output === "null") {
+      return [];
+    }
+
+    try {
+      const data = JSON.parse(output);
+      // PowerShell returns single object (not array) when only one result
+      const items = Array.isArray(data) ? data : [data];
+
+      return items.map(
+        (item: { Port: number; PID: number; Name: string; User: string }) => ({
+          port: item.Port,
+          pid: item.PID,
+          command: item.Name,
+          user: item.User ?? "unknown",
+          protocol: "TCP",
+        }),
+      );
+    } catch {
+      console.error("Failed to parse PowerShell output.");
+      return [];
+    }
+  }
+
+  /**
+   * Get extended metadata for a process using PowerShell.
+   */
+  getProcessMetadata(pid: number): ProcessMetadata {
+    const script = `
+      $p = Get-Process -Id ${pid} -ErrorAction SilentlyContinue
+      if ($p) {
+        $wmi = Get-WmiObject Win32_Process -Filter "ProcessId = ${pid}" -ErrorAction SilentlyContinue
+        [PSCustomObject]@{
+          CPU = $p.CPU
+          Memory = $p.WorkingSet64
+          StartTime = if ($p.StartTime) { $p.StartTime.ToString("o") } else { $null }
+          Path = $p.Path
+          Cwd = if ($wmi) { Split-Path -Parent $wmi.ExecutablePath -ErrorAction SilentlyContinue } else { $null }
+        } | ConvertTo-Json -Compress
+      } else {
+        "{}"
+      }
+    `;
+
+    try {
+      const proc = Bun.spawnSync([
+        "powershell",
+        "-NoProfile",
+        "-Command",
+        script,
+      ]);
+
+      if (proc.exitCode !== 0) {
+        return this.emptyMetadata();
+      }
+
+      const output = proc.stdout.toString().trim();
+      if (!output || output === "{}" || output === "null") {
+        return this.emptyMetadata();
+      }
+
+      const data = JSON.parse(output);
+
+      return {
+        cpuPercent: typeof data.CPU === "number" ? data.CPU : null,
+        memoryBytes: typeof data.Memory === "number" ? data.Memory : null,
+        startTime: data.StartTime ?? null,
+        path: data.Path ?? null,
+        cwd: data.Cwd ?? null,
+      };
+    } catch {
+      return this.emptyMetadata();
+    }
+  }
+
+  /**
+   * Return empty metadata object.
+   */
+  private emptyMetadata(): ProcessMetadata {
+    return {
+      cpuPercent: null,
+      memoryBytes: null,
+      startTime: null,
+      path: null,
+      cwd: null,
+    };
+  }
+
+  /**
+   * Kill a process with the specified signal.
+   * Uses process.kill which works on Windows for SIGTERM/SIGKILL.
+   */
+  killProcess(pid: number, signal: "SIGTERM" | "SIGKILL"): void {
+    try {
+      process.kill(pid, signal);
+    } catch (err: unknown) {
+      // Fallback to taskkill if process.kill fails
+      const force = signal === "SIGKILL" ? "/F" : "";
+      const args = ["/PID", String(pid)];
+      if (force) args.push(force);
+
+      const proc = Bun.spawnSync(["taskkill", ...args]);
+      if (proc.exitCode !== 0) {
+        throw err; // Re-throw original error
+      }
+    }
+  }
+}