portvac 0.1.0__tar.gz

portvac-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 portvac 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.

portvac-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: portvac
+Version: 0.1.0
+Summary: See what's listening on a TCP port and free it - cross-platform, zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/portvac-py
+Project-URL: Repository, https://github.com/jjdoor/portvac-py
+Project-URL: Issues, https://github.com/jjdoor/portvac-py/issues
+Keywords: port,kill-port,process,lsof,cli,devtools,cross-platform,debugging,sysadmin,zero-dependencies
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# portvac
+
+**See what's listening on a TCP port - and free it.** The "port already in use"
+error costs every developer a minute of `lsof` / `netstat` / `taskkill`
+archaeology. `portvac` lists who's on a port in one command, then vacates it on
+confirm. Cross-platform, **zero dependencies**.
+
+```bash
+pip install portvac
+portvac             # list every listening TCP port
+portvac 3000        # show what's on 3000, then kill it (asks first)
+portvac 3000 -k     # kill without asking (scripts / CI)
+portvac 3000 -s KILL   # SIGKILL instead of the default SIGTERM
+```
+
+Node shop? `npx portvac 3000 -k` works too - same tool, same behaviour.
+
+## Why
+
+> "Port 3000 is already in use" - and now you're pasting `lsof -i :3000` into
+> Stack Overflow for the fourth time this week.
+
+`lsof` flags differ from `netstat` which differs from Windows `taskkill`. You
+remember none of them under pressure. `portvac` is the one command that works
+the same on macOS, Linux, and Windows: **look first, kill second**, never
+silent.
+
+## How it works
+
+1. **List** - shells out to the platform's own tool (`lsof` / `ss` / `netstat`)
+   to read listening sockets. No daemon, no network.
+2. **Show** - prints a clean table: port, pid, process name, address, family.
+3. **Vacate** - on a port argument, asks `y/N`, then sends a signal (default
+   `TERM`) to the owning pid(s). `-k` skips the prompt.
+
+Nothing is installed system-wide and no data leaves your machine.
+
+## Usage
+
+```
+portvac                       List every TCP port currently listening
+portvac <port>                Show what's on <port>, then kill it (asks first)
+portvac <port> --list         Show only, don't kill
+portvac <port> -k             Kill without confirmation
+portvac <port> -s KILL        Send KILL instead of TERM
+portvac --json [<port>]       Machine-readable output (great for piping)
+
+  -k, --force         Kill without confirmation
+  -l, --list          List only; never kill
+  -s, --signal <SIG>  TERM (default), KILL, INT, QUIT, HUP
+      --json          Emit JSON; suppresses colors and prompts
+  -v, --version
+```
+
+### JSON
+
+```bash
+$ portvac --json 3000
+{
+  "port": 3000,
+  "listeners": [
+    { "port": 3000, "pid": 12345, "name": "node", "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4" }
+  ]
+}
+```
+
+## Platform notes
+
+| Platform | Lookup | Kill |
+|----------|--------|------|
+| macOS / BSD | `lsof -iTCP -sTCP:LISTEN -P -n` | `os.kill(pid, sig)` |
+| Linux | `ss -tlnp` (falls back to `netstat -tlnp`) | `os.kill(pid, sig)` |
+| Windows | `netstat -ano` + `tasklist` | `taskkill /PID <pid> /F /T` |
+
+On Windows there's no POSIX signal hierarchy, so `portvac` force-terminates
+(`taskkill /F`). To see another user's processes you may need elevated
+privileges, same as the underlying tools.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | listed, or killed successfully |
+| `1` | nothing listening / port not in use / aborted |
+| `2` | error (bad args, tool missing, kill failed) |
+
+## License
+
+MIT

portvac-0.1.0/README.md

@@ -0,0 +1,89 @@
+# portvac
+
+**See what's listening on a TCP port - and free it.** The "port already in use"
+error costs every developer a minute of `lsof` / `netstat` / `taskkill`
+archaeology. `portvac` lists who's on a port in one command, then vacates it on
+confirm. Cross-platform, **zero dependencies**.
+
+```bash
+pip install portvac
+portvac             # list every listening TCP port
+portvac 3000        # show what's on 3000, then kill it (asks first)
+portvac 3000 -k     # kill without asking (scripts / CI)
+portvac 3000 -s KILL   # SIGKILL instead of the default SIGTERM
+```
+
+Node shop? `npx portvac 3000 -k` works too - same tool, same behaviour.
+
+## Why
+
+> "Port 3000 is already in use" - and now you're pasting `lsof -i :3000` into
+> Stack Overflow for the fourth time this week.
+
+`lsof` flags differ from `netstat` which differs from Windows `taskkill`. You
+remember none of them under pressure. `portvac` is the one command that works
+the same on macOS, Linux, and Windows: **look first, kill second**, never
+silent.
+
+## How it works
+
+1. **List** - shells out to the platform's own tool (`lsof` / `ss` / `netstat`)
+   to read listening sockets. No daemon, no network.
+2. **Show** - prints a clean table: port, pid, process name, address, family.
+3. **Vacate** - on a port argument, asks `y/N`, then sends a signal (default
+   `TERM`) to the owning pid(s). `-k` skips the prompt.
+
+Nothing is installed system-wide and no data leaves your machine.
+
+## Usage
+
+```
+portvac                       List every TCP port currently listening
+portvac <port>                Show what's on <port>, then kill it (asks first)
+portvac <port> --list         Show only, don't kill
+portvac <port> -k             Kill without confirmation
+portvac <port> -s KILL        Send KILL instead of TERM
+portvac --json [<port>]       Machine-readable output (great for piping)
+
+  -k, --force         Kill without confirmation
+  -l, --list          List only; never kill
+  -s, --signal <SIG>  TERM (default), KILL, INT, QUIT, HUP
+      --json          Emit JSON; suppresses colors and prompts
+  -v, --version
+```
+
+### JSON
+
+```bash
+$ portvac --json 3000
+{
+  "port": 3000,
+  "listeners": [
+    { "port": 3000, "pid": 12345, "name": "node", "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4" }
+  ]
+}
+```
+
+## Platform notes
+
+| Platform | Lookup | Kill |
+|----------|--------|------|
+| macOS / BSD | `lsof -iTCP -sTCP:LISTEN -P -n` | `os.kill(pid, sig)` |
+| Linux | `ss -tlnp` (falls back to `netstat -tlnp`) | `os.kill(pid, sig)` |
+| Windows | `netstat -ano` + `tasklist` | `taskkill /PID <pid> /F /T` |
+
+On Windows there's no POSIX signal hierarchy, so `portvac` force-terminates
+(`taskkill /F`). To see another user's processes you may need elevated
+privileges, same as the underlying tools.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | listed, or killed successfully |
+| `1` | nothing listening / port not in use / aborted |
+| `2` | error (bad args, tool missing, kill failed) |
+
+## License
+
+MIT

portvac-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "portvac"
+version = "0.1.0"
+description = "See what's listening on a TCP port and free it - cross-platform, zero dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "yyfjj" }]
+keywords = ["port", "kill-port", "process", "lsof", "cli", "devtools", "cross-platform", "debugging", "sysadmin", "zero-dependencies"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Networking :: Monitoring",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/jjdoor/portvac-py"
+Repository = "https://github.com/jjdoor/portvac-py"
+Issues = "https://github.com/jjdoor/portvac-py/issues"
+
+[project.scripts]
+portvac = "portvac.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

portvac-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

portvac-0.1.0/src/portvac/__init__.py

@@ -0,0 +1,3 @@
+"""portvac - see what's listening on a TCP port and free it. Zero dependencies."""
+
+__version__ = "0.1.0"

portvac-0.1.0/src/portvac/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

portvac-0.1.0/src/portvac/cli.py

@@ -0,0 +1,280 @@
+"""portvac command-line interface. Mirrors bin/cli.js behaviour-for-behaviour."""
+
+import json
+import os
+import re
+import shutil
+import signal
+import subprocess
+import sys
+
+from . import __version__ as VERSION
+from . import core
+
+# ---- tiny color helpers (no dep) ----
+_COLOR = sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def _c(code, s):
+    return f"\x1b[{code}m{s}\x1b[0m" if _COLOR else s
+
+
+def red(s): return _c("31", s)
+def green(s): return _c("32", s)
+def yellow(s): return _c("33", s)
+def dim(s): return _c("2", s)
+def bold(s): return _c("1", s)
+def cyan(s): return _c("36", s)
+
+
+HELP = f"""{bold('portvac')} - see what's listening on a TCP port and free it. Cross-platform, zero deps.
+
+{bold('Usage')}
+  portvac                       List every TCP port currently listening
+  portvac <port>                Show what's on <port>, then kill it (asks first)
+  portvac <port> --list         Show what's on <port> only, don't kill
+  portvac <port> -k             Kill without asking (great for scripts)
+  portvac <port> -s KILL        Use KILL instead of the default TERM
+  portvac --json [<port>]       Machine-readable output
+
+{bold('Flags')}
+  -k, --force         Kill without confirmation
+  -l, --list          List only; never kill
+  -s, --signal <SIG>  Signal to send (TERM, KILL, INT, QUIT, HUP). Default TERM
+      --json          Emit JSON; suppresses colors and prompts
+  -h, --help          Show this help
+  -v, --version       Show version
+
+{bold('Exit codes')}  0 ok · 1 nothing listening / aborted · 2 error
+
+On macOS/BSD it shells out to {cyan('lsof')}; on Linux to {cyan('ss')} (falling back to
+{cyan('netstat')}); on Windows to {cyan('netstat')} + {cyan('taskkill')}. Nothing is installed
+and no data leaves your machine.
+"""
+
+
+def fail(msg):
+    sys.stderr.write(red(f"portvac: {msg}\n"))
+    sys.exit(2)
+
+
+def flag(args, name):
+    """Value after --name, or None."""
+    if name in args:
+        i = args.index(name)
+        if i + 1 < len(args):
+            return args[i + 1]
+    return None
+
+
+def has(args, name):
+    return name in args
+
+
+# ---- platform detection & listener collection -----------------------------
+
+def detect_source() -> str:
+    p = sys.platform
+    if p in ("darwin", "freebsd", "openbsd"):
+        return "lsof"
+    if p == "win32":
+        return "netstat-windows"
+    # linux: prefer ss, fall back to netstat
+    if shutil.which("ss"):
+        return "ss"
+    return "netstat-linux"
+
+
+def _raw_listeners(source):
+    if source == "lsof":
+        return subprocess.run(["lsof", "-iTCP", "-sTCP:LISTEN", "-P", "-n"],
+                              capture_output=True, text=True)
+    if source == "ss":
+        return subprocess.run(["ss", "-tlnp"], capture_output=True, text=True)
+    if source == "netstat-linux":
+        return subprocess.run(["netstat", "-tlnp"], capture_output=True, text=True)
+    if source == "netstat-windows":
+        return subprocess.run(["netstat", "-ano"], capture_output=True, text=True)
+    raise ValueError(f"unknown source: {source}")
+
+
+def _pid_name_map_windows():
+    res = subprocess.run(["tasklist", "/FO", "CSV", "/NH"], capture_output=True, text=True)
+    m = {}
+    if res.returncode != 0 or not res.stdout:
+        return m
+    for line in res.stdout.split("\n"):
+        match = re.match(r'^"([^"]+)","(\d+)"', line)
+        if match:
+            m[int(match.group(2))] = match.group(1)
+    return m
+
+
+def get_listeners():
+    """Collect + parse + dedup listeners. Returns (listeners, warning)."""
+    source = detect_source()
+    try:
+        res = _raw_listeners(source)
+    except FileNotFoundError as e:
+        return [], f"could not run {source}: {e}. Is the tool installed?"
+    raw = res.stdout or ""
+    listeners = core.parse_listeners(raw, source)
+    if source == "netstat-windows":
+        names = _pid_name_map_windows()
+        for l in listeners:
+            l["name"] = names.get(l["pid"])
+    listeners = core.dedup_listeners(listeners)
+    return listeners, None
+
+
+# ---- killing ---------------------------------------------------------------
+
+_SIG_CONST = {
+    "HUP": signal.SIGHUP,
+    "INT": signal.SIGINT,
+    "QUIT": signal.SIGQUIT,
+    "KILL": signal.SIGKILL,
+    "USR1": signal.SIGUSR1,
+    "USR2": signal.SIGUSR2,
+    "TERM": signal.SIGTERM,
+}
+
+
+def kill_pids(pids, signal_name):
+    results = []
+    if sys.platform == "win32":
+        # Windows has no POSIX signals; /F forces termination.
+        for pid in pids:
+            r = subprocess.run(["taskkill", "/PID", str(pid), "/F", "/T"],
+                               capture_output=True, text=True)
+            results.append({"pid": pid, "ok": r.returncode == 0,
+                            "error": r.stderr.strip() or None})
+        return results
+    sig = _SIG_CONST[signal_name]
+    for pid in pids:
+        try:
+            os.kill(pid, sig)
+            results.append({"pid": pid, "ok": True, "error": None})
+        except ProcessLookupError:
+            results.append({"pid": pid, "ok": False, "error": "no such process"})
+        except PermissionError:
+            results.append({"pid": pid, "ok": False, "error": "permission denied"})
+        except OSError as e:
+            results.append({"pid": pid, "ok": False, "error": str(e)})
+    return results
+
+
+# ---- confirmation prompt ---------------------------------------------------
+
+def confirm(question):
+    if not sys.stdin.isatty():
+        return False
+    try:
+        ans = input(question).strip().lower()
+    except EOFError:
+        return False
+    return ans in ("y", "yes")
+
+
+# ---- commands --------------------------------------------------------------
+
+def cmd_list(args):
+    listeners, warning = get_listeners()
+    if warning:
+        sys.stderr.write(yellow(f"{warning}\n"))
+    if has(args, "--json"):
+        sys.stdout.write(json.dumps({"listeners": listeners}, indent=2) + "\n")
+        return 0
+    if not listeners:
+        sys.stdout.write(dim("no TCP ports are listening.\n"))
+        return 0
+    sys.stdout.write(core.format_table(listeners) + "\n")
+    return 0
+
+
+def cmd_port(port_arg, args):
+    try:
+        port = core.normalize_port(port_arg)
+    except ValueError as e:
+        fail(str(e))
+
+    listeners, warning = get_listeners()
+    if warning:
+        sys.stderr.write(yellow(f"{warning}\n"))
+
+    matches = core.select_by_port(listeners, port)
+
+    if has(args, "--json"):
+        sys.stdout.write(json.dumps({"port": port, "listeners": matches}, indent=2) + "\n")
+        return 0 if matches else 1
+
+    if not matches:
+        sys.stdout.write(dim(f"nothing listening on port {port}.\n"))
+        return 1
+
+    sys.stdout.write(f"listening on port {bold(str(port))}:\n")
+    sys.stdout.write(core.format_table(matches) + "\n")
+
+    if has(args, "--list") or has(args, "-l"):
+        return 0
+
+    pids = core.unique_pids(matches)
+    if not pids:
+        sys.stderr.write(yellow(f"found listeners on {port} but no pid to kill (need root?)\n"))
+        return 2
+
+    signal_name = core.parse_signal(flag(args, "--signal") or flag(args, "-s"))
+    force = has(args, "-k") or has(args, "--force")
+
+    if not force:
+        parts = []
+        for p in pids:
+            m = next((x for x in matches if x["pid"] == p), None)
+            name = m["name"] if m and m["name"] else "?"
+            parts.append(f"{cyan(name)} (pid {p})")
+        who = ", ".join(parts)
+        if not confirm(f"Kill {who} on port {port} with {signal_name}? [y/N] "):
+            sys.stdout.write(dim("aborted. Use -k to skip the prompt.\n"))
+            return 1
+
+    results = kill_pids(pids, signal_name)
+    failed = [r for r in results if not r["ok"]]
+    for r in results:
+        mark = green("✓") if r["ok"] else red("✗")
+        tail = "" if r["ok"] else f" - {r['error']}"
+        sys.stdout.write(f"{mark} pid {r['pid']} {'killed' if r['ok'] else 'failed'}{tail}\n")
+    if failed:
+        sys.stderr.write(yellow(
+            f"{len(failed)} process(es) could not be killed (try -s KILL or run as root).\n"))
+        return 2
+    return 0
+
+
+# ---- main ------------------------------------------------------------------
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    if argv and argv[0] in ("-h", "--help"):
+        sys.stdout.write(HELP)
+        return 0
+    if argv and argv[0] in ("-v", "--version"):
+        sys.stdout.write(VERSION + "\n")
+        return 0
+
+    try:
+        # No args, or a flag-first form like `portvac --json` -> list everything.
+        if not argv or argv[0].startswith("-"):
+            return cmd_list(argv)
+        first = argv[0]
+        if first == "list":
+            return cmd_list(argv[1:])
+        if re.fullmatch(r"\d+", first):
+            return cmd_port(first, argv[1:])
+        fail(f"unknown argument: {first} (try --help)")
+    except ValueError as e:
+        fail(str(e))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

portvac-0.1.0/src/portvac/core.py

@@ -0,0 +1,276 @@
+"""portvac core - pure listener parsing & selection. No fs, no network, no OS
+calls, no clock. Everything that touches the OS lives in cli.py.
+
+A "listener" is a normalized dict:
+    {"port": int, "pid": int|None, "name": str|None,
+     "address": str, "protocol": "tcp", "family": "ipv4"|"ipv6"}
+
+The parsers turn the raw stdout of platform tools (lsof / ss / netstat) into
+this shape so the rest of the tool - and the tests - never care which OS
+produced it. Mirrors src/core.js byte-for-behaviour.
+"""
+
+import re
+
+SIGNALS = {"HUP": 1, "INT": 2, "QUIT": 3, "KILL": 9, "USR1": 10, "USR2": 12, "TERM": 15}
+
+
+def normalize_port(value) -> int:
+    """Coerce a port argument into an int 0-65535. Raises ValueError on garbage."""
+    if isinstance(value, bool):  # guard: bool is an int subclass
+        raise ValueError(f"invalid port: {value!r}")
+    if isinstance(value, int):
+        if value < 0 or value > 65535:
+            raise ValueError(f"invalid port: {value} (use 0-65535)")
+        return value
+    s = str(value).strip()
+    if not re.fullmatch(r"\d+", s):
+        raise ValueError(f'invalid port: "{value}" (use 0-65535)')
+    n = int(s)
+    if n < 0 or n > 65535:
+        raise ValueError(f'invalid port: "{value}" (use 0-65535)')
+    return n
+
+
+def parse_signal(value) -> str:
+    """Normalize a signal to a canonical uppercase name (no SIG prefix).
+
+    Accepts "TERM", "SIGTERM", "15". Default (None/"") is "TERM".
+    """
+    if value is None or value == "":
+        return "TERM"
+    s = str(value).strip().upper()
+    if s.startswith("SIG"):
+        s = s[3:]
+    if re.fullmatch(r"\d+", s):
+        for name, num in SIGNALS.items():
+            if num == int(s):
+                return name
+        raise ValueError(f"unsupported signal: {value!r}")
+    if s in SIGNALS:
+        return s
+    raise ValueError(f'unsupported signal: "{value}" (try TERM, KILL, INT, QUIT, HUP)')
+
+
+# ----- address helpers ------------------------------------------------------
+
+_ADDR_PORT_RE = re.compile(r"^(.*):(\d+)$")
+
+
+def _split_address_port(addr_port):
+    m = _ADDR_PORT_RE.match(addr_port)
+    if not m:
+        return None
+    return m.group(1), int(m.group(2))
+
+
+def _family_of(address):
+    # anything bracketed or containing multiple colons is IPv6; a bare "*" is
+    # reported as ipv4 (lsof emits separate IPv4/IPv6 rows for it anyway)
+    if address.startswith("[") or (":" in address and not re.fullmatch(r"\d+\.\d+\.\d+\.\d+", address)):
+        return "ipv6"
+    return "ipv4"
+
+
+def _normalize_wildcard(address, family):
+    if address == "*":
+        return "[::]" if family == "ipv6" else "0.0.0.0"
+    return address
+
+
+# ----- parsers --------------------------------------------------------------
+
+_LSOF_RE = re.compile(r"^(\S+)\s+(\d+)\s+\S+\s+\S+\s+(IPv4|IPv6)\s+\S+\s+\S+\s+\S+\s+(.+)$")
+
+
+def parse_lsof(raw) -> list:
+    """Parse `lsof -iTCP -sTCP:LISTEN -P -n` output (macOS / BSD / Linux)."""
+    out = []
+    lines = str(raw).split("\n")
+    for line in lines[1:]:  # skip header
+        t = line.strip()
+        if not t:
+            continue
+        m = _LSOF_RE.match(t)
+        if not m:
+            continue
+        family = m.group(3).lower()
+        addr_part = re.sub(r"\s*\(LISTEN\)\s*$", "", m.group(4)).strip()
+        sp = _split_address_port(addr_part)
+        if not sp:
+            continue
+        address, port = sp
+        out.append({
+            "port": port,
+            "pid": int(m.group(2)),
+            "name": m.group(1),
+            "address": _normalize_wildcard(address, family),
+            "protocol": "tcp",
+            "family": family,
+        })
+    return out
+
+
+_SS_RE = re.compile(r"^LISTEN\s+\S+\s+\S+\s+(\S+)\s+\S+\s*(.*)$")
+_SS_PROC_RE = re.compile(r'users:\(\("([^"]+)",pid=(\d+)')
+
+
+def parse_ss(raw) -> list:
+    """Parse `ss -tlnp` output (Linux). Process column is optional."""
+    out = []
+    for line in str(raw).split("\n")[1:]:  # skip header
+        t = line.strip()
+        if not t:
+            continue
+        m = _SS_RE.match(t)
+        if not m:
+            continue
+        sp = _split_address_port(m.group(1))
+        if not sp:
+            continue
+        address, port = sp
+        family = _family_of(address)
+        pid, name = None, None
+        pm = _SS_PROC_RE.search(m.group(2))
+        if pm:
+            name, pid = pm.group(1), int(pm.group(2))
+        out.append({
+            "port": port,
+            "pid": pid,
+            "name": name,
+            "address": _normalize_wildcard(address, family),
+            "protocol": "tcp",
+            "family": family,
+        })
+    return out
+
+
+_NETSTAT_LINUX_RE = re.compile(r"^tcp\S*\s+\S+\s+\S+\s+(\S+)\s+\S+\s+LISTEN\s+(\S+)$")
+
+
+def parse_netstat_linux(raw) -> list:
+    """Parse `netstat -tlnp` output (Linux)."""
+    out = []
+    for line in str(raw).split("\n"):  # match by pattern; header rows won't match
+        t = line.strip()
+        if not t:
+            continue
+        m = _NETSTAT_LINUX_RE.match(t)
+        if not m:
+            continue
+        sp = _split_address_port(m.group(1))
+        if not sp:
+            continue
+        address, port = sp
+        family = _family_of(address)
+        pid, name = None, None
+        pm = re.match(r"^(\d+)/(.+)$", m.group(2))
+        if pm:
+            pid, name = int(pm.group(1)), pm.group(2)
+        out.append({
+            "port": port,
+            "pid": pid,
+            "name": name,
+            "address": _normalize_wildcard(address, family),
+            "protocol": "tcp",
+            "family": family,
+        })
+    return out
+
+
+_NETSTAT_WIN_RE = re.compile(r"^TCP\s+(\S+)\s+\S+\s+LISTENING\s+(\d+)$", re.IGNORECASE)
+
+
+def parse_netstat_windows(raw) -> list:
+    """Parse `netstat -ano` output (Windows). Process names stay None here."""
+    out = []
+    for line in str(raw).split("\n"):
+        t = line.strip()
+        if not t:
+            continue
+        m = _NETSTAT_WIN_RE.match(t)
+        if not m:
+            continue
+        sp = _split_address_port(m.group(1))
+        if not sp:
+            continue
+        address, port = sp
+        family = _family_of(address)
+        out.append({
+            "port": port,
+            "pid": int(m.group(2)),
+            "name": None,
+            "address": _normalize_wildcard(address, family),
+            "protocol": "tcp",
+            "family": family,
+        })
+    return out
+
+
+def parse_listeners(raw, source) -> list:
+    """Dispatch parser by source descriptor."""
+    if source == "lsof":
+        return parse_lsof(raw)
+    if source == "ss":
+        return parse_ss(raw)
+    if source == "netstat-linux":
+        return parse_netstat_linux(raw)
+    if source == "netstat-windows":
+        return parse_netstat_windows(raw)
+    raise ValueError(f"unknown listener source: {source}")
+
+
+def dedup_listeners(listeners) -> list:
+    """Drop duplicate (port, pid, family) rows - lsof emits one per fd."""
+    seen = set()
+    out = []
+    for l in listeners:
+        key = (l["port"], l["pid"], l["family"])
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(l)
+    return out
+
+
+def select_by_port(listeners, port) -> list:
+    """Listeners matching a port, sorted by pid (None last)."""
+    p = normalize_port(port)
+    return sorted(
+        [l for l in listeners if l["port"] == p],
+        key=lambda l: (l["pid"] is None, l["pid"] if l["pid"] is not None else 0),
+    )
+
+
+def unique_pids(listeners) -> list:
+    """Collect unique pids from a set of listeners (for killing)."""
+    seen = set()
+    out = []
+    for l in listeners:
+        pid = l["pid"]
+        if pid is not None and pid not in seen:
+            seen.add(pid)
+            out.append(pid)
+    return sorted(out)
+
+
+def format_table(listeners) -> str:
+    """Format listeners as a fixed-width human table. Returns '' for empty."""
+    if not listeners:
+        return ""
+    cols = ["port", "pid", "name", "address", "family"]
+    rows = [{
+        "port": str(l["port"]),
+        "pid": str(l["pid"]) if l["pid"] is not None else "-",
+        "name": l["name"] or "-",
+        "address": l["address"] or "*",
+        "family": (l["family"] or "").upper(),
+    } for l in listeners]
+    w = {c: len(c) for c in cols}
+    for r in rows:
+        for c in cols:
+            w[c] = max(w[c], len(r[c]))
+    head = "  ".join(c.upper().ljust(w[c]) for c in cols)
+    sep = "  ".join("-" * w[c] for c in cols)
+    body = "\n".join("  ".join(r[c].ljust(w[c]) for c in cols) for r in rows)
+    return f"{head}\n{sep}\n{body}"

portvac-0.1.0/src/portvac.egg-info/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: portvac
+Version: 0.1.0
+Summary: See what's listening on a TCP port and free it - cross-platform, zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/portvac-py
+Project-URL: Repository, https://github.com/jjdoor/portvac-py
+Project-URL: Issues, https://github.com/jjdoor/portvac-py/issues
+Keywords: port,kill-port,process,lsof,cli,devtools,cross-platform,debugging,sysadmin,zero-dependencies
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# portvac
+
+**See what's listening on a TCP port - and free it.** The "port already in use"
+error costs every developer a minute of `lsof` / `netstat` / `taskkill`
+archaeology. `portvac` lists who's on a port in one command, then vacates it on
+confirm. Cross-platform, **zero dependencies**.
+
+```bash
+pip install portvac
+portvac             # list every listening TCP port
+portvac 3000        # show what's on 3000, then kill it (asks first)
+portvac 3000 -k     # kill without asking (scripts / CI)
+portvac 3000 -s KILL   # SIGKILL instead of the default SIGTERM
+```
+
+Node shop? `npx portvac 3000 -k` works too - same tool, same behaviour.
+
+## Why
+
+> "Port 3000 is already in use" - and now you're pasting `lsof -i :3000` into
+> Stack Overflow for the fourth time this week.
+
+`lsof` flags differ from `netstat` which differs from Windows `taskkill`. You
+remember none of them under pressure. `portvac` is the one command that works
+the same on macOS, Linux, and Windows: **look first, kill second**, never
+silent.
+
+## How it works
+
+1. **List** - shells out to the platform's own tool (`lsof` / `ss` / `netstat`)
+   to read listening sockets. No daemon, no network.
+2. **Show** - prints a clean table: port, pid, process name, address, family.
+3. **Vacate** - on a port argument, asks `y/N`, then sends a signal (default
+   `TERM`) to the owning pid(s). `-k` skips the prompt.
+
+Nothing is installed system-wide and no data leaves your machine.
+
+## Usage
+
+```
+portvac                       List every TCP port currently listening
+portvac <port>                Show what's on <port>, then kill it (asks first)
+portvac <port> --list         Show only, don't kill
+portvac <port> -k             Kill without confirmation
+portvac <port> -s KILL        Send KILL instead of TERM
+portvac --json [<port>]       Machine-readable output (great for piping)
+
+  -k, --force         Kill without confirmation
+  -l, --list          List only; never kill
+  -s, --signal <SIG>  TERM (default), KILL, INT, QUIT, HUP
+      --json          Emit JSON; suppresses colors and prompts
+  -v, --version
+```
+
+### JSON
+
+```bash
+$ portvac --json 3000
+{
+  "port": 3000,
+  "listeners": [
+    { "port": 3000, "pid": 12345, "name": "node", "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4" }
+  ]
+}
+```
+
+## Platform notes
+
+| Platform | Lookup | Kill |
+|----------|--------|------|
+| macOS / BSD | `lsof -iTCP -sTCP:LISTEN -P -n` | `os.kill(pid, sig)` |
+| Linux | `ss -tlnp` (falls back to `netstat -tlnp`) | `os.kill(pid, sig)` |
+| Windows | `netstat -ano` + `tasklist` | `taskkill /PID <pid> /F /T` |
+
+On Windows there's no POSIX signal hierarchy, so `portvac` force-terminates
+(`taskkill /F`). To see another user's processes you may need elevated
+privileges, same as the underlying tools.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | listed, or killed successfully |
+| `1` | nothing listening / port not in use / aborted |
+| `2` | error (bad args, tool missing, kill failed) |
+
+## License
+
+MIT

portvac-0.1.0/src/portvac.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/portvac/__init__.py
+src/portvac/__main__.py
+src/portvac/cli.py
+src/portvac/core.py
+src/portvac.egg-info/PKG-INFO
+src/portvac.egg-info/SOURCES.txt
+src/portvac.egg-info/dependency_links.txt
+src/portvac.egg-info/entry_points.txt
+src/portvac.egg-info/top_level.txt
+tests/test_core.py

portvac-0.1.0/src/portvac.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

portvac-0.1.0/src/portvac.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+portvac = portvac.cli:main

portvac-0.1.0/src/portvac.egg-info/top_level.txt

@@ -0,0 +1 @@
+portvac

portvac-0.1.0/tests/test_core.py

@@ -0,0 +1,187 @@
+import pytest
+
+from portvac.core import (
+    normalize_port, parse_signal,
+    parse_lsof, parse_ss, parse_netstat_linux, parse_netstat_windows, parse_listeners,
+    dedup_listeners, select_by_port, unique_pids, format_table,
+)
+
+# ----- normalize_port -------------------------------------------------------
+
+def test_normalize_port_accepts_ints_and_numeric_strings():
+    assert normalize_port(3000) == 3000
+    assert normalize_port("8080") == 8080
+    assert normalize_port("0") == 0
+    assert normalize_port("65535") == 65535
+
+
+def test_normalize_port_rejects_garbage_and_out_of_range():
+    with pytest.raises(ValueError):
+        normalize_port("abc")
+    with pytest.raises(ValueError):
+        normalize_port("-1")
+    with pytest.raises(ValueError):
+        normalize_port("65536")
+    with pytest.raises(ValueError):
+        normalize_port("3000a")
+
+
+# ----- parse_signal ---------------------------------------------------------
+
+def test_parse_signal_defaults_to_term_and_strips_sig_prefix():
+    assert parse_signal(None) == "TERM"
+    assert parse_signal("") == "TERM"
+    assert parse_signal("TERM") == "TERM"
+    assert parse_signal("sigkill") == "KILL"
+    assert parse_signal("KILL") == "KILL"
+    assert parse_signal("15") == "TERM"   # numeric -> canonical name
+    assert parse_signal("9") == "KILL"
+
+
+def test_parse_signal_rejects_unknown_signals():
+    with pytest.raises(ValueError):
+        parse_signal("SIGSEGV")
+    with pytest.raises(ValueError):
+        parse_signal("99")
+
+
+# ----- parse_lsof (real macOS output) ---------------------------------------
+
+LSOF_SAMPLE = """COMMAND     PID     USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
+rapportd    618 benjamin   11u  IPv4 0x10415ffa2a699725      0t0  TCP *:59505 (LISTEN)
+rapportd    618 benjamin   13u  IPv6  0xfd59be99dbab164      0t0  TCP *:59505 (LISTEN)
+OrbStack   2529 benjamin   82u  IPv4 0xbf8bb265f3586c58      0t0  TCP 127.0.0.1:32222 (LISTEN)
+OrbStack   2529 benjamin   83u  IPv6 0x34f6f7a71ad73a59      0t0  TCP [::1]:32222 (LISTEN)
+OrbStack   2529 benjamin  115u  IPv4 0x36e1f1db735e05      0t0  TCP *:5432 (LISTEN)
+"""
+
+
+def test_parse_lsof_parses_real_macos_output_all_address_shapes():
+    ls = parse_lsof(LSOF_SAMPLE)
+    assert len(ls) == 5
+    assert ls[0] == {"port": 59505, "pid": 618, "name": "rapportd", "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4"}
+    assert ls[1] == {"port": 59505, "pid": 618, "name": "rapportd", "address": "[::]", "protocol": "tcp", "family": "ipv6"}
+    assert ls[2] == {"port": 32222, "pid": 2529, "name": "OrbStack", "address": "127.0.0.1", "protocol": "tcp", "family": "ipv4"}
+    assert ls[3] == {"port": 32222, "pid": 2529, "name": "OrbStack", "address": "[::1]", "protocol": "tcp", "family": "ipv6"}
+    assert ls[4] == {"port": 5432, "pid": 2529, "name": "OrbStack", "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4"}
+
+
+def test_parse_lsof_skips_header_and_blank_lines():
+    assert parse_lsof("COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME\n") == []
+    assert parse_lsof("") == []
+
+
+# ----- parse_ss (Linux) -----------------------------------------------------
+
+SS_SAMPLE = """State   Recv-Q  Send-Q   Local Address:Port    Peer Address:Port  Process
+LISTEN  0       128      0.0.0.0:3000          0.0.0.0:*          users:(("node",pid=12345,fd=23))
+LISTEN  0       128      127.0.0.1:5432        0.0.0.0:*          users:(("python",pid=12346,fd=4))
+LISTEN  0       128      [::]:8080             [::]:*             users:(("nginx",pid=12347,fd=6))
+LISTEN  0       128      0.0.0.0:9000          0.0.0.0:*
+"""
+
+
+def test_parse_ss_parses_linux_output_incl_ipv6_and_missing_process():
+    ls = parse_ss(SS_SAMPLE)
+    assert len(ls) == 4
+    assert ls[0] == {"port": 3000, "pid": 12345, "name": "node", "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4"}
+    assert ls[2] == {"port": 8080, "pid": 12347, "name": "nginx", "address": "[::]", "protocol": "tcp", "family": "ipv6"}
+    assert ls[3] == {"port": 9000, "pid": None, "name": None, "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4"}
+
+
+# ----- parse_netstat_linux --------------------------------------------------
+
+NETSTAT_LINUX_SAMPLE = """Proto Recv-Q Send-Q Local Address   Foreign Address   State    PID/Program name
+tcp   0      128    0.0.0.0:3000    0.0.0.0:*         LISTEN   12345/node
+tcp   0      128    127.0.0.1:5432  0.0.0.0:*         LISTEN   12346/python
+tcp6  0      128    :::8080         :::*              LISTEN   12347/nginx
+"""
+
+
+def test_parse_netstat_linux_parses_output():
+    ls = parse_netstat_linux(NETSTAT_LINUX_SAMPLE)
+    assert len(ls) == 3
+    assert ls[0] == {"port": 3000, "pid": 12345, "name": "node", "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4"}
+    assert ls[2] == {"port": 8080, "pid": 12347, "name": "nginx", "address": "::", "protocol": "tcp", "family": "ipv6"}
+
+
+# ----- parse_netstat_windows ------------------------------------------------
+
+NETSTAT_WIN_SAMPLE = """Active Connections
+
+  Proto  Local Address     Foreign Address   State       PID
+  TCP    0.0.0.0:3000      0.0.0.0:0         LISTENING   12345
+  TCP    127.0.0.1:5432    0.0.0.0:0         LISTENING   12346
+  TCP    [::]:8080         [::]:0            LISTENING   12347
+"""
+
+
+def test_parse_netstat_windows_parses_output_name_stays_none():
+    ls = parse_netstat_windows(NETSTAT_WIN_SAMPLE)
+    assert len(ls) == 3
+    assert ls[0] == {"port": 3000, "pid": 12345, "name": None, "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4"}
+    assert ls[2] == {"port": 8080, "pid": 12347, "name": None, "address": "[::]", "protocol": "tcp", "family": "ipv6"}
+
+
+# ----- parse_listeners dispatch --------------------------------------------
+
+def test_parse_listeners_dispatches_by_source():
+    assert len(parse_listeners(LSOF_SAMPLE, "lsof")) == 5
+    assert len(parse_listeners(SS_SAMPLE, "ss")) == 4
+    with pytest.raises(ValueError):
+        parse_listeners("", "nope")
+
+
+# ----- dedup_listeners ------------------------------------------------------
+
+def test_dedup_collapses_same_port_pid_family():
+    ls = parse_lsof(LSOF_SAMPLE)
+    dup = ls + [dict(ls[0])]
+    assert len(dedup_listeners(dup)) == len(ls)
+
+
+def test_dedup_keeps_distinct_families_on_same_port():
+    ls = dedup_listeners(parse_lsof(LSOF_SAMPLE))
+    on59505 = [l for l in ls if l["port"] == 59505]
+    assert len(on59505) == 2  # ipv4 + ipv6, same pid
+
+
+# ----- select_by_port -------------------------------------------------------
+
+def test_select_by_port_filters_and_sorts_by_pid():
+    ls = dedup_listeners(parse_lsof(LSOF_SAMPLE))
+    on32222 = select_by_port(ls, 32222)
+    assert len(on32222) == 2
+    assert [l["family"] for l in on32222] == ["ipv4", "ipv6"]
+    assert select_by_port(ls, 9999) == []
+
+
+def test_select_by_port_rejects_bad_port():
+    with pytest.raises(ValueError):
+        select_by_port([], "nope")
+
+
+# ----- unique_pids ----------------------------------------------------------
+
+def test_unique_pids_dedups_and_sorts():
+    ls = dedup_listeners(parse_lsof(LSOF_SAMPLE))
+    on32222 = select_by_port(ls, 32222)
+    assert unique_pids(on32222) == [2529]  # both families, one pid
+    assert unique_pids([{"pid": 3}, {"pid": 1}, {"pid": 1}]) == [1, 3]
+    assert unique_pids([{"pid": None}]) == []
+
+
+# ----- format_table ---------------------------------------------------------
+
+def test_format_table_empty_is_empty_string():
+    assert format_table([]) == ""
+
+
+def test_format_table_renders_header_separator_rows():
+    ls = dedup_listeners(parse_lsof(LSOF_SAMPLE))
+    table = format_table(select_by_port(ls, 32222))
+    assert "PORT" in table
+    assert "----" in table
+    assert "32222" in table
+    assert "OrbStack" in table
+    assert len(table.split("\n")) == 4  # header + sep + 2 rows