portsmith 0.1.0__tar.gz

portsmith-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Tools
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db

portsmith-0.1.0/LICENSE

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

portsmith-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: portsmith
+Version: 0.1.0
+Summary: Local port management CLI — list, kill, watch, and snapshot listening ports
+Project-URL: Homepage, https://github.com/atharvashashankk/portman
+Project-URL: Issues, https://github.com/atharvashashankk/portman/issues
+Author-email: Atharva Kokane <atharvashashankkokane@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Atharva Kokane
+        
+        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.
+License-File: LICENSE
+Keywords: cli,devtools,network,port,process
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+# portman
+
+A local port management CLI for macOS and Linux.
+
+## Installation
+
+```bash
+pip install portman
+```
+
+Or install from source:
+
+```bash
+git clone <repo>
+cd portman
+pip install -e .
+```
+
+## Commands
+
+### `portman list`
+
+Show all listening ports with PID, process name, port, protocol, and status. System ports (<1024) are highlighted in yellow, user ports in green.
+
+```bash
+portman list
+
+# Only show ports opened from this terminal session
+portman list --mine
+
+# Machine-readable JSON output
+portman list --json
+```
+
+> **`--mine` note:** this flag filters to processes running under your OS user account. It removes system services (svchost, lsass, etc.) but will still show other user-owned background apps that happen to listen on ports (e.g. Chrome, cloud sync clients). It correctly catches dev servers started in any shell or terminal window.
+
+### `portman kill <port>`
+
+Kill the process listening on a given port. Asks for confirmation unless `--force` is passed.
+
+```bash
+portman kill 8080
+
+# Skip confirmation
+portman kill 8080 --force
+portman kill 8080 -f
+```
+
+### `portman watch`
+
+Live-updating view of all active ports, refreshing every 2 seconds. New ports are highlighted green, closed ports red. Exit with `Ctrl+C`.
+
+```bash
+portman watch
+
+# Only watch ports opened from this terminal session
+portman watch --mine
+```
+
+### `portman save <name>`
+
+Save a snapshot of all currently active user ports (port ≥1024) to `~/.portman/profiles/<name>.json`.
+
+```bash
+portman save myproject
+portman save dev-stack
+```
+
+### `portman restore <name>`
+
+Check a saved profile against currently running ports. Shows which saved processes are still running and which are missing, along with hints for restarting them.
+
+```bash
+portman restore myproject
+```
+
+### `portman profiles`
+
+List all saved profiles with their creation timestamp and port count.
+
+```bash
+portman profiles
+```
+
+## Requirements
+
+- Python 3.10+
+- macOS or Linux (Windows is not supported)
+
+## Notes
+
+- Ports below 1024 are system ports and may require `sudo` to kill.
+- `portman restore` does not restart processes — it only reports their status and suggests what needs to be restarted.
+- Profiles are stored in `~/.portman/profiles/` as JSON files.

portsmith-0.1.0/README.md

@@ -0,0 +1,94 @@
+# portman
+
+A local port management CLI for macOS and Linux.
+
+## Installation
+
+```bash
+pip install portman
+```
+
+Or install from source:
+
+```bash
+git clone <repo>
+cd portman
+pip install -e .
+```
+
+## Commands
+
+### `portman list`
+
+Show all listening ports with PID, process name, port, protocol, and status. System ports (<1024) are highlighted in yellow, user ports in green.
+
+```bash
+portman list
+
+# Only show ports opened from this terminal session
+portman list --mine
+
+# Machine-readable JSON output
+portman list --json
+```
+
+> **`--mine` note:** this flag filters to processes running under your OS user account. It removes system services (svchost, lsass, etc.) but will still show other user-owned background apps that happen to listen on ports (e.g. Chrome, cloud sync clients). It correctly catches dev servers started in any shell or terminal window.
+
+### `portman kill <port>`
+
+Kill the process listening on a given port. Asks for confirmation unless `--force` is passed.
+
+```bash
+portman kill 8080
+
+# Skip confirmation
+portman kill 8080 --force
+portman kill 8080 -f
+```
+
+### `portman watch`
+
+Live-updating view of all active ports, refreshing every 2 seconds. New ports are highlighted green, closed ports red. Exit with `Ctrl+C`.
+
+```bash
+portman watch
+
+# Only watch ports opened from this terminal session
+portman watch --mine
+```
+
+### `portman save <name>`
+
+Save a snapshot of all currently active user ports (port ≥1024) to `~/.portman/profiles/<name>.json`.
+
+```bash
+portman save myproject
+portman save dev-stack
+```
+
+### `portman restore <name>`
+
+Check a saved profile against currently running ports. Shows which saved processes are still running and which are missing, along with hints for restarting them.
+
+```bash
+portman restore myproject
+```
+
+### `portman profiles`
+
+List all saved profiles with their creation timestamp and port count.
+
+```bash
+portman profiles
+```
+
+## Requirements
+
+- Python 3.10+
+- macOS or Linux (Windows is not supported)
+
+## Notes
+
+- Ports below 1024 are system ports and may require `sudo` to kill.
+- `portman restore` does not restart processes — it only reports their status and suggests what needs to be restarted.
+- Profiles are stored in `~/.portman/profiles/` as JSON files.

portsmith-0.1.0/portman/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

portsmith-0.1.0/portman/commands/kill.py

@@ -0,0 +1,53 @@
+import typer
+import psutil
+from rich.console import Console
+from portman.utils import check_platform, get_listening_ports
+
+console = Console()
+
+
+def command(
+    port: int = typer.Argument(..., help="Port number of the process to kill"),
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation prompt"),
+) -> None:
+    """Kill the process listening on the given port."""
+    check_platform()
+    ports = get_listening_ports()
+    matches = [p for p in ports if p.port == port]
+
+    if not matches:
+        console.print(f"[red]No process found listening on port {port}.[/red]")
+        raise typer.Exit(1)
+
+    target = matches[0]
+
+    if not target.pid:
+        console.print(
+            f"[red]Cannot kill process on port {port}: PID unknown. "
+            "Try running with sudo.[/red]"
+        )
+        raise typer.Exit(1)
+
+    if not force:
+        confirmed = typer.confirm(
+            f"Kill {target.name} (PID {target.pid}) on port {port}?"
+        )
+        if not confirmed:
+            console.print("[yellow]Aborted.[/yellow]")
+            raise typer.Exit()
+
+    try:
+        proc = psutil.Process(target.pid)
+        proc.terminate()
+        console.print(
+            f"[green]Killed[/green] [bold]{target.name}[/bold] "
+            f"(PID {target.pid}) on port [bold]{port}[/bold]."
+        )
+    except psutil.NoSuchProcess:
+        console.print(f"[yellow]Process {target.pid} was already gone.[/yellow]")
+    except psutil.AccessDenied:
+        console.print(
+            f"[red]Permission denied killing PID {target.pid}. "
+            "Try running with sudo.[/red]"
+        )
+        raise typer.Exit(1)

portsmith-0.1.0/portman/commands/list_ports.py

@@ -0,0 +1,67 @@
+import json
+import typer
+from rich.console import Console
+from rich.table import Table
+from portman.utils import check_platform, get_listening_ports, get_user_pids
+
+console = Console()
+
+
+def command(
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    mine: bool = typer.Option(False, "--mine", help="Only show ports opened from this terminal session"),
+) -> None:
+    """Show all listening ports with PID, process name, port, protocol, and status."""
+    check_platform()
+    ports = get_listening_ports()
+
+    if mine:
+        user_pids = get_user_pids()
+        ports = [p for p in ports if p.pid in user_pids]
+
+    if json_output:
+        data = [
+            {
+                "pid": p.pid,
+                "name": p.name,
+                "port": p.port,
+                "protocol": p.protocol,
+                "status": p.status,
+            }
+            for p in ports
+        ]
+        typer.echo(json.dumps(data, indent=2))
+        return
+
+    if not ports:
+        console.print("[yellow]No listening ports found.[/yellow]")
+        return
+
+    table = Table(
+        title="Active Listening Ports",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Port", justify="right", style="bold")
+    table.add_column("Proto")
+    table.add_column("PID", justify="right")
+    table.add_column("Process")
+    table.add_column("Status")
+    table.add_column("Type")
+
+    for p in ports:
+        if p.is_system():
+            type_label = "[yellow]system[/yellow]"
+        else:
+            type_label = "[green]user[/green]"
+
+        table.add_row(
+            str(p.port),
+            p.protocol,
+            str(p.pid) if p.pid else "[dim]-[/dim]",
+            p.name,
+            p.status,
+            type_label,
+        )
+
+    console.print(table)

portsmith-0.1.0/portman/commands/profiles.py

@@ -0,0 +1,35 @@
+import json
+from rich.console import Console
+from rich.table import Table
+from portman.utils import check_platform, get_profiles_dir
+
+console = Console()
+
+
+def command() -> None:
+    """List all saved profiles with their timestamp and port count."""
+    check_platform()
+    profiles_dir = get_profiles_dir()
+    files = sorted(profiles_dir.glob("*.json"))
+
+    if not files:
+        console.print("[yellow]No saved profiles. Use 'portman save <name>' to create one.[/yellow]")
+        return
+
+    table = Table(
+        title="Saved Profiles",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Name", style="bold")
+    table.add_column("Saved At")
+    table.add_column("Ports", justify="right")
+
+    for f in files:
+        try:
+            data = json.loads(f.read_text())
+            table.add_row(data["name"], data["saved_at"], str(len(data["ports"])))
+        except (json.JSONDecodeError, KeyError):
+            table.add_row(f.stem, "[red]corrupted[/red]", "[dim]-[/dim]")
+
+    console.print(table)

portsmith-0.1.0/portman/commands/restore.py

@@ -0,0 +1,51 @@
+import json
+import typer
+from rich.console import Console
+from rich.table import Table
+from portman.utils import check_platform, get_listening_ports, get_profiles_dir
+
+console = Console()
+
+
+def command(
+    name: str = typer.Argument(..., help="Name of the profile to check"),
+) -> None:
+    """Show which saved ports are still running and which are missing."""
+    check_platform()
+    path = get_profiles_dir() / f"{name}.json"
+
+    if not path.exists():
+        console.print(f"[red]Profile '{name}' not found.[/red]")
+        raise typer.Exit(1)
+
+    profile = json.loads(path.read_text())
+    saved_ports: dict[int, dict] = {p["port"]: p for p in profile["ports"]}
+    active_ports: set[int] = {p.port for p in get_listening_ports()}
+
+    table = Table(
+        title=f"Profile: {name}  [dim](saved {profile['saved_at']})[/dim]",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Port", justify="right")
+    table.add_column("Process")
+    table.add_column("Status")
+
+    missing: list[dict] = []
+    for port, info in sorted(saved_ports.items()):
+        if port in active_ports:
+            table.add_row(str(port), info["name"], "[green]running[/green]")
+        else:
+            table.add_row(str(port), info["name"], "[red]missing[/red]")
+            missing.append(info)
+
+    console.print(table)
+
+    if missing:
+        console.print(
+            "\n[bold yellow]The following processes are no longer running:[/bold yellow]"
+        )
+        for info in missing:
+            console.print(
+                f"  [dim]# Restart '{info['name']}' and have it listen on port {info['port']}[/dim]"
+            )

portsmith-0.1.0/portman/commands/save.py

@@ -0,0 +1,38 @@
+import json
+from datetime import datetime
+import typer
+from rich.console import Console
+from portman.utils import check_platform, get_listening_ports, get_profiles_dir
+
+console = Console()
+
+
+def command(
+    name: str = typer.Argument(..., help="Name for the profile snapshot"),
+) -> None:
+    """Save a snapshot of currently active user ports (>=1024) to ~/.portman/profiles/<name>.json."""
+    check_platform()
+    ports = get_listening_ports()
+    user_ports = [p for p in ports if not p.is_system()]
+
+    profile = {
+        "name": name,
+        "saved_at": datetime.now().isoformat(),
+        "ports": [
+            {
+                "pid": p.pid,
+                "name": p.name,
+                "port": p.port,
+                "protocol": p.protocol,
+                "status": p.status,
+            }
+            for p in user_ports
+        ],
+    }
+
+    path = get_profiles_dir() / f"{name}.json"
+    path.write_text(json.dumps(profile, indent=2))
+    console.print(
+        f"[green]Saved[/green] [bold]{len(user_ports)}[/bold] user port(s) "
+        f"to profile [bold]'{name}'[/bold] ({path})"
+    )

portsmith-0.1.0/portman/commands/watch.py

@@ -0,0 +1,81 @@
+import time
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.live import Live
+from portman.utils import check_platform, get_listening_ports, get_user_pids, PortInfo
+
+console = Console()
+
+
+def _build_table(
+    ports: list[PortInfo],
+    new_ports: set[int],
+    closed_ports: set[int],
+) -> Table:
+    table = Table(
+        title="Active Ports  [dim](Ctrl+C to exit)[/dim]",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Port", justify="right", style="bold")
+    table.add_column("Proto")
+    table.add_column("PID", justify="right")
+    table.add_column("Process")
+    table.add_column("Status")
+    table.add_column("Change", justify="center")
+
+    for p in ports:
+        if p.port in new_ports:
+            change = "[bold green]NEW[/bold green]"
+            port_str = f"[green]{p.port}[/green]"
+        else:
+            change = ""
+            port_str = str(p.port)
+
+        table.add_row(
+            port_str,
+            p.protocol,
+            str(p.pid) if p.pid else "[dim]-[/dim]",
+            p.name,
+            p.status,
+            change,
+        )
+
+    for port in sorted(closed_ports):
+        table.add_row(
+            f"[red]{port}[/red]",
+            "", "", "", "",
+            "[bold red]CLOSED[/bold red]",
+        )
+
+    return table
+
+
+def command(
+    mine: bool = typer.Option(False, "--mine", help="Only show ports opened from this terminal session"),
+) -> None:
+    """Live-updating view of all active ports. Refreshes every 2 seconds."""
+    check_platform()
+
+    def _filtered_ports():
+        ports = get_listening_ports()
+        if mine:
+            user_pids = get_user_pids()
+            ports = [p for p in ports if p.pid in user_pids]
+        return ports
+
+    prev_ports: set[int] = {p.port for p in _filtered_ports()}
+
+    try:
+        with Live(console=console, refresh_per_second=2) as live:
+            while True:
+                ports = _filtered_ports()
+                current = {p.port for p in ports}
+                new_ports = current - prev_ports
+                closed_ports = prev_ports - current
+                live.update(_build_table(ports, new_ports, closed_ports))
+                prev_ports = current
+                time.sleep(2)
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Stopped watching.[/yellow]")

portsmith-0.1.0/portman/main.py

@@ -0,0 +1,18 @@
+import typer
+from portman.commands import list_ports, kill, watch, save, restore, profiles
+
+app = typer.Typer(
+    name="portman",
+    help="portman — local port management CLI",
+    no_args_is_help=True,
+)
+
+app.command("list")(list_ports.command)
+app.command("kill")(kill.command)
+app.command("watch")(watch.command)
+app.command("save")(save.command)
+app.command("restore")(restore.command)
+app.command("profiles")(profiles.command)
+
+if __name__ == "__main__":
+    app()

portsmith-0.1.0/portman/utils.py

@@ -0,0 +1,88 @@
+import os
+import sys
+import socket
+import psutil
+from dataclasses import dataclass
+
+
+def check_platform() -> None:
+    pass
+
+
+@dataclass
+class PortInfo:
+    pid: int
+    name: str
+    port: int
+    protocol: str
+    status: str
+
+    def is_system(self) -> bool:
+        return self.port < 1024
+
+
+def _get_process_name(pid: int) -> str:
+    if not pid:
+        return "unknown"
+    try:
+        return psutil.Process(pid).name()
+    except (psutil.NoSuchProcess, psutil.AccessDenied):
+        return "unknown"
+
+
+def get_listening_ports() -> list[PortInfo]:
+    seen: dict[tuple[int, str], PortInfo] = {}
+    try:
+        for conn in psutil.net_connections(kind="inet"):
+            if not conn.laddr:
+                continue
+            if conn.type == socket.SOCK_STREAM and conn.status != "LISTEN":
+                continue
+
+            port = conn.laddr.port
+            protocol = "TCP" if conn.type == socket.SOCK_STREAM else "UDP"
+            key = (port, protocol)
+            if key in seen:
+                continue
+
+            status = conn.status if conn.type == socket.SOCK_STREAM else "N/A"
+            pid = conn.pid or 0
+            seen[key] = PortInfo(
+                pid=pid,
+                name=_get_process_name(pid),
+                port=port,
+                protocol=protocol,
+                status=status,
+            )
+    except psutil.AccessDenied:
+        pass
+    return sorted(seen.values(), key=lambda x: x.port)
+
+
+def get_current_username() -> str | None:
+    try:
+        return psutil.Process(os.getpid()).username()
+    except (psutil.NoSuchProcess, psutil.AccessDenied):
+        return None
+
+
+def get_user_pids() -> set[int]:
+    """Return PIDs of all processes running as the current user."""
+    username = get_current_username()
+    if not username:
+        return set()
+    pids: set[int] = set()
+    for proc in psutil.process_iter(["pid", "username"]):
+        try:
+            if proc.info["username"] == username:
+                pids.add(proc.info["pid"])
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            pass
+    return pids
+
+
+def get_profiles_dir():
+    from pathlib import Path
+    d = Path.home() / ".portman" / "profiles"
+    d.mkdir(parents=True, exist_ok=True)
+    return d

portsmith-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "portsmith"
+version = "0.1.0"
+description = "Local port management CLI — list, kill, watch, and snapshot listening ports"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Atharva Kokane", email = "atharvashashankkokane@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["port", "cli", "network", "process", "devtools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Networking",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "psutil>=5.9.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/atharvashashankk/portman"
+Issues = "https://github.com/atharvashashankk/portman/issues"
+
+[project.scripts]
+portman = "portman.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["portman"]