fix: start scripts now validate prerequisites and stop on failure

- Check for Python and Node.js before starting
- Stop with clear error message if pip install fails
- Recommend Python 3.10-3.12 (3.13+ has compatibility issues)
- Show version info at startup for easier debugging
- Updated README with Python version guidance

README.md

@@ -208,8 +208,9 @@ If you want to modify the code or run from source:
 
 #### Prerequisites
 
-* **Node.js** 18+ and **npm**
-* **Python** 3.10+ with `pip`
+* **Node.js** 18+ and **npm** — [nodejs.org](https://nodejs.org/)
+* **Python** 3.10, 3.11, or 3.12 with `pip` — [python.org](https://www.python.org/downloads/) (**check "Add to PATH"** during install)
+  * ⚠️ Python 3.13+ may have compatibility issues with some dependencies. **3.11 or 3.12 is recommended.**
 * API keys for: `aisstream.io` (required), and optionally `opensky-network.org` (OAuth2), `lta.gov.sg`
 
 ### Installation

start.bat

@@ -5,28 +5,82 @@ echo ===================================================
 echo     S H A D O W B R O K E R   --   STARTUP
 echo ===================================================
 echo.
-echo Installing backend dependencies if needed...
+
+:: Check for Python
+where python >nul 2>&1
+if %errorlevel% neq 0 (
+    echo [!] ERROR: Python is not installed or not in PATH.
+    echo [!] Install Python 3.10-3.12 from https://python.org
+    echo [!] IMPORTANT: Check "Add to PATH" during install.
+    echo.
+    pause
+    exit /b 1
+)
+
+:: Check Python version
+for /f "tokens=2 delims= " %%v in ('python --version 2^>^&1') do set PYVER=%%v
+echo [*] Found Python %PYVER%
+
+:: Check for Node.js
+where npm >nul 2>&1
+if %errorlevel% neq 0 (
+    echo [!] ERROR: Node.js/npm is not installed or not in PATH.
+    echo [!] Install Node.js 18+ from https://nodejs.org
+    echo.
+    pause
+    exit /b 1
+)
+
+for /f "tokens=1 delims= " %%v in ('node --version 2^>^&1') do echo [*] Found Node.js %%v
+
+echo.
+echo [*] Setting up backend...
 cd backend
 if not exist "venv\" (
-    echo Creating Python virtual environment...
+    echo [*] Creating Python virtual environment...
     python -m venv venv
+    if %errorlevel% neq 0 (
+        echo [!] ERROR: Failed to create virtual environment.
+        pause
+        exit /b 1
+    )
 )
 call venv\Scripts\activate.bat
+echo [*] Installing Python dependencies (this may take a minute)...
 pip install -r requirements.txt
+if %errorlevel% neq 0 (
+    echo.
+    echo [!] ERROR: pip install failed. See errors above.
+    echo [!] If you see Rust/cargo errors, your Python version may be too new.
+    echo [!] Recommended: Python 3.10, 3.11, or 3.12.
+    echo.
+    pause
+    exit /b 1
+)
+echo [*] Backend dependencies OK.
 cd ..
 
 echo.
-echo Installing frontend dependencies if needed...
+echo [*] Setting up frontend...
 cd frontend
 if not exist "node_modules\" (
-    echo Running npm install...
+    echo [*] Installing frontend dependencies...
     call npm install
+    if %errorlevel% neq 0 (
+        echo [!] ERROR: npm install failed. See errors above.
+        pause
+        exit /b 1
+    )
 )
+echo [*] Frontend dependencies OK.
 
 echo.
-echo Starting both services...
-echo (Press Ctrl+C to stop the dashboard)
+echo ===================================================
+echo   Starting services...
+echo   Dashboard: http://localhost:3000
+echo   Keep this window open! Initial load takes ~10s.
+echo ===================================================
+echo   (Press Ctrl+C to stop)
 echo.
 
-:: Start the dev server which runs both NEXT and API via concurrently
 call npm run dev

start.sh

@@ -6,9 +6,10 @@ echo ""
 
 # Check for Node.js
 if ! command -v npm &> /dev/null; then
-    echo "[!] ERROR: npm is not installed. Please install Node.js (https://nodejs.org/)"
+    echo "[!] ERROR: npm is not installed. Please install Node.js 18+ (https://nodejs.org/)"
     exit 1
 fi
+echo "[*] Found Node.js $(node --version)"
 
 # Check for Python 3
 PYTHON_CMD=""
@@ -17,42 +18,63 @@ if command -v python3 &> /dev/null; then
 elif command -v python &> /dev/null; then
     PYTHON_CMD="python"
 else
-    echo "[!] ERROR: python3 is not installed. Please install Python 3.10+ (https://python.org/)"
+    echo "[!] ERROR: Python is not installed."
+    echo "[!] Install Python 3.10-3.12 from https://python.org"
     exit 1
 fi
 
-echo "[*] Using Python: $PYTHON_CMD ($($PYTHON_CMD --version 2>&1))"
+echo "[*] Found $($PYTHON_CMD --version 2>&1)"
 
-# Get the directory where this script lives (handles running from any location)
+# Get the directory where this script lives
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
-echo "[*] Setting up Backend Environment..."
+echo ""
+echo "[*] Setting up backend..."
 cd "$SCRIPT_DIR/backend"
 if [ ! -d "venv" ]; then
-    echo "[*] Creating Python Virtual Environment..."
+    echo "[*] Creating Python virtual environment..."
     $PYTHON_CMD -m venv venv
+    if [ $? -ne 0 ]; then
+        echo "[!] ERROR: Failed to create virtual environment."
+        exit 1
+    fi
 fi
 
-echo "[*] Installing Backend dependencies..."
 source venv/bin/activate
-pip install -q -r requirements.txt
+echo "[*] Installing Python dependencies (this may take a minute)..."
+pip install -r requirements.txt
+if [ $? -ne 0 ]; then
+    echo ""
+    echo "[!] ERROR: pip install failed. See errors above."
+    echo "[!] If you see Rust/cargo errors, your Python version may be too new."
+    echo "[!] Recommended: Python 3.10, 3.11, or 3.12."
+    exit 1
+fi
+echo "[*] Backend dependencies OK."
 deactivate
 
 cd "$SCRIPT_DIR"
 
-echo "[*] Setting up Frontend Environment..."
+echo ""
+echo "[*] Setting up frontend..."
 cd "$SCRIPT_DIR/frontend"
 if [ ! -d "node_modules" ]; then
-    echo "[*] Installing Frontend dependencies..."
+    echo "[*] Installing frontend dependencies..."
     npm install
+    if [ $? -ne 0 ]; then
+        echo "[!] ERROR: npm install failed. See errors above."
+        exit 1
+    fi
 fi
+echo "[*] Frontend dependencies OK."
 
 echo ""
 echo "======================================================="
-echo "  Starting Services...                                 "
-echo "  Dashboard will be available at: http://localhost:3000 "
-echo "  Keep this window open! Initial load takes ~10s       "
+echo "  Starting services...                                 "
+echo "  Dashboard: http://localhost:3000                     "
+echo "  Keep this window open! Initial load takes ~10s.      "
 echo "======================================================="
+echo "  (Press Ctrl+C to stop)"
 echo ""
 
 npm run dev