v3.2.4

🚀 kport v3.2.4 — Release Notes

Release Date: June 15, 2026
Tag: v3.2.4
Previous Version: v3.2.3

---

Overview

kport 3.2.4 is a packaging and configuration release. It adds cross-platform application icons, improves packaging consistency, enhances VS Code extension configuration, and updates the project license metadata to comply with PEP 621 standards.

---

🆕 New Features

🎨 Cross-Platform Application Icons

kport now includes professional application icons for all platforms:

New assets:

• assets/icons/windows/ — Windows .ico format for installers and system integration
• assets/icons/macos/ — macOS .icns format for app bundles
• assets/icons/linux/ — PNG icons in multiple sizes (16x16, 32x32, 64x64, 128x128, 256x256)

Icons are integrated into:

• Windows installer (NSIS)
• macOS app bundle and DMG
• Linux package managers (DEB, RPM, Snap)
• VS Code extension marketplace

---

📦 Improved VS Code Extension Configuration

Enhanced vscode-extension/ with:

• Refined package.json configuration for better marketplace visibility
• Updated icon references and branding consistency
• Improved MCP server integration documentation

---

🐛 Bug Fixes

License metadata compliance (PEP 621)

Root cause: pyproject.toml used non-standard license field format that may not be recognized by modern Python packaging tools.

Fix:

• Updated project.license to comply with PEP 621 standard
• License metadata now properly recognized by pip, poetry, and other modern tools
• Verified compatibility with setuptools 70.0+

---

🔄 CI/CD Improvements

Enhanced packaging workflows:

• Icon assets integrated into all package build scripts
• Improved icon path handling across platforms
• Better validation of icon formats during CI

---

📋 Full Changelog

Commit	Type	Summary
14a027e	feat	Add cross-platform packaging, application icons, and VS Code extension configuration
392a1dd	fix	Update project.license to comply with PEP 621

---

🔄 Backward Compatibility

✅ Fully backward compatible with kport 3.2.3.

All existing commands, flags, and configurations continue to work without modification.

---

📦 Installation

Platform	Command
PyPI	pip install kport==3.2.4
Linux DEB	See Releases
Linux RPM	See Releases
Linux Snap	snap install kport
macOS	See Releases
Windows EXE	See Releases
Windows Chocolatey	choco install kport
VS Code	Extensions marketplace → search "KPort"

---

🛠️ For Developers & Maintainers

Building from Source

# Prerequisites check
python kport_orchestrate.py --check

# Build everything
python kport_orchestrate.py --build-all

# Build individual formats
python kport_orchestrate.py --build-pypi    # PyPI wheel + sdist
python kport_orchestrate.py --build-vscode  # VS Code .vsix
python kport_orchestrate.py --build-snap    # Snap package

Publishing

# Publish everything (requires credentials in env)
python kport_orchestrate.py --publish-all

# Publish individually
python publish.py                              # PyPI (TWINE_PASSWORD required)
python vscode_build.py --publish               # VS Code Marketplace (VSCE_PAT required)
python snap_publish.py --publish --channel stable  # Snap Store (snapcraft login required)

Running Tests

python run_tests.py
# or
pytest tests/ -v

See BUILD_GUIDE.md for full documentation.

---

📖 Resources

• GitHub Repository
• PyPI Package
• Snap Package
• VS Code Extension
• Issue Tracker
• Build Guide
• Model Context Protocol

v3.2.3

🚀 kport v3.2.3 — Release Notes

Release Date: June 14, 2026
Tag: v3.2.3
Previous Version: v3.2.2

---

Overview

kport 3.2.3 is a feature and infrastructure release. It ships the official VS Code extension, expands package manager support to Chocolatey and Snap, adds smarter CLI diagnostics for permission-restricted processes, and resolves two critical CI regressions that broke PyPI and Snap publishing in the previous release cycle.

---

🆕 New Features

🖥️ Official VS Code Extension

The KPort VS Code extension brings port management directly into the editor:

Command	Description
KPort: Inspect Ports	View all active ports and associated processes
KPort: Free Port	Kill a process using a specific port
KPort: List Ports	Show all listening ports with process details
KPort: Configure MCP Server	Set up MCP server for AI assistant integration

MCP (Model Context Protocol) integration:

• On first activation, the extension prompts once to configure MCP for AI tools
• Automatically generates .vscode/mcp.json with correct stdio settings
• Works with Claude, GitHub Copilot, and any MCP-compatible client
• MCP can be reconfigured at any time via the Command Palette

Install from VS Code Marketplace:

Extensions (Ctrl+Shift+X) → search "KPort" → Install

Or via CLI:

code --install-extension farmanali.kport-vscode

New files: vscode-extension/ directory (TypeScript source, package.json, tsconfig.json, mcpConfig.ts, extension.ts)

---

📦 Chocolatey Package Support (Windows)

kport is now available via Chocolatey for Windows users:

choco install kport

New files:

• choco_build.py — builds .nupkg from a staged Windows .exe installer
• packaging/chocolatey/kport.nuspec.template
• packaging/chocolatey/tools/chocolateyinstall.ps1.template

---

📦 Snap Package Support (Linux)

kport is now available from the Snap Store:

snap install kport

New files:

• snap_build.py — builds .snap from source using snapcraft
• snap_publish.py — publishes to Snap Store with channel management (stable, candidate, edge)
• packaging/snap/snapcraft.yaml.template
• packaging/snap/launcher

---

🔨 Unified Build & Publish Tooling

New developer-facing scripts and documentation for streamlined release workflows:

• kport_orchestrate.py (formerly build.py — see Bug Fixes below)
  — Single interactive or CLI entry point for all build + publish operations

  python kport_orchestrate.py                 # interactive menu
  python kport_orchestrate.py --build-all     # CI: build everything
  python kport_orchestrate.py --publish-all   # CI: publish everything
  python kport_orchestrate.py --build-snap --publish-snap --snap-channel edge

• vscode_build.py — VS Code extension builder and publisher

  python vscode_build.py --build     # compile .vsix
  python vscode_build.py --install   # install locally
  python vscode_build.py --publish   # publish to VS Code Marketplace

• snap_publish.py — Snap Store publisher

  python snap_publish.py --publish --channel stable
  python snap_publish.py --publish --channel edge

• BUILD_GUIDE.md — Comprehensive developer documentation covering all build scripts, prerequisites, credentials, and release workflows.

---

⚠️ Smarter CLI Diagnostics: Inaccessible Process Warnings

When a kport command targets a process by name and finds the process but cannot see its port bindings, it now diagnoses the most common cause and tells you clearly:

Warning: No port bindings found matching 'myapp', but matching processes exist
(PID(s): 12345). Try running with sudo/admin privileges.

What changed in src/kport/cli.py:

• When port inspection returns no bindings but matching PIDs are found, kport checks whether the current user is root/admin
• If not elevated, it prints an actionable stderr warning with the relevant PID(s)
• Cross-platform: uses os.geteuid() on Linux/macOS and ctypes.windll.shell32.IsUserAnAdmin() on Windows
• No warning is shown if the user is already elevated (no false noise)

---

🐛 Bug Fixes

python -m build executed interactive menu instead of building wheels (PyPI CI failure)

Root cause: The repo contained a file named build.py. When the CI step ran python -m build, Python found the local build.py before the installed build pip package (because CWD is on sys.path). This launched the interactive orchestrator menu, which hit EOFError on input() in the non-TTY CI environment.

Fix:

• Renamed build.py → kport_orchestrate.py to eliminate the name collision entirely
• python -m build now correctly invokes the PyPI build frontend
• No workarounds needed in build_packages.py

Error installing snap 'core22' (Snap CI failure)

Root cause: ubuntu-latest runners (Ubuntu 24.04) use a restricted snapd sandbox that cannot download and install core22 from the Snap Store. The previous workflow used sudo snap install snapcraft --classic, which itself requires core22 and therefore fails.

Fix:

• Replaced sudo snap install snapcraft --classic + python snap_build.py --build with snapcore/action-build@v1 — the official GitHub Action that runs snapcraft inside an LXD container, bypassing the snapd restriction entirely
• Added a "Prepare snap staging directory" step that renders snapcraft.yaml from the template and copies source files into snap-build/ before the action runs

Snap cross-compilation failure on amd64 CI runners

Root cause: snapcraft.yaml.template declared architectures: [amd64, arm64], instructing snapcraft to cross-compile an arm64 snap on the amd64 CI runner. This fails because the LXD container does not have QEMU configured for arm64 emulation in the GitHub Actions environment.

Fix: Removed the architectures block from snapcraft.yaml.template. Snapcraft now builds for the native runner architecture (amd64). An arm64 snap can be added later using a separate arm64 runner job.

---

🔄 CI/CD Improvements

.github/workflows/build-packages.yml — complete rewrite:

Improvement	Detail
PyPI job	Clean python -m build — no workarounds required
Snap job	Uses snapcore/action-build@v1 with staged source directory
Resilience	continue-on-error: true on build-deb, build-rpm, build-snap, build-choco — platform package failures no longer block the core PyPI release
VS Code job	New vscode-extension.yml workflow added
Documentation	Inline comments explain every non-obvious step

---

📋 Full Changelog

Commit	Type	Summary
88ba487	fix	Rename build.py → kport_orchestrate.py; fix snap CI; rewrite workflow
7eabe76	feat	Add kport_orchestrate.py, snap_publish.py, vscode_build.py, BUILD_GUIDE.md; VS Code MCP first-run prompt
2f6468d	chore	Bump version to 3.2.3; initial release notes draft
93c7a7c	feat	Add VS Code extension (extension.ts, mcpConfig.ts, package.json); add snap_build.py, choco_build.py; update CI workflows
0d980d7	feat	Add permission-aware warning in CLI when processes are found but port bindings are inaccessible

---

🔄 Backward Compatibility

✅ Fully backward compatible with kport 3.2.2.

All existing commands, flags, and configurations continue to work without modification.

One developer-facing rename:

• build.py → kport_orchestrate.py — update any local scripts or CI references that called python build.py directly.

---

📦 Installation

Platform	Command
PyPI	pip install kport==3.2.3
Linux DEB	See Releases
Linux RPM	See Releases
Linux Snap	snap install kport
macOS	See Releases
Windows EXE	See Releases
Windows Chocolatey	choco install kport
VS Code	Extensions marketplace → search "KPort"

---

🛠️ For Developers & Maintainers

Building from Source

# Prerequisites check
python kport_orchestrate.py --check

# Build everything
python kport_orchestrate.py --build-all

# Build individual formats
python kport_orchestrate.py --build-pypi    # PyPI wheel + sdist
python kport_orchestrate.py --build-vscode  # VS Code .vsix
python kport_orchestrate.py --build-snap    # Snap package

Publishing

# Publish everything (requires credentials in env)
python kport_orchestrate.py --publish-all

# Publish individually
python publish.py                              # PyPI (TWINE_PASSWORD required)
python vscode_build.py --publish               # VS Code Marketplace (VSCE_PAT required)
python snap_publish.py --publish --channel stable  # Snap Store (snapcraft login required)

Running Tests

python run_tests.py
# or
pytest tests/ -v

See BUILD_GUIDE.md for full documentation.

---

📖 Resources

• GitHub Repository
• PyPI Package
• Snap Package
• VS Code Extension
• Issue Tracker
• Build Guide
• Model Context Protocol

v3.2.2

🚀 kport v3.2.2 — Release Notes

Release Date: June 2026
Branch: refactor
Previous Version: 3.2.1

---

Overview

kport 3.2.2 is a maintenance and refinement release focusing on CLI robustness, improved error handling, and streamlined release automation. This release enhances the user experience with better error messages and improved timeout handling while maintaining full backward compatibility with 3.2.1.

---

🆕 New Features

🔍 Enhanced CLI Error Handling

Improved command-line parser with better error messages and warnings for unused subcommands:

• Custom Error Parser: Provides more informative error messages when invalid arguments are passed
• Unused Subcommand Warnings: Alerts users when they attempt to use unrecognized subcommands
• Better guidance on correct command usage and available options

Example:

kport invalid-command  # Now shows helpful error message with suggestions

---

🔧 Improvements

⏱️ Graceful Timeout Handling

Enhanced graceful timeout handling in CLI commands for more reliable process termination:

• Improved timeout logic for kport kill operations
• More predictable behavior during graceful shutdown attempts
• Better handling of edge cases in timeout scenarios
• Enhanced code readability in timeout-related functions

📜 Streamlined Release Automation

Major refactoring of release.py for improved maintainability:

• Removed deprecated functions and redundant code
• Simplified version handling logic
• Cleaner build process integration
• Better separation of concerns in release workflows
• Reduced code complexity (454 lines → 190 lines of functional code)

---

🧪 Testing

The existing test suite in tests/test_cli.py continues to cover:

• CLI command parsing and execution
• Safety Shield functionality
• Port inspection and management
• Error handling scenarios

Run all tests:

python run_tests.py
# or
pytest tests/ -v

---

🐛 Bug Fixes & Quality Improvements

• Fixed CLI parser error handling to provide clearer feedback to users
• Improved graceful timeout reliability in port killing operations
• Removed deprecated code paths from release automation
• Enhanced code maintainability in core CLI module

---

⬆️ Upgrade Notes

• No breaking changes from v3.2.1
• All existing commands and configuration options remain unchanged
• No new dependencies added

---

📄 Full Changelog

• Enhanced CLI error handling with custom parser
• Added warning for unused subcommands
• Improved graceful timeout handling in kill operations
• Refactored release.py for better maintainability
• Simplified release script version handling
• Removed deprecated functions from build automation

---

🔗 Resources

• GitHub Repository: port-killer
• Installation: See INSTALL.md
• Quick Start: See QUICKSTART.md
• Contributing: See CONTRIBUTING.md

v3.2.0

🚀 kport v3.2.0 — Release Notes

Release Date: June 2026
Branch: refactor
Previous Version: 3.1.2

---

Overview

kport 3.2.0 is the Phase 2 Pro release, delivering a full suite of advanced port management features designed for professional developers, DevOps engineers, and AI agent workflows. This release brings real-time port monitoring, AI safety guardrails, comprehensive configuration support, and a standards-compliant MCP (Model Context Protocol) server.

---

🆕 New Features

👁️ Watch Mode — kport watch PORT

Continuously polls a port at a configurable interval and automatically kills any process that starts using it.

kport watch 8080              # monitor with 1s interval (default)
kport watch 8080 --interval 2 # poll every 2 seconds
kport watch 8080 --dry-run    # alert only, do not kill
kport watch 8080 --json       # JSON output for scripting
kport watch 8080 --yes        # skip kill confirmation

• Respects the Safety Shield — will not auto-kill protected ports/processes unless --bypass-safety is set.
• Supports graceful kill with configurable timeout before escalating to force kill.
• Handles KeyboardInterrupt (Ctrl+C) cleanly.

---

🛡️ Safety Shield — Protected Ports & Processes

A configurable safety layer that prevents accidental termination of critical system services. Active by default on all kill and watch operations.

Default protected ports:

Port	Service
22	SSH
53	DNS
80	HTTP
443	HTTPS
3306	MySQL
5432	PostgreSQL
6379	Redis
6443	Kubernetes API

Default protected processes: systemd, init, docker, dockerd, sshd, explorer.exe, lsass.exe, services.exe

To override the shield:

kport kill 22 --bypass-safety
kport watch 80 --bypass-safety --dry-run

To customize protected lists, set protected_ports and protected_processes in your .kport.json config — this replaces (not extends) the default lists.

---

⚙️ Enhanced Config File Support

The config file now supports protected_ports and protected_processes fields, making Safety Shield customizable per-project or globally.

Config lookup order:

1. .kport.json (current directory — project-level)
2. ~/.kport.json (user-level)
3. ~/.config/kport/config.json (XDG-compliant global)

Full config schema:

{
  "yes": false,
  "dry_run": false,
  "force": false,
  "debug": false,
  "graceful_timeout": 3.0,
  "docker_action": "stop",
  "protected_ports": [22, 53, 80, 443],
  "protected_processes": ["sshd", "systemd"]
}

---

🤖 MCP Server — AI Agent Integration

kport now ships a standards-compliant Model Context Protocol (MCP) server that AI assistants (Claude, Copilot, Cursor, etc.) can call to inspect and manage ports autonomously — with Safety Shield always active.

kport --mcp                  # start MCP server on stdio
python -m kport.mcp_server   # alternative invocation

MCP Tools:

Tool	Description
list_ports	Lists all local + Docker listening ports
inspect_port	Returns detailed info on a specific port
kill_port	Frees a port (safety-shielded, Docker-aware)

The MCP server dynamically loads .kport.json config on each kill_port call, so safety policies can be updated without restarting the server.

Claude Desktop / Cursor integration:

{
  "mcpServers": {
    "kport": {
      "command": "kport",
      "args": ["--mcp"]
    }
  }
}

---

📦 Cross-Platform Packaging

Native distribution packages are now automated via dedicated build scripts:

Platform	Script	Output
Windows	python win_build.py	.exe NSIS installer
macOS	python mac_build.py	.pkg installer
Debian/Ubuntu	python deb_publish.py	.deb package
RHEL/Fedora	python rpm_build.py	.rpm package
PyPI (any OS)	python -m build	.whl + .tar.gz

The Debian package correctly installs both the kport entry-point binary and the full src/kport/ library to Python's standard dist-packages path.

---

🔧 Improvements

• Cross-platform inspector: psutil-based PsutilInspector is now the default when psutil is installed; FallbackInspector (using native system commands) is used transparently when psutil is absent.
• JSON output: All subcommands now support --json for machine-readable output.
• Graceful kill strategy: SIGTERM → wait → SIGKILL → fuser (Linux fallback) chain is now consistent across CLI and MCP paths.
• Debug mode: --debug now prints full process resolution steps and kill attempt sequences.
• Version: Updated to 3.2.0 across pyproject.toml, setup.py, CLI parser, and MCP server info.

---

🧪 Test Suite

The test suite in tests/test_cli.py has been extended with:

• Safety Shield unit tests (default protection, bypass, custom config, process shield)
• watch command parser validation
• apply_config_defaults unit tests
• FallbackInspector initialization test
• Port range parsing edge-case coverage

Run all tests:

python run_tests.py
# or
pytest tests/ -v

---

🐛 Bug Fixes

• Fixed Debian rules file generator in deb_publish.py to correctly copy the full src/kport/ module tree during override_dh_auto_install.
• Fixed MCP server version string to 3.2.0 (was 3.1.2).
• Resolved setuptools deprecation warnings for project.license and keywords metadata.

---

⬆️ Upgrade Notes

• Minimum Python version is now 3.8 (was 3.6).
• The protected_ports and protected_processes config keys are new. If you had an existing .kport.json, no action is required — the Safety Shield defaults will apply automatically.
• The --bypass-safety flag is new. Old scripts that did not set it will now get Safety Shield protection by default.

---

📄 Full Changelog

• Added watch subcommand with auto-kill and polling loop
• Added bypass_safety flag to kill and watch subcommands
• Added check_safety_policy() function in cli.py
• Added load_mcp_config() in mcp_server.py with dynamic policy resolution
• Added win_build.py, mac_build.py, rpm_build.py, deb_publish.py build scripts
• Added packaging/windows/installer.nsi NSIS installer template
• Added PACKAGING.md guide
• Updated README.md and QUICKSTART.md for v3.2.0
• Bumped version to 3.2.0 across all package metadata files

kport 3.1.1

Release 3.1.1

Changes in this release:

• Bug fixes and improvements
• See commit history for details

Install:
pip install kport==3.1.1

kport v3.1.0

kport v3.1.0 Release Notes

Release Date: January 20, 2026

Cross-platform port inspector and killer with Docker support, safe termination features, and multiple output formats.

---

🎉 Highlights

• Docker-aware port detection - Automatically detects ports published by Docker containers
• Safe process termination - Interactive confirmations with graceful shutdown (SIGTERM) and force option
• Multiple interfaces - Both legacy flags (-k, -l, -i) and modern subcommands (kill, list, inspect)
• JSON output - Machine-readable output for automation and scripting
• Hidden PID handling - Correctly detects when system services hide PIDs (requires elevated privileges)
• Cross-platform - Works on Linux, macOS, and Windows with intelligent fallbacks

---

✨ Features

Port Management

• Inspect ports - kport inspect 8080 - Check what's using a specific port
• Explain ports - kport explain 8080 - Get detailed information about port usage
• Kill processes - kport kill 8080 - Safely terminate processes using a port
• List all ports - kport list - View all listening ports and their processes

Docker Integration

• Docker port mapping - kport docker - List all Docker container port mappings
• Container detection - Automatically identifies when a port is mapped to a Docker container
• Container actions - Stop or kill Docker containers directly from kport

Safety Features

• Confirmation prompts - Interactive confirmation before killing processes
• Dry-run mode - Preview actions without executing them (--dry-run)
• Force option - Send SIGKILL when graceful termination fails (--force)
• Permission detection - Clear messages when elevated privileges are required

Conflict Detection

• Port conflicts - kport conflicts - Find multiple processes trying to use the same port
• Range scanning - Check port ranges for conflicts

Configuration

• Config file support - Use .kport.json for default settings
• Config locations - Project-level, user home, or XDG config directory
• CLI override - --config flag to specify custom config file

---

🐧 Installation

PyPI (pip)

pip install kport==3.1.0
# or user install (recommended)
pip install --user kport==3.1.0

Debian/Ubuntu

wget https://github.com/farman20ali/port-killer/releases/download/v3.1.0/kport_3.1.0-1_all.deb
sudo dpkg -i kport_3.1.0-1_all.deb

From Source

pip install git+https://github.com/farman20ali/port-killer.git@v3.1.0

---

📋 Usage Examples

# List all listening ports
kport list

# Check what's using port 8080
kport inspect 8080

# Get detailed explanation for port 3000
kport explain 3000

# Kill process on port 5000 (with confirmation)
kport kill 5000

# Kill without confirmation
kport kill 8080 --yes

# List Docker port mappings
kport docker

# Find port conflicts
kport conflicts

# JSON output for scripting
kport inspect 8080 --json

---

🔧 Technical Details

Dependencies

• Python: 3.6 or higher
• Required: psutil >= 5.9.0 (for best cross-platform support)
• Optional: Docker CLI (for Docker features)

Platform Support

• Linux - Full support (uses psutil, falls back to lsof/ss/netstat)
• macOS - Full support (uses psutil, falls back to lsof)
• Windows - Full support (uses psutil, falls back to PowerShell/netstat)

Exit Codes

• 0 - Success
• 1 - General error
• 2 - Port not in use or not found
• 3 - Permission denied
• 4 - Port used by Docker container
• 5 - Port is free

---

📚 Documentation

• Installation Guide: INSTALL.md
• Quick Start: QUICKSTART.md
• Release Guide: RELEASE_GUIDE.md
• Contributing: CONTRIBUTING.md

---

🐛 Known Issues

• On some Linux systems, detecting PIDs for system services requires sudo or root privileges
• Docker detection requires Docker CLI to be installed and accessible in PATH
• Color output may not work on older Windows versions (< Windows 10)

---

🙏 Credits

Thanks to all contributors and users who provided feedback and bug reports.

---

📝 License

GNU Affero General Public License v3.0 (AGPL-3.0) - see LICENSE for details.

This license requires sharing source code modifications, even for network/SaaS use.

---

Full Changelog: https://github.com/farman20ali/port-killer/commits/v3.1.0