portmap-dev 1.1.0__tar.gz

portmap_dev-1.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Environments
+.venv
+venv/
+env/
+
+# Python
+__pycache__/
+*.pyc
+
+# IDE
+.vscode/
+.idea/
+
+# Build
+build/
+dist/
+
+# Env
+.env
+

portmap_dev-1.1.0/LICENSE

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

portmap_dev-1.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: portmap-dev
+Version: 1.1.0
+Summary: Real-time dashboard for monitoring and managing local listening ports
+Project-URL: Homepage, https://github.com/abdallah-9a/Portmap
+Project-URL: Repository, https://github.com/abdallah-9a/Portmap
+Project-URL: Issues, https://github.com/abdallah-9a/Portmap/issues
+License: MIT
+License-File: LICENSE
+Keywords: dashboard,developer-tools,monitoring,networking,ports
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.111
+Requires-Dist: psutil>=5.9
+Requires-Dist: uvicorn[standard]>=0.29
+Description-Content-Type: text/markdown
+
+# Portmap
+
+A real-time dashboard for the listening ports on your machine. Portmap shows
+*what* is listening on every port, identifies the **project or service** behind
+each one, and lets you terminate a process with a single click.
+
+
+![Portmap dashboard](docs/portmap.png)
+
+---
+
+## Overview
+
+*"What is running on port 3000 — and why won't it die?"* Every developer hits
+this eventually. On a busy machine, dozens of dev servers, watchers, and
+forgotten daemons compete for ports, and tracking down which one belongs to
+which project — then stopping it safely — usually means a chain of `lsof`,
+`grep`, and `kill`.
+
+Portmap turns that into a glance. It keeps a live, categorized view of every
+listening port — which project or service owns it, and whether it is safe to
+kill — and lets you stop a process with one click, right from the browser.
+
+Under the hood it is a lightweight, local, single-user tool: a FastAPI backend
+plus a single static HTML page. No database, no build step.
+
+---
+
+## Why Portmap?
+
+`lsof`, `ss`, and `netstat` already list open ports — but they stop at the PID.
+Portmap is built for the step after that: understanding and acting on what you
+find.
+
+- **Answers "whose port is this?", not just "what PID?"** — each port is traced
+  to a git project and framework, instead of leaving you to map PIDs by hand.
+- **Live, not a one-off snapshot.** The view updates as servers start and stop,
+  so you don't re-run a command and re-read its output every time.
+- **Kill from the same place.** No copying a PID into a separate `kill` command —
+  and system-owned processes are guarded against accidental termination.
+- **Less noise.** IDE helpers and Chromium/Electron subprocesses are filtered
+  out, so you see services rather than internals.
+
+If you just need a one-off list, `ss -ltnp` is perfect. Portmap is for when you
+are juggling many services and want to watch and manage them continuously.
+
+---
+
+## Quick Start
+
+Linux with Python 3.12+:
+
+```bash
+git clone https://github.com/abdallah-9a/Portmap.git
+cd Portmap
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+fastapi run main.py
+```
+
+Then open <http://127.0.0.1:8000>. See [Installation](#installation) and
+[Usage](#usage) for details.
+
+---
+
+## Features
+
+- **Live updates** — ports are rescanned every 0.5s and pushed to the browser
+  over a websocket; the UI updates only when something actually changes.
+- **Smart identification** — each listening port is categorized as:
+  - **Project** — traced to a git repository, with framework detection
+    (Django, Node.js, Go, Rust, Ruby, Java, PHP, …).
+  - **Infrastructure** — known daemons like Redis, PostgreSQL, MySQL, MongoDB,
+    Nginx, Docker.
+  - **System** — kernel/system sockets with no owning PID.
+  - **Unknown** — an honest fallback showing the raw process name.
+- **Noise filtering** — IDE helpers (VS Code, Cursor, JetBrains, …) and
+  Chromium/Electron internal processes are skipped.
+- **One-click kill** — `SIGTERM` first, escalating to `SIGKILL` if the process
+  doesn't exit within the grace period.
+- **Safety guard** — processes owned by privileged/system accounts (UID < 1000)
+  are protected and cannot be killed from the UI.
+- **Non-blocking scanner** — scanning runs in a background thread, so the event
+  loop stays responsive for websocket updates and kill requests.
+
+---
+
+## Installation
+
+**Requirements:** Linux, Python 3.12+.
+
+```bash
+# 1. Clone
+git clone https://github.com/abdallah-9a/Portmap.git
+cd Portmap
+
+# 2. Create and activate a virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 3. Install dependencies
+pip install -r requirements.txt
+```
+
+---
+
+## Usage
+
+Start the server:
+
+```bash
+fastapi run main.py
+# or, equivalently:
+# uvicorn main:app
+```
+
+Then open the UI in your browser:
+
+```
+http://127.0.0.1:8000
+```
+
+Use the search box to filter by port or name, and click **Kill** next to a
+process to terminate it.
+
+> **Note:** `psutil` may need elevated privileges to see the owning PID of every
+> socket. If some ports show up as "System" or with missing details, try running
+> with `sudo` (be aware this also lets the kill endpoint act with root
+> privileges).
+
+---
+
+## Screenshots & Demo
+
+The hero screenshot sits at the top of this README — the first thing a visitor
+sees. This section is for the moving picture:
+
+![Portmap in action](docs/demo.gif)
+
+_A short capture of the live updates and one-click kill in action._
+
+---
+
+## Limitations
+
+- **Linux only.** Portmap relies on Linux semantics: `/proc`-based working
+  directory lookup for git detection, real UID ownership checks, and the
+  `UID < 1000` system-account protection. It is untested on macOS/Windows.
+- **No authentication.** Anyone who can reach the server can kill processes.
+  Bind it to `127.0.0.1` (the default) and do **not** expose it to a network.
+- **Single user / local use.** It is designed as a personal dev tool, not a
+  multi-tenant service.
+- **Privilege-dependent visibility.** Without elevated privileges, some sockets'
+  PIDs and metadata may be hidden by the OS.
+- **Git-root heuristic.** Project detection assumes a process's working
+  directory lives inside its repository; processes started elsewhere may fall
+  back to "Unknown".
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome. For anything beyond a small fix, please
+open an issue first to discuss the approach. For local development, run
+`fastapi dev main.py` to get auto-reload.
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE).

portmap_dev-1.1.0/README.md

@@ -0,0 +1,171 @@
+# Portmap
+
+A real-time dashboard for the listening ports on your machine. Portmap shows
+*what* is listening on every port, identifies the **project or service** behind
+each one, and lets you terminate a process with a single click.
+
+
+![Portmap dashboard](docs/portmap.png)
+
+---
+
+## Overview
+
+*"What is running on port 3000 — and why won't it die?"* Every developer hits
+this eventually. On a busy machine, dozens of dev servers, watchers, and
+forgotten daemons compete for ports, and tracking down which one belongs to
+which project — then stopping it safely — usually means a chain of `lsof`,
+`grep`, and `kill`.
+
+Portmap turns that into a glance. It keeps a live, categorized view of every
+listening port — which project or service owns it, and whether it is safe to
+kill — and lets you stop a process with one click, right from the browser.
+
+Under the hood it is a lightweight, local, single-user tool: a FastAPI backend
+plus a single static HTML page. No database, no build step.
+
+---
+
+## Why Portmap?
+
+`lsof`, `ss`, and `netstat` already list open ports — but they stop at the PID.
+Portmap is built for the step after that: understanding and acting on what you
+find.
+
+- **Answers "whose port is this?", not just "what PID?"** — each port is traced
+  to a git project and framework, instead of leaving you to map PIDs by hand.
+- **Live, not a one-off snapshot.** The view updates as servers start and stop,
+  so you don't re-run a command and re-read its output every time.
+- **Kill from the same place.** No copying a PID into a separate `kill` command —
+  and system-owned processes are guarded against accidental termination.
+- **Less noise.** IDE helpers and Chromium/Electron subprocesses are filtered
+  out, so you see services rather than internals.
+
+If you just need a one-off list, `ss -ltnp` is perfect. Portmap is for when you
+are juggling many services and want to watch and manage them continuously.
+
+---
+
+## Quick Start
+
+Linux with Python 3.12+:
+
+```bash
+git clone https://github.com/abdallah-9a/Portmap.git
+cd Portmap
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+fastapi run main.py
+```
+
+Then open <http://127.0.0.1:8000>. See [Installation](#installation) and
+[Usage](#usage) for details.
+
+---
+
+## Features
+
+- **Live updates** — ports are rescanned every 0.5s and pushed to the browser
+  over a websocket; the UI updates only when something actually changes.
+- **Smart identification** — each listening port is categorized as:
+  - **Project** — traced to a git repository, with framework detection
+    (Django, Node.js, Go, Rust, Ruby, Java, PHP, …).
+  - **Infrastructure** — known daemons like Redis, PostgreSQL, MySQL, MongoDB,
+    Nginx, Docker.
+  - **System** — kernel/system sockets with no owning PID.
+  - **Unknown** — an honest fallback showing the raw process name.
+- **Noise filtering** — IDE helpers (VS Code, Cursor, JetBrains, …) and
+  Chromium/Electron internal processes are skipped.
+- **One-click kill** — `SIGTERM` first, escalating to `SIGKILL` if the process
+  doesn't exit within the grace period.
+- **Safety guard** — processes owned by privileged/system accounts (UID < 1000)
+  are protected and cannot be killed from the UI.
+- **Non-blocking scanner** — scanning runs in a background thread, so the event
+  loop stays responsive for websocket updates and kill requests.
+
+---
+
+## Installation
+
+**Requirements:** Linux, Python 3.12+.
+
+```bash
+# 1. Clone
+git clone https://github.com/abdallah-9a/Portmap.git
+cd Portmap
+
+# 2. Create and activate a virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 3. Install dependencies
+pip install -r requirements.txt
+```
+
+---
+
+## Usage
+
+Start the server:
+
+```bash
+fastapi run main.py
+# or, equivalently:
+# uvicorn main:app
+```
+
+Then open the UI in your browser:
+
+```
+http://127.0.0.1:8000
+```
+
+Use the search box to filter by port or name, and click **Kill** next to a
+process to terminate it.
+
+> **Note:** `psutil` may need elevated privileges to see the owning PID of every
+> socket. If some ports show up as "System" or with missing details, try running
+> with `sudo` (be aware this also lets the kill endpoint act with root
+> privileges).
+
+---
+
+## Screenshots & Demo
+
+The hero screenshot sits at the top of this README — the first thing a visitor
+sees. This section is for the moving picture:
+
+![Portmap in action](docs/demo.gif)
+
+_A short capture of the live updates and one-click kill in action._
+
+---
+
+## Limitations
+
+- **Linux only.** Portmap relies on Linux semantics: `/proc`-based working
+  directory lookup for git detection, real UID ownership checks, and the
+  `UID < 1000` system-account protection. It is untested on macOS/Windows.
+- **No authentication.** Anyone who can reach the server can kill processes.
+  Bind it to `127.0.0.1` (the default) and do **not** expose it to a network.
+- **Single user / local use.** It is designed as a personal dev tool, not a
+  multi-tenant service.
+- **Privilege-dependent visibility.** Without elevated privileges, some sockets'
+  PIDs and metadata may be hidden by the OS.
+- **Git-root heuristic.** Project detection assumes a process's working
+  directory lives inside its repository; processes started elsewhere may fall
+  back to "Unknown".
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome. For anything beyond a small fix, please
+open an issue first to discuss the approach. For local development, run
+`fastapi dev main.py` to get auto-reload.
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE).

portmap_dev-1.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "portmap-dev"
+version = "1.1.0"
+description = "Real-time dashboard for monitoring and managing local listening ports"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["developer-tools", "ports", "monitoring", "networking", "dashboard"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Networking :: Monitoring",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Environment :: Console",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = [
+    "fastapi>=0.111",
+    "uvicorn[standard]>=0.29",
+    "psutil>=5.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/abdallah-9a/Portmap"
+Repository = "https://github.com/abdallah-9a/Portmap"
+Issues = "https://github.com/abdallah-9a/Portmap/issues"
+
+[project.scripts]
+portmap = "portmap.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/portmap"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/portmap/**",
+    "README.md",
+    "LICENSE",
+]

portmap_dev-1.1.0/src/portmap/__init__.py

@@ -0,0 +1,2 @@
+# src/portmap/__init__.py
+__version__ = "1.1.0"

portmap_dev-1.1.0/src/portmap/__main__.py

@@ -0,0 +1,5 @@
+# src/portmap/__main__.py
+from portmap.cli import main
+
+if __name__ == "__main__":
+    main()

portmap_dev-1.1.0/src/portmap/cli.py

@@ -0,0 +1,40 @@
+# src/portmap/cli.py
+import argparse
+import uvicorn
+from pathlib import Path
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="portmap",
+        description="Real-time dashboard for local listening ports."
+    )
+    parser.add_argument(
+        "--port", "-p",
+        type=int,
+        default=7474,
+        help="Port to run the Portmap dashboard on (default: 7474)"
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host to bind to (default: 127.0.0.1)"
+    )
+    parser.add_argument(
+        "--version", "-v",
+        action="version",
+        version="%(prog)s 1.1.0"
+    )
+    args = parser.parse_args()
+
+    print(f"Portmap running at http://{args.host}:{args.port}")
+    uvicorn.run(
+        "portmap.main:app",
+        host=args.host,
+        port=args.port,
+        log_level="warning"   # suppress uvicorn noise, portmap speaks for itself
+    )
+
+
+if __name__ == "__main__":
+    main()