@hicoders/devkit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hicoders
+
+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,87 @@
+# devkit
+
+**Your terminal toolbelt — the small, annoying dev chores, fixed in a keystroke.**
+
+`devkit` is a set of fast, keyboard-driven terminal tools for everyday development.
+One hub, clean UI, mouse-friendly, no config to get started.
+
+```sh
+bun install -g @hicoders/devkit
+```
+
+Then just run `devkit` — or jump straight to a tool by name.
+
+---
+
+## What you get
+
+### 🔪 Kill whatever's hogging a port
+
+That dreaded `Error: port 3000 is already in use`? Gone.
+
+```sh
+killport 3000          # kill whatever is on port 3000
+killport 3000 8080     # several at once
+killport               # not sure what's running? open the picker
+```
+
+The picker shows what's **actually** listening — grouped into your **apps** and
+**services**, with real project names (not just "node"), auto-refreshing live.
+Select with the keyboard or mouse, hit Enter, done.
+
+> No more `netstat | findstr` → copy PID → `taskkill /F /PID …`. One screen, one keystroke.
+
+### 🚀 Start your projects with one key
+
+Stop `cd`-ing into folders and remembering which script to run.
+
+```sh
+launch                 # pick a project, press Enter
+launch my-app          # or start it straight away
+```
+
+Point `launch` at the folders where your projects live and it finds them all
+automatically — reading `package.json`, `go.mod`, `Cargo.toml`, and
+`pyproject.toml`. Press **Enter** to start a project's default command(s)
+(backend **and** frontend together, streaming logs); Ctrl-C stops everything.
+
+- **Pin** your go-to projects to the top.
+- **Reorder** the list however you like, or sort by what you ran most recently.
+- Press **`a`** to launch a different combo of scripts for a one-off run — it even
+  remembers your last choice.
+- Add projects by auto-detecting a folder, or by hand.
+
+### 🧰 One hub for all of it
+
+```sh
+devkit
+```
+
+A single menu lists every tool. Pick one, use it, and you're back at the menu when
+it exits. Filter with `/`, navigate with arrows or `j`/`k`, press `h` anytime for
+help.
+
+---
+
+## Nice touches
+
+- ⌨️ **Keyboard-first**, but the **mouse works too** — click, hover, scroll, double-click.
+- 🎨 **Themes** — press `t` to cycle; your choice sticks across every tool.
+- 🧠 **Remembers your setup** — pins, order, and preferences persist automatically.
+- ⚡ **Instant** — no build step, snappy native-feeling UI.
+
+## Try it without installing
+
+```sh
+bunx @hicoders/devkit              # the hub
+bunx -p @hicoders/devkit killport 3000
+```
+
+## Requirements
+
+devkit runs on **[Bun](https://bun.com)** (v1.2+). Install Bun first, then install
+devkit — that's the only prerequisite.
+
+## License
+
+[MIT](./LICENSE) © hicoders

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hicoders/devkit",
+  "version": "1.0.0",
+  "description": "A terminal toolbelt of small, daily-use developer tools (killport, launch, ...) with a unified TUI hub.",
+  "type": "module",
+  "license": "MIT",
+  "author": "hicoders (https://www.npmjs.com/~hicoders)",
+  "keywords": [
+    "cli",
+    "tui",
+    "terminal",
+    "toolbelt",
+    "developer-tools",
+    "killport",
+    "launcher",
+    "opentui",
+    "bun"
+  ],
+  "bin": {
+    "devkit": "pkg/tui/devkit.tsx",
+    "killport": "pkg/tui/killport.tsx",
+    "launch": "pkg/tui/launch.tsx"
+  },
+  "files": [
+    "pkg",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "scripts": {
+    "devkit": "bun pkg/tui/devkit.tsx",
+    "launch": "bun pkg/tui/launch.tsx",
+    "killport": "bun pkg/tui/killport.tsx",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.17"
+  },
+  "dependencies": {
+    "@opentui/core": "0.0.0-20260616-38ae4bd9",
+    "@opentui/react": "0.0.0-20260616-38ae4bd9",
+    "react": "^19.2.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/pkg/core/appname.ts

@@ -0,0 +1,206 @@
+// appname — resolve a friendly app name for a process by reading its working
+// directory and walking up to the nearest project file.
+//
+// "node"/"bun"/"python" tell you the runtime, not which app. The app's project
+// dir is the process's current directory (dev servers are launched from the
+// project), so we read the cwd and look upward for a project manifest:
+//   package.json (name) · Cargo.toml · pyproject.toml · go.mod
+//
+// Getting another process's cwd is OS-specific:
+//   - Windows (x64): read it from the process PEB via bun:ffi
+//   - Linux:        readlink /proc/<pid>/cwd
+//   - macOS:        lsof -a -p <pid> -d cwd
+// For processes we can't inspect (elevated / other user) this returns null and
+// the caller just shows the runtime name. Results are cached per pid per session.
+
+import { dlopen, FFIType, ptr } from "bun:ffi";
+import { basename, dirname } from "node:path";
+import { readlinkSync } from "node:fs";
+import { tomlName } from "./manifest";
+
+// ---- native plumbing (lazy + guarded so importing never throws) ----
+
+function initNative() {
+  const k32 = dlopen("kernel32.dll", {
+    OpenProcess: { args: [FFIType.u32, FFIType.i32, FFIType.u32], returns: FFIType.ptr },
+    ReadProcessMemory: {
+      args: [FFIType.ptr, FFIType.u64, FFIType.ptr, FFIType.u64, FFIType.ptr],
+      returns: FFIType.i32,
+    },
+    CloseHandle: { args: [FFIType.ptr], returns: FFIType.i32 },
+  });
+  const ntdll = dlopen("ntdll.dll", {
+    NtQueryInformationProcess: {
+      args: [FFIType.ptr, FFIType.i32, FFIType.ptr, FFIType.u32, FFIType.ptr],
+      returns: FFIType.i32,
+    },
+  });
+  return {
+    OpenProcess: k32.symbols.OpenProcess,
+    ReadProcessMemory: k32.symbols.ReadProcessMemory,
+    CloseHandle: k32.symbols.CloseHandle,
+    NtQueryInformationProcess: ntdll.symbols.NtQueryInformationProcess,
+  };
+}
+
+let nativeInit = false;
+let native: ReturnType<typeof initNative> | null = null;
+
+function getNative() {
+  if (nativeInit) return native;
+  nativeInit = true;
+  if (process.platform !== "win32" || process.arch !== "x64") return (native = null);
+  try {
+    native = initNative();
+  } catch {
+    native = null;
+  }
+  return native;
+}
+
+const PROCESS_QUERY_INFORMATION = 0x0400;
+const PROCESS_VM_READ = 0x0010;
+
+// PEB walk offsets (x64): PROCESS_BASIC_INFORMATION.PebBaseAddress @ 0x08,
+// PEB.ProcessParameters @ 0x20, RTL_USER_PROCESS_PARAMETERS.CurrentDirectory
+// (a UNICODE_STRING: Length @ 0x00, Buffer @ 0x08) @ 0x38.
+function readCwdWindows(pid: number): string | null {
+  const n = getNative();
+  if (!n) return null;
+  const h = n.OpenProcess(PROCESS_QUERY_INFORMATION | PROCESS_VM_READ, 0, pid);
+  if (!h) return null;
+  try {
+    const scratch = new Uint8Array(8);
+    const rpm = (addr: bigint, size: number): Uint8Array | null => {
+      const out = new Uint8Array(size);
+      const ok = n.ReadProcessMemory(h, addr, ptr(out), BigInt(size), ptr(scratch));
+      return ok ? out : null;
+    };
+    const u64 = (b: Uint8Array, off = 0) => new DataView(b.buffer).getBigUint64(off, true);
+
+    const pbi = new Uint8Array(48);
+    if (n.NtQueryInformationProcess(h, 0, ptr(pbi), 48, ptr(scratch)) !== 0) return null;
+    const ppBuf = rpm(u64(pbi, 8) + 0x20n, 8);
+    if (!ppBuf) return null;
+    const cur = rpm(u64(ppBuf) + 0x38n, 16);
+    if (!cur) return null;
+    const len = new DataView(cur.buffer).getUint16(0, true);
+    if (!len) return null;
+    const strBuf = rpm(u64(cur, 8), len);
+    if (!strBuf) return null;
+    const cwd = Buffer.from(strBuf).toString("utf16le").replace(/\\+$/, "");
+    return cwd || null;
+  } catch {
+    return null;
+  } finally {
+    n.CloseHandle(h);
+  }
+}
+
+function readCwdLinux(pid: number): string | null {
+  try {
+    return readlinkSync(`/proc/${pid}/cwd`) || null;
+  } catch {
+    return null;
+  }
+}
+
+async function readCwdDarwin(pid: number): Promise<string | null> {
+  try {
+    const proc = Bun.spawn(["lsof", "-a", "-p", String(pid), "-d", "cwd", "-Fn"], {
+      stdout: "pipe",
+      stderr: "ignore",
+      stdin: "ignore",
+    });
+    const out = await new Response(proc.stdout).text();
+    await proc.exited;
+    for (const line of out.split("\n")) if (line.startsWith("n")) return line.slice(1).trim() || null;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Current working directory of another process, or null if unavailable. */
+export async function readProcessCwd(pid: number): Promise<string | null> {
+  switch (process.platform) {
+    case "win32":
+      return readCwdWindows(pid);
+    case "linux":
+      return readCwdLinux(pid);
+    case "darwin":
+      return readCwdDarwin(pid);
+    default:
+      return null;
+  }
+}
+
+// ---- name resolution (cached per pid for the session) ----
+
+const cache = new Map<number, string | null>();
+
+async function tryRead(path: string): Promise<string | null> {
+  try {
+    return await Bun.file(path).text();
+  } catch {
+    return null;
+  }
+}
+
+// If `dir` holds a known project manifest, return its app name (or the folder
+// name as a fallback); return null when there's no manifest here.
+async function nameFromManifest(dir: string): Promise<string | null> {
+  const base = dir.replace(/\\/g, "/");
+  const folder = basename(dir);
+
+  const pj = await tryRead(`${base}/package.json`);
+  if (pj !== null) {
+    try {
+      const n = JSON.parse(pj)?.name;
+      if (typeof n === "string" && n) return n;
+    } catch {
+      /* malformed package.json — fall through to folder name */
+    }
+    return folder;
+  }
+
+  const cargo = await tryRead(`${base}/Cargo.toml`);
+  if (cargo !== null) return tomlName(cargo, "package") ?? folder;
+
+  const py = await tryRead(`${base}/pyproject.toml`);
+  if (py !== null) return tomlName(py, "project") ?? tomlName(py, "tool\\.poetry") ?? folder;
+
+  const gomod = await tryRead(`${base}/go.mod`);
+  if (gomod !== null) {
+    const m = gomod.match(/^\s*module\s+(\S+)/m);
+    return m ? m[1]!.split("/").pop()! : folder;
+  }
+
+  return null;
+}
+
+async function projectNameAbove(startDir: string): Promise<string | null> {
+  let dir = startDir;
+  for (let i = 0; i < 8 && dir; i++) {
+    const name = await nameFromManifest(dir);
+    if (name) return name;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Friendly app name for a process (from package.json / Cargo.toml /
+ * pyproject.toml / go.mod, or the project folder), or null if it can't be
+ * determined. Cached per pid for the session.
+ */
+export async function resolveAppName(pid: number): Promise<string | null> {
+  if (cache.has(pid)) return cache.get(pid)!;
+  let name: string | null = null;
+  const cwd = await readProcessCwd(pid);
+  if (cwd) name = await projectNameAbove(cwd);
+  cache.set(pid, name);
+  return name;
+}

package/pkg/core/config.ts

@@ -0,0 +1,34 @@
+// config — tiny persisted settings for devkit, shared across all tools.
+//
+// Pure logic (no UI): reads/writes a single JSON file in the user's home dir, so
+// a preference chosen in one tool (e.g. the theme) sticks and applies to every
+// tool, including across the hub spawning each tool as its own process.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { LaunchConfig } from "./launch";
+
+const CONFIG_PATH = join(homedir(), ".devkit.json");
+
+export interface DevkitConfig {
+  theme?: string;
+  /** The `launch` tool's project registry + scan roots. */
+  launch?: LaunchConfig;
+}
+
+export function loadConfig(): DevkitConfig {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf8")) as DevkitConfig;
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(patch: Partial<DevkitConfig>): void {
+  try {
+    writeFileSync(CONFIG_PATH, JSON.stringify({ ...loadConfig(), ...patch }, null, 2));
+  } catch {
+    /* best-effort — a missing setting just falls back to defaults */
+  }
+}

package/pkg/core/killport.ts

@@ -0,0 +1,273 @@
+// killport core — discover TCP listeners and kill processes by PID.
+//
+// Pure logic only: no terminal UI, no console output. The TUI layer
+// (pkg/tui/killport.tsx) and any future GUI both build on these functions.
+//
+// Windows-only. Listeners are gathered from two commands run in parallel:
+//   - native `netstat -ano` (~15ms) for port → pid → state, and
+//   - one `Get-Process` (PowerShell) for pid → name + exe path.
+// Joining them avoids the slow `Get-NetTCPConnection` cmdlet (~500ms) and the
+// per-connection `Get-Process` calls the first version used (~1s total).
+// Kills go through `taskkill`.
+
+import { homedir } from "node:os";
+
+export type PortCategory = "app" | "service" | "other";
+
+export interface Listener {
+  port: number;
+  pid: number;
+  name: string; // ACTUAL process name from the OS, e.g. "node" — always primary
+  path: string | null; // full exe path when readable (null for protected/system)
+  system: boolean; // true => protected, must not be killed
+  category: PortCategory; // which section this port belongs to
+  portLabel?: string; // conventional use of the port, e.g. "MySQL" — hint only
+}
+
+export interface KillResult {
+  pid: number;
+  ok: boolean;
+  error?: string;
+}
+
+// Conventional uses of well-known ports. This is ONLY used to (a) sort ports
+// into sections and (b) show a dim hint — it never overrides the real process
+// name, so something other than MySQL on 3306 still shows its true name.
+const PORT_CATALOG: Record<number, { label: string; category: "app" | "service" }> = {
+  // app / dev servers
+  3000: { label: "dev server", category: "app" },
+  3001: { label: "dev server", category: "app" },
+  4173: { label: "Vite preview", category: "app" },
+  4200: { label: "Angular", category: "app" },
+  4321: { label: "Astro", category: "app" },
+  5000: { label: "dev server", category: "app" },
+  8000: { label: "dev server", category: "app" },
+  8080: { label: "HTTP alt", category: "app" },
+  8081: { label: "HTTP alt", category: "app" },
+  1420: { label: "Tauri", category: "app" },
+  19006: { label: "Expo", category: "app" },
+  // services / infra
+  1433: { label: "SQL Server", category: "service" },
+  2181: { label: "Zookeeper", category: "service" },
+  3306: { label: "MySQL", category: "service" },
+  5432: { label: "PostgreSQL", category: "service" },
+  5672: { label: "RabbitMQ", category: "service" },
+  5984: { label: "CouchDB", category: "service" },
+  6379: { label: "Redis", category: "service" },
+  9092: { label: "Kafka", category: "service" },
+  9200: { label: "Elasticsearch", category: "service" },
+  11211: { label: "Memcached", category: "service" },
+  27017: { label: "MongoDB", category: "service" },
+};
+
+// Inclusive port ranges with a shared conventional use.
+const RANGE_CATALOG: { from: number; to: number; label: string; category: "app" | "service" }[] = [
+  { from: 5173, to: 5190, label: "Vite", category: "app" },
+];
+
+/** Conventional category + label for a port from the catalog (port-only). */
+export function portInfo(port: number): { category: "app" | "service" | null; label?: string } {
+  const exact = PORT_CATALOG[port];
+  if (exact) return exact;
+  for (const r of RANGE_CATALOG) {
+    if (port >= r.from && port <= r.to) return { category: r.category, label: r.label };
+  }
+  return { category: null };
+}
+
+// Programming-language runtimes / dev tooling. A process with one of these names
+// is "something I'm running" → grouped under APPS, regardless of port. (Compiled
+// Go/Rust/etc. binaries get an arbitrary exe name, so those are caught instead by
+// the dev-path heuristic below.)
+const RUNTIME_NAMES = new Set([
+  "node", "bun", "deno", "tsx", "ts-node", "nodemon",
+  "python", "python3", "pythonw", "py",
+  "ruby", "rubyw", "php",
+  "java", "javaw", "dotnet",
+  "go", "cargo", "rustc", "air",
+  "elixir", "erl", "dart", "flutter", "perl",
+  "uvicorn", "gunicorn", "hypercorn",
+]);
+
+// Database / infrastructure daemons → grouped under SERVICES.
+const SERVICE_NAMES = new Set([
+  "mysqld", "mariadbd", "postgres", "pg_ctl", "mongod",
+  "redis-server", "redis", "memcached", "sqlservr", "oracle",
+  "cassandra", "influxd", "couchdb", "rabbitmq", "rabbitmq-server",
+  "docker", "dockerd", "com.docker.backend",
+]);
+
+// True when an exe lives in one of the user's own dev locations (scoop, .cargo,
+// go/bin, project/target dirs, go-build temp) — i.e. something the user built or
+// runs themselves. This is what lets a compiled Go/Rust binary with an arbitrary
+// name land in APPS. We deliberately exclude the AppData subtree so installed
+// Electron/GUI apps (VS Code, Discord, Slack…) don't masquerade as dev servers —
+// except AppData\Local\Temp, where `go run` drops its compiled binaries.
+const HOME = (homedir() || "").toLowerCase();
+function isDevPath(path: string | null): boolean {
+  if (!path || !HOME) return false;
+  const p = path.toLowerCase();
+  if (!p.startsWith(HOME)) return false;
+  const rel = p.slice(HOME.length);
+  if (rel.includes("\\appdata\\")) return rel.includes("\\appdata\\local\\temp\\");
+  return true;
+}
+
+/**
+ * Decide which section a listener belongs to, from the actual process + port.
+ * APPS first (dev runtime name OR a user-owned exe path), so "anything I run"
+ * floats to the top; then SERVICES (known daemon name or service port); the
+ * catalog is also consulted for the dim port-use hint.
+ */
+export function classify(p: { port: number; name: string; path: string | null }): {
+  category: PortCategory;
+  label?: string;
+} {
+  const name = p.name.toLowerCase();
+  const { category: portCat, label } = portInfo(p.port);
+
+  if (RUNTIME_NAMES.has(name) || isDevPath(p.path)) return { category: "app", label };
+  if (SERVICE_NAMES.has(name) || portCat === "service") return { category: "service", label };
+  if (portCat === "app") return { category: "app", label }; // well-known dev port, unknown proc
+  return { category: "other", label };
+}
+
+// PIDs / process names that belong to Windows itself. These are flagged
+// `system: true` and treated as protected — a "free up my dev port" tool
+// should never invite killing core OS processes (their ports are RPC/SMB/etc).
+const SYSTEM_PIDS = new Set([0, 4]);
+const SYSTEM_NAMES = new Set([
+  "system",
+  "idle",
+  "system idle process",
+  "registry",
+  "svchost",
+  "lsass",
+  "services",
+  "wininit",
+  "winlogon",
+  "csrss",
+  "smss",
+  "spoolsv",
+]);
+
+// One Get-Process call maps every pid to its name + exe path as compact JSON.
+// `Path` is null for processes we can't open (system / other-session) — a useful
+// "don't touch this" signal that also keeps them out of APPS.
+const PS_PROCS = "Get-Process | Select-Object Id,ProcessName,Path | ConvertTo-Json -Compress";
+
+interface ProcRow {
+  Id: number;
+  ProcessName: string | null;
+  Path: string | null;
+}
+
+async function runCapture(cmd: string[]): Promise<{ stdout: string; stderr: string; code: number }> {
+  const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe", stdin: "ignore" });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { stdout, stderr, code };
+}
+
+function isSystem(pid: number, name: string): boolean {
+  return SYSTEM_PIDS.has(pid) || SYSTEM_NAMES.has(name.toLowerCase());
+}
+
+// Parse `netstat -ano` rows into { port, pid }, keeping only TCP LISTENING.
+// Rows look like: "  TCP    0.0.0.0:135   0.0.0.0:0   LISTENING   2216"
+// IPv6 rows are "  TCP    [::1]:5178   [::]:0   LISTENING   3144" (also "TCP").
+// UDP rows have no state column (4 fields) so they're filtered out below.
+function parseNetstat(out: string): { port: number; pid: number }[] {
+  const rows: { port: number; pid: number }[] = [];
+  for (const line of out.split(/\r?\n/)) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 5 || parts[0] !== "TCP" || parts[3] !== "LISTENING") continue;
+    const local = parts[1]!;
+    const port = Number(local.slice(local.lastIndexOf(":") + 1));
+    const pid = Number(parts[parts.length - 1]);
+    if (Number.isInteger(port) && Number.isInteger(pid)) rows.push({ port, pid });
+  }
+  return rows;
+}
+
+// Parse the Get-Process JSON into a pid → { name, path } map.
+function parseProcs(out: string): Map<number, { name: string; path: string | null }> {
+  const map = new Map<number, { name: string; path: string | null }>();
+  const raw = out.trim();
+  if (!raw) return map;
+  let parsed: ProcRow | ProcRow[];
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return map;
+  }
+  for (const r of Array.isArray(parsed) ? parsed : [parsed]) {
+    if (r && typeof r.Id === "number") {
+      map.set(r.Id, { name: r.ProcessName ?? "(unknown)", path: r.Path ?? null });
+    }
+  }
+  return map;
+}
+
+/** All TCP ports currently in the LISTEN state, sorted by port then pid. */
+export async function listListeners(): Promise<Listener[]> {
+  // Run the fast native port scan and the process lookup concurrently.
+  // Plain `netstat -ano` (no `-p TCP`!) is used on purpose: `-p TCP` lists only
+  // IPv4, dropping IPv6-only listeners like Vite/Node on [::1]. Both IPv4 and
+  // IPv6 TCP rows are labelled "TCP" by netstat, so the parser handles both.
+  const [net, procs] = await Promise.all([
+    runCapture(["netstat", "-ano"]).then((r) => parseNetstat(r.stdout)),
+    runCapture(["powershell", "-NoProfile", "-NonInteractive", "-Command", PS_PROCS]).then((r) =>
+      parseProcs(r.stdout),
+    ),
+  ]);
+
+  const seen = new Set<string>();
+  const listeners: Listener[] = [];
+  for (const { port, pid } of net) {
+    const key = `${port}:${pid}`;
+    if (seen.has(key)) continue; // collapse IPv4 + IPv6 duplicates of the same socket
+    seen.add(key);
+    const proc = procs.get(pid);
+    const name = proc?.name ?? "(unknown)";
+    const path = proc?.path ?? null;
+    const { category, label } = classify({ port, name, path });
+    listeners.push({
+      port,
+      pid,
+      name,
+      path,
+      system: isSystem(pid, name),
+      category,
+      portLabel: label,
+    });
+  }
+  listeners.sort((a, b) => a.port - b.port || a.pid - b.pid);
+  return listeners;
+}
+
+/** Listeners bound to a specific port. */
+export async function listenersForPort(port: number): Promise<Listener[]> {
+  return (await listListeners()).filter((l) => l.port === port);
+}
+
+/** Force-kill a process (and its child tree) by PID via taskkill. */
+export async function killPid(pid: number): Promise<KillResult> {
+  const { stderr, code } = await runCapture(["taskkill", "/PID", String(pid), "/F", "/T"]);
+  if (code === 0) return { pid, ok: true };
+  return { pid, ok: false, error: stderr.trim() || `taskkill exited with code ${code}` };
+}
+
+/** Parse CLI args into a unique, sorted list of valid port numbers (1-65535). */
+export function parsePorts(args: string[]): number[] {
+  const ports = new Set<number>();
+  for (const a of args) {
+    if (a.startsWith("-")) continue; // skip flags such as -y / --yes
+    const n = Number(a);
+    if (Number.isInteger(n) && n >= 1 && n <= 65535) ports.add(n);
+  }
+  return [...ports].sort((a, b) => a - b);
+}