portctl 0.1.1__tar.gz

portctl-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install ruff mypy
+      - run: ruff check src/
+      - run: mypy src/portctl/ --ignore-missing-imports
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+          - ubuntu-24.04-arm
+          - macos-latest
+          - windows-latest
+          - windows-11-arm
+        python-version: ["3.9", "3.12", "3.13"]
+        exclude:
+          - os: windows-11-arm
+            python-version: "3.9"
+          - os: ubuntu-24.04-arm
+            python-version: "3.9"
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .
+      - run: portctl --version
+      - run: portctl --help

portctl-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release & Publish
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Get version from pyproject.toml
+        id: version
+        run: |
+          VERSION=$(grep '^version' pyproject.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Check if tag exists
+        id: check
+        run: |
+          if git rev-parse "v${{ steps.version.outputs.version }}" >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create release
+        if: steps.check.outputs.exists == 'false'
+        run: |
+          gh release create "${{ steps.version.outputs.tag }}" \
+            --title "${{ steps.version.outputs.tag }}" \
+            --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Build and publish always run — skip-existing makes re-runs safe
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: pip install build && python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

portctl-0.1.1/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tools
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

portctl-0.1.1/LICENSE

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

portctl-0.1.1/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: portctl
+Version: 0.1.1
+Summary: Manage your ports — view, inspect, and kill processes on TCP ports
+Project-URL: Homepage, https://github.com/mubbie/portctl
+Project-URL: Repository, https://github.com/mubbie/portctl
+Project-URL: Issues, https://github.com/mubbie/portctl/issues
+Author: Mubbie Idoko
+License: MIT
+License-File: LICENSE
+Keywords: cli,devtools,network,ports,process
+Classifier: Development Status :: 4 - Beta
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: psutil>=5.9
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Description-Content-Type: text/markdown
+
+# portctl
+
+> Manage your ports.
+
+A cross-platform Python CLI tool for viewing, managing, and killing processes on TCP ports.
+
+Inspired by [port-whisperer](https://github.com/LarsenCundric/port-whisperer) by [Larsen Cundric](https://x.com/larsencc).
+
+## What it looks like
+
+```bash
+$ portctl
+
+ ┌──────────────────────────────────────────┐
+ │ portctl                                  │
+ │ scanning your ports...                   │
+ └──────────────────────────────────────────┘
+
+  PORT    PROCESS      PID     PROJECT       FRAMEWORK      UPTIME   MEM        BIND     STATUS
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  :8000   python.exe   14320   payments-api  FastAPI        3h 12m   48.7 MB   public   ● healthy
+  :5173   node         52981   dashboard     Vite           22m      112.4 MB  local    ● healthy
+  :8080   go           8734    gateway       Go             6d 1h    23.1 MB   public   ● healthy
+  :5432   docker       7712    —             Docker (PG)    14d 8h   67.0 MB   local    ● healthy
+
+  4 ports active  ·  Run portctl <port> for details  ·  --all to show everything
+```
+
+```bash
+$ portctl 5173
+
+ ┌─────────────────────── Port :5173 ───────────────────────┐
+ │                                                          │
+ │  Process     node                                        │
+ │  PID         52981                                       │
+ │  Status      ● healthy                                   │
+ │  Framework   Vite                                        │
+ │  Memory      112.4 MB                                    │
+ │  Uptime      22m                                         │
+ │  Started     2026-04-04 10:15:42                         │
+ │  Bind        local (127.0.0.1)                           │
+ │  Command     node node_modules/.bin/vite --port 5173     │
+ │                                                          │
+ │  Directory   /home/mubarak/projects/dashboard            │
+ │  Project     dashboard                                   │
+ │  Git Branch  feat/charts                                 │
+ │                                                          │
+ │  Process Tree                                            │
+ │    → node (52981)                                        │
+ │      └─ bash (52900)                                     │
+ │        └─ tmux: server (1120)                            │
+ │                                                          │
+ └──────────────────────────────────────────────────────────┘
+
+  Run portctl kill 5173 to stop  ·  portctl cmd 5173 to see startup command
+```
+
+```bash
+$ portctl 8000-8100
+
+  :8000 python.exe (PID 14320) [FastAPI]
+  :8001 free
+  :8002 free
+  ...
+  :8080 go (PID 8734) [Go]
+  :8081 free
+  ...
+  :8100 free
+```
+
+```bash
+$ portctl free 5173 -- npm run dev
+
+  ✓ Killed node (PID 52981) on port 5173
+  Running: npm run dev
+```
+
+```bash
+$ portctl kill 8000 8080
+
+  ✓ Killed python.exe (PID 14320) on port 8000
+  ✓ Killed go (PID 8734) on port 8080
+```
+
+## Install
+
+```bash
+pip install portctl
+# or
+pipx install portctl
+```
+
+## Quick Start
+
+```bash
+portctl                    # Show dev server ports
+portctl 3000               # Inspect what's on port 3000
+portctl kill 3000           # Kill it
+```
+
+## Commands
+
+### List ports
+
+```bash
+portctl                    # Dev server ports only
+portctl --all              # All listening ports
+portctl --sort mem         # Sort by memory (also: uptime)
+portctl -f django          # Filter by process, framework, or project
+portctl -n 5               # Limit to top N rows
+```
+
+### Inspect a port
+
+```bash
+portctl 3000               # Detail view if occupied, "available" if free
+```
+
+Shows process info, framework, memory, uptime, bind address, working directory, git branch, and process tree.
+
+### Scan a range
+
+```bash
+portctl 8000-9000          # Show which ports are in use
+```
+
+### Kill processes
+
+```bash
+portctl kill 3000          # Kill process on port 3000
+portctl kill 3000 8080     # Kill multiple ports
+portctl kill 3000 --force  # Force kill (SIGKILL)
+portctl kill 3000 --dry-run  # Preview without killing
+```
+
+### Free a port and run a command
+
+```bash
+portctl free 3000 -- npm start      # Kill port 3000, then run npm start
+portctl free 3000 5432 -- docker compose up  # Free multiple, then run
+```
+
+### Show startup command
+
+```bash
+portctl cmd 3000           # Print the command that started the process
+portctl cmd 3000 --copy    # Copy it to clipboard
+```
+
+### Utilities
+
+```bash
+portctl open 3000          # Open http://localhost:3000 in browser
+portctl copy 3000          # Copy http://localhost:3000 to clipboard
+portctl clean              # Kill orphaned/zombie dev processes
+portctl clean --dry-run    # Preview without killing
+```
+
+## Features
+
+- **Cross-platform** -- works on macOS, Linux, and Windows
+- **Framework detection** -- identifies Next.js, Vite, Django, FastAPI, Flask, Express, and 20+ others
+- **Project detection** -- finds project root and name from package.json, pyproject.toml, Cargo.toml, etc.
+- **Smart filtering** -- shows only dev processes by default, use `--all` for everything
+- **Protected processes** -- refuses to kill system-critical processes (systemd, lsass, etc.)
+- **Git branch** -- shows which branch each process is running from
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| macOS    | Supported (use `sudo` for full visibility) |
+| Linux    | Supported |
+| Windows  | Supported (admin recommended for full PID visibility) |
+
+## License
+
+MIT

portctl-0.1.1/README.md

@@ -0,0 +1,178 @@
+# portctl
+
+> Manage your ports.
+
+A cross-platform Python CLI tool for viewing, managing, and killing processes on TCP ports.
+
+Inspired by [port-whisperer](https://github.com/LarsenCundric/port-whisperer) by [Larsen Cundric](https://x.com/larsencc).
+
+## What it looks like
+
+```bash
+$ portctl
+
+ ┌──────────────────────────────────────────┐
+ │ portctl                                  │
+ │ scanning your ports...                   │
+ └──────────────────────────────────────────┘
+
+  PORT    PROCESS      PID     PROJECT       FRAMEWORK      UPTIME   MEM        BIND     STATUS
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  :8000   python.exe   14320   payments-api  FastAPI        3h 12m   48.7 MB   public   ● healthy
+  :5173   node         52981   dashboard     Vite           22m      112.4 MB  local    ● healthy
+  :8080   go           8734    gateway       Go             6d 1h    23.1 MB   public   ● healthy
+  :5432   docker       7712    —             Docker (PG)    14d 8h   67.0 MB   local    ● healthy
+
+  4 ports active  ·  Run portctl <port> for details  ·  --all to show everything
+```
+
+```bash
+$ portctl 5173
+
+ ┌─────────────────────── Port :5173 ───────────────────────┐
+ │                                                          │
+ │  Process     node                                        │
+ │  PID         52981                                       │
+ │  Status      ● healthy                                   │
+ │  Framework   Vite                                        │
+ │  Memory      112.4 MB                                    │
+ │  Uptime      22m                                         │
+ │  Started     2026-04-04 10:15:42                         │
+ │  Bind        local (127.0.0.1)                           │
+ │  Command     node node_modules/.bin/vite --port 5173     │
+ │                                                          │
+ │  Directory   /home/mubarak/projects/dashboard            │
+ │  Project     dashboard                                   │
+ │  Git Branch  feat/charts                                 │
+ │                                                          │
+ │  Process Tree                                            │
+ │    → node (52981)                                        │
+ │      └─ bash (52900)                                     │
+ │        └─ tmux: server (1120)                            │
+ │                                                          │
+ └──────────────────────────────────────────────────────────┘
+
+  Run portctl kill 5173 to stop  ·  portctl cmd 5173 to see startup command
+```
+
+```bash
+$ portctl 8000-8100
+
+  :8000 python.exe (PID 14320) [FastAPI]
+  :8001 free
+  :8002 free
+  ...
+  :8080 go (PID 8734) [Go]
+  :8081 free
+  ...
+  :8100 free
+```
+
+```bash
+$ portctl free 5173 -- npm run dev
+
+  ✓ Killed node (PID 52981) on port 5173
+  Running: npm run dev
+```
+
+```bash
+$ portctl kill 8000 8080
+
+  ✓ Killed python.exe (PID 14320) on port 8000
+  ✓ Killed go (PID 8734) on port 8080
+```
+
+## Install
+
+```bash
+pip install portctl
+# or
+pipx install portctl
+```
+
+## Quick Start
+
+```bash
+portctl                    # Show dev server ports
+portctl 3000               # Inspect what's on port 3000
+portctl kill 3000           # Kill it
+```
+
+## Commands
+
+### List ports
+
+```bash
+portctl                    # Dev server ports only
+portctl --all              # All listening ports
+portctl --sort mem         # Sort by memory (also: uptime)
+portctl -f django          # Filter by process, framework, or project
+portctl -n 5               # Limit to top N rows
+```
+
+### Inspect a port
+
+```bash
+portctl 3000               # Detail view if occupied, "available" if free
+```
+
+Shows process info, framework, memory, uptime, bind address, working directory, git branch, and process tree.
+
+### Scan a range
+
+```bash
+portctl 8000-9000          # Show which ports are in use
+```
+
+### Kill processes
+
+```bash
+portctl kill 3000          # Kill process on port 3000
+portctl kill 3000 8080     # Kill multiple ports
+portctl kill 3000 --force  # Force kill (SIGKILL)
+portctl kill 3000 --dry-run  # Preview without killing
+```
+
+### Free a port and run a command
+
+```bash
+portctl free 3000 -- npm start      # Kill port 3000, then run npm start
+portctl free 3000 5432 -- docker compose up  # Free multiple, then run
+```
+
+### Show startup command
+
+```bash
+portctl cmd 3000           # Print the command that started the process
+portctl cmd 3000 --copy    # Copy it to clipboard
+```
+
+### Utilities
+
+```bash
+portctl open 3000          # Open http://localhost:3000 in browser
+portctl copy 3000          # Copy http://localhost:3000 to clipboard
+portctl clean              # Kill orphaned/zombie dev processes
+portctl clean --dry-run    # Preview without killing
+```
+
+## Features
+
+- **Cross-platform** -- works on macOS, Linux, and Windows
+- **Framework detection** -- identifies Next.js, Vite, Django, FastAPI, Flask, Express, and 20+ others
+- **Project detection** -- finds project root and name from package.json, pyproject.toml, Cargo.toml, etc.
+- **Smart filtering** -- shows only dev processes by default, use `--all` for everything
+- **Protected processes** -- refuses to kill system-critical processes (systemd, lsass, etc.)
+- **Git branch** -- shows which branch each process is running from
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| macOS    | Supported (use `sudo` for full visibility) |
+| Linux    | Supported |
+| Windows  | Supported (admin recommended for full PID visibility) |
+
+## License
+
+MIT

portctl-0.1.1/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "portctl"
+version = "0.1.1"
+description = "Manage your ports — view, inspect, and kill processes on TCP ports"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Mubbie Idoko"},
+]
+keywords = ["ports", "cli", "devtools", "process", "network"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: System :: Networking",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "psutil>=5.9",
+    "rich>=13.0",
+    "typer>=0.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/mubbie/portctl"
+Repository = "https://github.com/mubbie/portctl"
+Issues = "https://github.com/mubbie/portctl/issues"
+
+[project.scripts]
+portctl = "portctl.cli:_cli_entry"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/portctl"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true

portctl-0.1.1/src/portctl/__init__.py

@@ -0,0 +1,7 @@
+"""portctl — manage your ports.
+
+A cross-platform CLI for viewing, inspecting, and killing processes on TCP ports.
+Uses psutil for cross-platform support (macOS, Linux, Windows).
+"""
+
+__version__ = "0.1.1"

portctl-0.1.1/src/portctl/classifier.py

@@ -0,0 +1,43 @@
+"""Signal-based dev process classification.
+
+Uses positive signals to identify dev processes rather than maintaining
+platform-specific blocklists. A process is "dev" if ANY signal fires.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from portctl.scanner import ProcessInfo
+
+from portctl.frameworks import KNOWN_RUNTIMES, is_docker_process
+
+
+def _signal_has_project_root(proc: ProcessInfo) -> bool:
+    return proc.project_root is not None
+
+
+def _signal_known_runtime(proc: ProcessInfo) -> bool:
+    if not proc.normalized_name:
+        return False
+    return proc.normalized_name in KNOWN_RUNTIMES
+
+
+def _signal_docker_process(proc: ProcessInfo) -> bool:
+    return is_docker_process(proc.process_name)
+
+
+def _signal_has_framework(proc: ProcessInfo) -> bool:
+    """If detect_framework already identified a framework, it's a dev process."""
+    return proc.framework is not None
+
+
+def is_dev_process(proc: ProcessInfo) -> bool:
+    """Returns True if ANY signal fires. Use --all to bypass."""
+    return (
+        _signal_has_project_root(proc)
+        or _signal_known_runtime(proc)
+        or _signal_docker_process(proc)
+        or _signal_has_framework(proc)
+    )