Add port killer utility for troubleshooting port conflicts

[sebastiensimon1]

Pull Request Title

Add port killer utility for troubleshooting port conflicts

Related Issue

N/A - This is a proactive enhancement to help users troubleshoot common port conflict issues

Description

This PR adds a diagnostic utility script that helps users identify and terminate processes occupying ports, particularly useful when Streamlit fails to start due to "Address already in use" errors.

The script uses multiple detection methods (lsof, fuser, netstat, ss, and /proc filesystem) to ensure reliable process identification across different Linux/WSL environments.

Type

• Bug Fix
• Feature Enhancement
• Documentation Update
• Code Refactoring
• Other (please specify):

Proposed Changes

• Added port_killer.py - comprehensive port diagnostic and process termination utility
• Script supports command-line arguments for flexible port targeting
• Provides detailed process information before termination
• Uses multiple detection methods for reliability across different environments

Screenshots / Code Snippets (if applicable)

Example usage:

# Kill default ports
python port_killer.py

# Kill specific port(s)

python port_killer.py 8000 3000

Example output:

TARGET PORTS: [8000]

======================================================================
DEEP SCAN: PORT 8000
======================================================================

[1] Checking with lsof...
    Found: [12345]
...
EXECUTING KILL SEQUENCE FOR PORT 8501
...
Port 8000: CLEAR

How to Test

1. Start the backend and frontend on port 8000 and 3000
2. Without stopping it, try to start another instance (should fail with "Address already in use")
3. Run the port killer script: `python port_killer.py
4. Verify the port is now free and you can start it successfully
5. Test with multiple ports: `python port_killer.py

Checklist

• The code compiles successfully without any errors or warnings
• The changes have been tested and verified
• The documentation has been updated (if applicable)
• The changes follow the project's coding guidelines and best practices
• The commit messages are descriptive and follow the project's guidelines
• All tests (if applicable) pass successfully
• This pull request has been linked to the related issue (if applicable)

Additional Information

This utility is particularly helpful for:

• Quick troubleshooting without manually finding and killing processes

The script requires no additional dependencies beyond Python standard library and works on Linux/WSL environments. It gracefully handles missing system utilities and provides clear feedback about what was found and terminated.

---

Summary by cubic

Adds a Linux/WSL port killer utility to quickly diagnose and free busy ports. Helps resolve “Address already in use” errors by finding and terminating offending processes with clear output.

• New Features
  • Adds port_killer.py to scan and kill processes on specified ports (defaults: 3000, 3001, 3002, 8000).
  • Uses lsof, fuser, netstat, ss, and /proc for reliable detection across environments.
  • Shows process details (name, status, parent, command) before kill and verifies clearance.
  • No external deps; includes a brief troubleshooting note in the README.

^{Written for commit c8fd455. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 2 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="port_killer.py">

<violation number="1" location="port_killer.py:98">
P1: Naive /proc fd substring match can misidentify PIDs and kill unrelated processes; socket fd links don’t contain ports or “TCP”, so this detection is unreliable and can flag non-port users.</violation>

<violation number="2" location="port_killer.py:245">
P1: PermissionError from os.kill(pid, 0) is unhandled, so checking a process owned by another user will crash the script and stop processing remaining ports.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: PermissionError from os.kill(pid, 0) is unhandled, so checking a process owned by another user will crash the script and stop processing remaining ports.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At port_killer.py, line 245:

<comment>PermissionError from os.kill(pid, 0) is unhandled, so checking a process owned by another user will crash the script and stop processing remaining ports.</comment>

<file context>
@@ -0,0 +1,305 @@
+            
+            # Check if dead
+            try:
+                os.kill(pid, 0)  # Signal 0 = check if alive
+                print(f"   Still alive after kill attempt!")
+                
</file context>

[cubic-dev-ai]

P1: Naive /proc fd substring match can misidentify PIDs and kill unrelated processes; socket fd links don’t contain ports or “TCP”, so this detection is unreliable and can flag non-port users.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At port_killer.py, line 98:

<comment>Naive /proc fd substring match can misidentify PIDs and kill unrelated processes; socket fd links don’t contain ports or “TCP”, so this detection is unreliable and can flag non-port users.</comment>

<file context>
@@ -0,0 +1,305 @@
+                    for fd in os.listdir(fd_path):
+                        try:
+                            link = os.readlink(f'{fd_path}/{fd}')
+                            if f':{port}' in link or f'TCP' in link:
+                                all_pids.add(pid)
+                                print(f"    Found: {pid} (via /proc)")
</file context>