Metadata-Version: 2.4
Name: portviz
Version: 1.0.1
Summary: Windows-based real-time port inspection CLI tool
Author: Aadish Sonawane
License: MIT License
        
        Copyright (c) 2026 Aadish Sonawane
        
        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.
        
Project-URL: Homepage, https://github.com/yourusername/portviz
Project-URL: Repository, https://github.com/yourusername/portviz
Keywords: ports,network,cli,windows,monitoring,netstat,inspection
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: Microsoft :: Windows
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Topic :: System :: Networking
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Requires-Dist: platformdirs>=3.0.0
Requires-Dist: pyfiglet>=0.8
Dynamic: license-file

# Portviz  
**Cross-Platform Port & Process Manager for Developers**

Portviz is a developer-focused CLI tool for inspecting active network ports, identifying bound processes, monitoring service changes in real time, and safely terminating processes — all through a structured, consistent interface.

It eliminates the need for OS-specific commands like `netstat`, `lsof`, or `taskkill` during development and provides a unified workflow for managing ports across environments.

---

## 🚀 Vision

Portviz is being built in structured phases:

- ✅ Core port inspection engine (Python)
- ✅ Production-ready CLI with rich output and JSON streaming
- 🔄 Cross-platform abstraction (Windows → macOS/Linux expansion)
- 🔜 VS Code extension for in-editor visibility and control
- 🔜 Project-level service & port orchestration layer

The long-term goal is to evolve Portviz into a modular developer utility that integrates seamlessly into modern development workflows.

---

## 🎯 Problem It Solves

During development:

- Servers may crash but keep ports occupied  
- “Port already in use” errors interrupt workflow  
- Identifying and killing processes requires OS-specific commands  
- Managing multiple services across different ports becomes tedious  

Traditional commands:

- macOS/Linux → `lsof -i :3000` + `kill -9 <PID>`
- Windows → `netstat -ano` + `taskkill /PID <PID>`

Portviz abstracts these differences and provides a clean, consistent CLI interface.

---

## 📦 Current Features (v1.0.0)

### 🔎 Port Inspection
- Full port report
- Summarized port statistics
- LISTEN-only filtering
- Public vs local-only port detection
- Dual-stack (IPv4 + IPv6) detection
- Per-port inspection

### 🧠 Process Management
- Kill by PID
- Kill by port (auto-detect associated processes)
- Structured termination results
- Safe PID mapping

### 📸 Snapshot System
- Save current port state
- List saved snapshots
- Diff snapshots (detect new/closed services)

### 👀 Real-Time Monitoring
- Live dashboard mode (Rich-based UI)
- Stream mode for lightweight monitoring
- NDJSON streaming for automation pipelines
- Event-based service start/stop detection

### 🧾 JSON Support
All major commands support structured JSON output for:
- Automation
- Logging
- External integrations
- Tool chaining

---

## 🏗 Architecture Overview

Portviz follows a layered, modular architecture:

### 1️⃣ Core Engine
- OS detection
- System command execution
- Raw output parsing
- Structured data normalization
- Port summary generation
- Safe process termination

### 2️⃣ CLI Layer
- Argparse-based command routing
- Rich-formatted dashboard
- JSON output layer
- Snapshot management
- Watch/event streaming

### 3️⃣ Storage Layer
- Snapshot persistence via `platformdirs`
- OS-specific user data directories
- Structured snapshot diffing

This separation ensures the core engine remains reusable for IDE extensions or external tooling.

---

## 🧠 How It Works

1. Detect operating system
2. Execute appropriate networking command:
   - Windows → `netstat -ano`
   - macOS/Linux → `lsof -i -P -n` (planned full support)
3. Capture raw output
4. Parse into structured objects:
   - Protocol
   - Local IP
   - Local Port
   - Foreign IP
   - State
   - PID
   - Process name
5. Normalize into internal models
6. Provide CLI, snapshot, or streaming output
7. Allow safe termination via PID mapping

---

## 🖥 Example Usage

```bash
portviz
portviz report
portviz report --json
portviz summary
portviz list --public
portviz port 3000
portviz kill --port 3000
portviz snapshot save
portviz snapshot diff
portviz watch
portviz watch --stream --json
```

---

## 🧩 Project Structure

```
portviz/
│
├── pyproject.toml
├── README.md
└── portviz/
    ├── actions/
    ├── cli/
    ├── collectors/
    ├── core/
    ├── storage/
    ├── version.py
    ├── __main__.py
    └── services.py
```

The project uses modern Python packaging (`pyproject.toml`) and publishes via PyPI.

---

## 🔮 Future Enhancements

### 🔄 Full Cross-Platform Engine
- macOS & Linux parity
- Unified abstraction layer
- Command normalization improvements

### 🧩 Project-Level Service Management
- Workspace-based service configuration
- Define:
  - Service name
  - Port
  - Start command
  - Dependencies
  - Service type
- One-click startup of all services
- Conflict detection
- Health monitoring

### 🗺 Service Topology Visualization
- Visual frontend–backend–database representation
- Live service status indicators
- Architecture overview inside VS Code

### ⚙ Developer Experience Improvements
- Interactive CLI mode
- Smart port conflict suggestions
- Docker container awareness
- Permission safety checks
- Performance optimizations
- Configurable watch intervals
- Event schema versioning

---

## 🧠 Long-Term Scope

- PyPI distribution (completed)
- npm wrapper for JavaScript ecosystem
- VS Code Marketplace extension
- Project-level service orchestration
- Local development architecture visualization
- Developer workflow automation toolkit

---

## 🔧 Tech Stack

- Python 3.9+
- Rich (terminal UI)
- Pyfiglet (CLI banner)
- Platformdirs (OS-specific storage)
- Subprocess-based system command execution
- Structured CLI architecture

---

## 📌 Status

Stable v1.0.0 release.

Core CLI engine is production-ready.  
Cross-platform expansion and IDE integration are planned next phases.

---

## 📄 License

MIT License.

