portinspector 0.1.0__tar.gz

portinspector-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint & Format Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Run Ruff Lint
+        run: uv run --with ruff ruff check .
+
+      - name: Run Ruff Format Check
+        run: uv run --with ruff ruff format --check .
+
+  test:
+    name: Test (${{ matrix.os }} - Py ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Run Pytest
+        run: uv run --python ${{ matrix.python-version }} --with pytest pytest -v
+
+  build-check:
+    name: Build & Package Validation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Validate distribution metadata
+        run: uv run --with twine twine check dist/*

portinspector-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    name: Build and Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/portinspector
+    permissions:
+      id-token: write  # Mandatory for PyPI Trusted Publishing
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Verify distribution archives
+        run: uv run --with twine twine check dist/*
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

portinspector-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+test_env/
+
+# IDE files
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.ruff_cache/
+
+# Local OS files
+.DS_Store
+Thumbs.db

portinspector-0.1.0/AGENTS.md

@@ -0,0 +1,85 @@
+# AGENTS.md - PortInspector Contributor Guide for AI Agents
+
+This document provides architectural context, development constraints, and design principles for AI coding agents modifying or extending PortInspector.
+
+---
+
+## Core Principles & Constraints
+
+1. **Zero Runtime Dependencies**:
+   - The production package must remain dependency-free (`dependencies = []` in `pyproject.toml`).
+   - Use Python standard library modules (`ctypes`, `socket`, `subprocess`, `argparse`, `dataclasses`, `json`, etc.).
+   - Do not add packages like `click`, `typer`, `psutil`, or `rich` to core dependencies.
+
+2. **Cross-Platform Architecture**:
+   - Platform implementations are strictly isolated inside `src/portinspector/platform/`:
+     - `windows.py`: IP Helper API (`iphlpapi.dll`) via `ctypes` + `netstat -ano` fallback.
+     - `linux.py`: `/proc/net/tcp`, `/proc/net/udp` + `/proc/<pid>/fd` procfs inspection + `ss` fallback.
+     - `macos.py`: `lsof -nP` + BSD `netstat -anv` fallback.
+     - `base.py`: Abstract `PlatformProvider` interface.
+     - `__init__.py`: Dynamic dispatcher returning provider instance based on `sys.platform`.
+   - Never assume Unix-only commands (`lsof`, `ss`) are available on all machines.
+   - Always handle `PermissionError`, missing files, and unreadable PIDs gracefully. Read-only commands must never crash when permissions are restricted.
+
+3. **Safety First**:
+   - `--kill PORT` must never terminate a process automatically unless `--yes` / `-y` is provided.
+   - Always display process details and a prominent warning banner prior to the confirmation prompt.
+
+4. **Testing Constraints**:
+   - **Never hardcode static ports** (e.g. 8000, 3000, 5000) as assumed free or occupied in tests.
+   - **Use ephemeral sockets** (`sock.bind(("127.0.0.1", 0))`) in pytest fixtures to test active and available detection deterministically.
+   - **No external network calls**: Tests must pass completely offline.
+   - When testing platform-specific modules on other host operating systems, mock file access or OS calls.
+
+---
+
+## Repository Layout
+
+```
+src/portinspector/
+├── __init__.py           # __version__ export
+├── __main__.py          # Entrypoint for python -m portinspector
+├── cli.py               # Argument parser and command routing
+├── models.py            # PortInfo, ProcessInfo, ScanSummary
+├── checker.py           # Single-port inspection, range scanning, port availability
+├── kill.py              # Process termination with safety confirmation
+├── watch.py             # Periodic port monitoring
+├── formatter.py         # Table, detail, summary, and JSON formatters
+└── platform/
+    ├── __init__.py      # Platform detector and provider factory
+    ├── base.py          # PlatformProvider interface
+    ├── windows.py       # Windows ctypes IP Helper + netstat
+    ├── linux.py         # Linux procfs + ss
+    └── macos.py         # macOS lsof + netstat
+tests/
+├── conftest.py          # Shared fixtures (ephemeral test sockets, mock providers)
+├── test_cli.py          # CLI integration tests
+├── test_parsing.py      # Port and port range input parsing tests
+├── test_checker.py      # Port availability, range scanning, and inspection tests
+├── test_platform.py     # Windows, Linux, and macOS provider tests
+├── test_json.py         # JSON schema tests across all commands
+├── test_kill.py         # Termination confirmation and safety tests
+└── test_watch.py        # Event monitoring and diff detection tests
+```
+
+---
+
+## Verification Commands
+
+Before concluding any work, always execute:
+```bash
+# Run test suite
+uv run --with pytest pytest -v
+
+# Run linting
+uv run --with ruff ruff check .
+
+# Run formatting checks
+uv run --with ruff ruff format --check .
+
+# Build package
+uv build
+
+# Validate package distribution
+uv run --with twine twine check dist/*
+```

portinspector-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-21
+
+### Added
+- Initial release of `portinspector`, a lightweight cross-platform CLI developer utility for inspecting local ports and processes.
+- Default command `portinspector` to list all currently active and listening local ports with protocol, address, status, PID, and process name.
+- Single port inspection `portinspector PORT` clearly reporting `ACTIVE/LISTENING` or `AVAILABLE` status.
+- Filter flag `portinspector --active` to display active/listening ports.
+- Range scanner `portinspector --scan START-END` to quickly scan and summarize active vs available ports.
+- Port finder `portinspector --find` and `portinspector --find PORT` to find next available local ports.
+- Process inspector `portinspector --process PORT` to display executable path, command line, status, and parent PID.
+- Process termination `portinspector --kill PORT` with mandatory interactive confirmation and `--yes` automation flag.
+- Real-time watch mode `portinspector --watch` with configurable polling interval `--interval SECONDS`.
+- Structured JSON output `portinspector --json` across all query and inspection commands.
+- Isolated platform implementations:
+  - Windows: IP Helper API (`iphlpapi.dll`) via `ctypes` and `netstat -ano` fallback.
+  - Linux: procfs `/proc/net/{tcp,tcp6,udp,udp6}` and `/proc/<pid>/fd` with `ss` fallback.
+  - macOS: `lsof` and BSD `netstat -anv` with `ps` fallback.
+- Comprehensive test suite with ephemeral test socket fixtures.
+- GitHub Actions multi-OS CI and PyPI release workflows.

portinspector-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to PortInspector
+
+Thank you for your interest in contributing to PortInspector! We welcome bug fixes, documentation improvements, and platform enhancements.
+
+---
+
+## Development Setup
+
+PortInspector requires **Python 3.10+** and has zero runtime dependencies. We recommend using [uv](https://github.com/astral-sh/uv) for development.
+
+### 1. Clone the Repository
+```bash
+git clone https://github.com/ramalingamthangamani/PortCheck.git
+cd PortCheck
+```
+
+### 2. Set Up Virtual Environment & Dependencies
+Using `uv`:
+```bash
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]" pytest ruff build twine
+```
+
+Or using standard `venv` and `pip`:
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -e .
+pip install pytest ruff build twine
+```
+
+---
+
+## Running the Test Suite
+
+Run all unit and integration tests:
+
+```bash
+uv run --with pytest pytest -v
+```
+
+### Test Design Guidelines
+- **No hardcoded machine ports**: Never assume ports like 8000 or 3000 are free or busy. Use the shared test socket fixtures (`ephemeral_port`, `bound_socket`) which bind to port `0` or loopback addresses.
+- **No external network calls**: Tests must not make network requests to external hosts or APIs. All tests must be self-contained and run completely offline.
+- **Platform isolation**: When writing platform-specific tests (e.g. for Windows ctypes, Linux procfs, or macOS lsof), mock or isolate the operating system calls so test suites pass consistently across any host OS.
+
+---
+
+## Code Quality & Linting
+
+We use [Ruff](https://github.com/astral-sh/ruff) for linting and code formatting:
+
+```bash
+# Check code style and rules
+uv run --with ruff ruff check .
+
+# Check formatting
+uv run --with ruff ruff format --check .
+
+# Automatically apply formatting
+uv run --with ruff ruff format .
+```
+
+---
+
+## Building and Checking the Distribution
+
+Validate package packaging and PyPI metadata:
+
+```bash
+uv build
+uv run --with twine twine check dist/*
+```
+
+---
+
+## Submitting Pull Requests
+
+1. Create a feature branch: `git checkout -b feature/my-enhancement`.
+2. Ensure all tests pass and Ruff checks succeed.
+3. Keep commits focused, descriptive, and atomic.
+4. Submit a Pull Request targeting the `main` branch.

portinspector-0.1.0/LICENSE

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

portinspector-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: portinspector
+Version: 0.1.0
+Summary: Lightweight cross-platform CLI developer utility for inspecting network ports and processes
+Project-URL: Homepage, https://github.com/ramalingamthangamani/PortCheck
+Project-URL: Documentation, https://github.com/ramalingamthangamani/PortCheck#readme
+Project-URL: Issues, https://github.com/ramalingamthangamani/PortCheck/issues
+Project-URL: Repository, https://github.com/ramalingamthangamani/PortCheck.git
+Author: PortInspector Contributors
+License: MIT
+License-File: LICENSE
+Keywords: cli,developer-tools,lsof,netstat,network,port,portcheck,portinspector,process
+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 :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# PortInspector
+
+[![CI](https://github.com/ramalingamthangamani/PortCheck/actions/workflows/ci.yml/badge.svg)](https://github.com/ramalingamthangamani/PortCheck/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/portinspector.svg)](https://pypi.org/project/portinspector/)
+[![Python versions](https://img.shields.io/pypi/pyversions/portinspector.svg)](https://pypi.org/project/portinspector/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**PortInspector** is a lightweight, cross-platform developer utility for inspecting local network ports and the processes using them.
+
+Built with pure Python standard library primitives, PortInspector requires **zero runtime dependencies**, installs instantly, and works across **Windows**, **Linux**, and **macOS**.
+
+---
+
+## Key Features
+
+- **Instant Visibility**: See all active and listening ports, addresses, PIDs, and process names in milliseconds.
+- **Port Inspection**: Quickly check if a specific port is `ACTIVE/LISTENING` or `AVAILABLE`.
+- **Port Finder**: Find the next available local port for web servers and microservices.
+- **Fast Range Scanning**: Scan thousands of ports in milliseconds using OS connection caching.
+- **Process Inspection**: View detailed process metadata (PID, executable path, command line, parent PID).
+- **Safe Process Termination**: Kill hung processes with mandatory interactive confirmation and `--yes` automation support.
+- **Continuous Watch Mode**: Real-time port monitoring that alerts when ports open or close.
+- **Structured JSON Output**: Full `--json` support across commands for CI/CD pipelines, dev tooling, and scripts.
+- **Zero Dependencies**: Pure Python with native platform integrations. No heavy C extensions or compilation required.
+
+---
+
+## Installation
+
+```bash
+pip install portinspector
+```
+
+Or using [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv tool install portinspector
+```
+
+---
+
+## Quick Reference
+
+| Command | Description |
+| :--- | :--- |
+| `portinspector` | Show all active/listening local ports with process details |
+| `portinspector 8000` | Inspect port 8000 (status, process, PID, protocol, address) |
+| `portinspector --active` | Show only active/listening ports |
+| `portinspector --scan 3000-9000` | Scan a port range and summarize active vs available ports |
+| `portinspector --find` | Find an available local port (defaults to starting at 8000) |
+| `portinspector --find 8000` | Start at port 8000 and find the next available port |
+| `portinspector --process 8000` | Show detailed process information for the process on port 8000 |
+| `portinspector --kill 8000` | Terminate the process using port 8000 (interactive confirmation) |
+| `portinspector --kill 8000 --yes` | Terminate the process using port 8000 without prompting |
+| `portinspector --watch` | Continuously monitor ports and report opened/closed events |
+| `portinspector --watch --interval 2` | Monitor ports with a custom polling interval in seconds |
+| `portinspector --json` | Output structured JSON suitable for scripts and automation |
+| `portinspector --version` | Display version number |
+| `portinspector --help` | Display help and usage manual |
+
+---
+
+## Usage Examples
+
+### 1. List Active & Listening Ports
+```bash
+$ portinspector
+PORT   PROTO  ADDRESS                    STATUS  PID    PROCESS
+-----  -----  -------------------------  ------  -----  ---------------
+22     TCP    0.0.0.0                    LISTEN  7104   sshd.exe
+80     TCP    0.0.0.0                    LISTEN  1234   nginx
+3000   TCP    127.0.0.1                  LISTEN  9821   node.exe
+8000   TCP    127.0.0.1                  LISTEN  4218   python.exe
+```
+
+### 2. Inspect a Specific Port
+```bash
+$ portinspector 8000
+Port 8000:
+  Status:      ACTIVE/LISTENING
+  Protocol:    TCP
+  Address:     127.0.0.1
+  Process:     python.exe
+  PID:         4218
+```
+
+If the port is free:
+```bash
+$ portinspector 8001
+Port 8001:
+  Status:      AVAILABLE
+  Message:     Port 8001 is available for use.
+```
+
+### 3. Find Next Available Port
+Useful for configuring dev servers or automated tests:
+```bash
+$ portinspector --find 8000
+Port 8000 is ACTIVE/LISTENING. Next available port is 8001.
+
+$ portinspector --find 8000 --json
+{
+  "start_port": 8000,
+  "available_port": 8001,
+  "is_available": true
+}
+```
+
+### 4. Scan a Port Range
+```bash
+$ portinspector --scan 3000-3005
+Port Scan Summary (3000-3005):
+  Total Scanned:    6
+  Active Ports:     2
+  Available Ports:  4
+
+Active Ports:
+PORT   PROTO  ADDRESS    STATUS  PID    PROCESS
+-----  -----  ---------  ------  -----  -------
+3000   TCP    127.0.0.1  LISTEN  9821   node.exe
+3001   TCP    127.0.0.1  LISTEN  9822   vite.exe
+
+Available Ports:
+  3002, 3003, 3004, 3005
+```
+
+### 5. Detailed Process Information
+```bash
+$ portinspector --process 8000
+Process Details (Port 8000):
+  PID:         4218
+  Name:        python.exe
+  Status:      running
+  Executable:  C:\Users\developer\AppData\Local\Programs\Python\Python310\python.exe
+  Command:     python -m http.server 8000
+  Parent PID:  1024
+  Ports Used:  8000
+```
+
+### 6. Terminate a Process Using a Port
+PortInspector prioritizes safety. Process termination always prompts for explicit confirmation unless `--yes` is passed:
+
+```bash
+$ portinspector --kill 8000
+============================================================
+WARNING: DANGEROUS OPERATION - PROCESS TERMINATION
+============================================================
+Terminating this process will immediately close its network sockets
+and may cause unsaved data loss or crash dependent applications.
+
+  Port:         8000
+  PID:          4218
+  Process Name: python.exe
+  Path:         C:\Users\developer\AppData\Local\Programs\Python\Python310\python.exe
+  Command:      python -m http.server 8000
+============================================================
+Are you sure you want to terminate process 4218 (python.exe)? [y/N]: y
+Successfully terminated process 4218 (python.exe) on port 8000.
+```
+
+For non-interactive scripts:
+```bash
+portinspector --kill 8000 --yes
+```
+
+### 7. Real-Time Watch Mode
+Monitor ports dynamically as services spin up or shut down:
+```bash
+$ portinspector --watch --interval 1.5
+[13:30:00] Monitoring listening ports every 1.5s (Press Ctrl+C to stop)...
+[13:30:00] Initial state: 18 listening ports detected.
+[13:30:04] [OPENED] Port 5173 (TCP) on 127.0.0.1 by vite (PID: 14205)
+[13:30:22] [CLOSED] Port 5173 (TCP) (was vite (PID: 14205))
+^C
+[13:30:30] Monitoring stopped.
+```
+
+---
+
+## Platform Support & Architecture
+
+PortInspector implements isolated, native OS providers:
+
+- **Windows (`src/portinspector/platform/windows.py`)**:
+  - Leverages the Windows IP Helper API (`iphlpapi.dll`) via `ctypes` (`GetExtendedTcpTable`, `GetExtendedUdpTable`).
+  - Fetches complete TCP and UDP connection tables directly in-memory without spawning slow subprocesses.
+  - Fallback parser for `netstat -ano`.
+  - Process queries via `kernel32` (`QueryFullProcessImageNameW`) and WMI.
+- **Linux (`src/portinspector/platform/linux.py`)**:
+  - Reads `/proc/net/tcp`, `/proc/net/tcp6`, `/proc/net/udp`, `/proc/net/udp6`.
+  - Resolves socket inodes to PIDs via `/proc/<pid>/fd/*`.
+  - Fallback parser for `ss` or `netstat`.
+  - Reads `/proc/<pid>/comm`, `cmdline`, `status`, and `exe`.
+- **macOS (`src/portinspector/platform/macos.py`)**:
+  - Built-in `lsof` parser with fallback to BSD `netstat -anv`.
+  - Process metadata via `ps`.
+
+### Permissions
+- **Read-Only Inspection**: Administrator/root privileges are **never required** for normal scanning.
+- **Permission Handling**: When a process is owned by another user or system account, PortInspector still reports the active port, protocol, and address gracefully while noting when PID details are restricted by OS security boundaries.
+- **Process Termination**: Terminating processes owned by other users or system services requires elevated privileges.
+
+---
+
+## License
+
+This project is licensed under the terms of the [MIT License](LICENSE).