spark: add port availability checker utility

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)