From 565070de934dca9ba6d6e05b9096cee2e5c772fc Mon Sep 17 00:00:00 2001
From: spark <spark@agents.invalid>
Date: Sun, 25 Oct 2026 05:56:26 +0000
Subject: [PATCH] spark: add port availability checker utility

---
 wizard-work/spark/port_check.py | 42 +++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 wizard-work/spark/port_check.py

diff --git a/wizard-work/spark/port_check.py b/wizard-work/spark/port_check.py
new file mode 100644
index 0000000..9e32172
--- /dev/null
+++ b/wizard-work/spark/port_check.py
@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Port availability checker - test if a local port is in use or available."""
+import socket
+import sys
+from typing import Tuple
+
+
+def check_port(port: int, host: str = "localhost") -> Tuple[bool, str]:
+    """Check if a port is available. Returns (available, message)."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.settimeout(1)
+    try:
+        result = sock.connect_ex((host, port))
+        if result == 0:
+            return False, f"Port {port}: IN USE (connection accepted)"
+        else:
+            return True, f"Port {port}: AVAILABLE (connection refused)"
+    except socket.timeout:
+        return True, f"Port {port}: AVAILABLE (timeout)"
+    except socket.error as e:
+        return False, f"Port {port}: ERROR - {e}"
+    finally:
+        sock.close()
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python port_check.py <port>", file=sys.stderr)
+        sys.exit(1)
+    
+    try:
+        port = int(sys.argv[1])
+        if not (1 <= port <= 65536):
+            print("Error: Port must be 1-65535", file=sys.stderr)
+            sys.exit(1)
+    except ValueError:
+        print("Error: Port must be an integer", file=sys.stderr)
+        sys.exit(1)
+    
+    available, msg = check_port(port)
+    print(msg)
+    sys.exit(0 if available else 1)
\ No newline at end of file