feat(dev): refactor service startup to use dedicated start script (#1042)

scripts/wait-for-port.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+#
+# wait-for-port.sh - Wait for a TCP port to become available
+#
+# Usage: ./scripts/wait-for-port.sh <port> [timeout_seconds] [service_name]
+#
+# Arguments:
+#   port             - TCP port to wait for (required)
+#   timeout_seconds  - Max seconds to wait (default: 60)
+#   service_name     - Display name for messages (default: "Service")
+#
+# Exit codes:
+#   0 - Port is listening
+#   1 - Timed out waiting
+
+PORT="${1:?Usage: wait-for-port.sh <port> [timeout] [service_name]}"
+TIMEOUT="${2:-60}"
+SERVICE="${3:-Service}"
+
+elapsed=0
+interval=1
+
+while ! lsof -i :"$PORT" -sTCP:LISTEN -t >/dev/null 2>&1; do
+    if [ "$elapsed" -ge "$TIMEOUT" ]; then
+        echo ""
+        echo "✗ $SERVICE failed to start on port $PORT after ${TIMEOUT}s"
+        exit 1
+    fi
+    printf "\r  Waiting for %s on port %s... %ds" "$SERVICE" "$PORT" "$elapsed"
+    sleep "$interval"
+    elapsed=$((elapsed + interval))
+done
+
+printf "\r  %-60s\r" ""   # clear the waiting line