fix: CODEQL_PATH tests and startup validation

- Fix codeql-path-tests CI job that timed out (~17min) on all three OSes
  due to bash pipe PID tracking bug (`$!` captured subshell PID, not
  server PID). Replace inline workflow steps with portable bash scripts
  using background watchdog + `wait` pattern (no GNU `timeout`).

- Add startup-time validation (`validateCodeQLBinaryReachable`) that runs
  `codeql version --format=terse` before tool registration. Server now
  fails fast with actionable error when codeql is not on PATH and
  CODEQL_PATH is not set.

- Add Test 3: verify server fails at startup when codeql is missing from
  both PATH and CODEQL_PATH.

- Address 5 Copilot PR review comments:
  - Implement caching in `resolveCodeQLBinary()` (short-circuit on repeat calls)
  - Fix JSDoc in temp-dir.ts (`<repoRoot>` -> `<packageRoot>`)
  - Gate Windows backslash test to `process.platform === 'win32'`
  - Use `path.isAbsolute()` for cross-platform database path check
  - Guard `additionalPacksPath` with `existsSync()` for npm-installed layouts

Scripts: server/scripts/test-codeql-path-{invalid,missing,valid}.sh
Tests: 375 passed (4 new)

Author: data-douser

.github/workflows/client-integration-tests.yml

@@ -276,87 +276,19 @@ jobs:
       ## to a non-existent file and codeql is not on PATH.
       - name: CODEQL_PATH Tests - Test 1 - Fail with invalid CODEQL_PATH
         shell: bash
-        run: |
-          echo "=== Test 1: Server must fail when CODEQL_PATH is invalid ==="
-          export PATH="$CLEAN_PATH"
-          export CODEQL_PATH="/nonexistent/path/to/codeql"
-
-          # Use a long-running Node process as a stdin source to prevent
-          # immediate EOF (which causes a clean exit instead of a crash).
-          # Cross-platform: works on Linux, macOS, and Windows (no mkfifo).
-          node -e "setTimeout(()=>{},999999)" | \
-            node server/dist/codeql-development-mcp-server.js >stdout.txt 2>stderr.txt &
-          SERVER_PID=$!
-
-          # Wait for the process to exit (it should fail within seconds)
-          sleep 5
-
-          if kill -0 "$SERVER_PID" 2>/dev/null; then
-            echo "::error::Server should have exited but is still running"
-            kill "$SERVER_PID" 2>/dev/null || true
-            wait "$SERVER_PID" 2>/dev/null || true
-            cat stderr.txt
-            exit 1
-          fi
-
-          wait "$SERVER_PID" 2>/dev/null
-          EXIT_CODE=$?
+        run: ./server/scripts/test-codeql-path-invalid.sh
 
-          echo "Exit code: $EXIT_CODE"
-          cat stderr.txt
-
-          if [[ "$EXIT_CODE" -ne 0 ]] && grep -qi "does not exist" stderr.txt; then
-            echo ""
-            echo "✅ PASS: Server failed at startup with expected CODEQL_PATH error"
-          else
-            echo ""
-            echo "::error::Unexpected behavior (exit=$EXIT_CODE)"
-            exit 1
-          fi
+      ## Test 2: The server must fail at startup when codeql is not on PATH
+      ## and CODEQL_PATH is not set.
+      - name: CODEQL_PATH Tests - Test 2 - Fail when codeql not on PATH and CODEQL_PATH not set
+        shell: bash
+        run: ./server/scripts/test-codeql-path-missing.sh
 
-      ## Test 2: The server must start without error when CODEQL_PATH points
+      ## Test 3: The server must start without error when CODEQL_PATH points
       ## to a valid CodeQL binary, even though codeql is not on PATH.
-      - name: CODEQL_PATH Tests - Test 2 - Start with valid CODEQL_PATH
+      - name: CODEQL_PATH Tests - Test 3 - Start with valid CODEQL_PATH
         shell: bash
-        run: |
-          echo "=== Test 2: Server must start when CODEQL_PATH is valid ==="
-          export PATH="$CLEAN_PATH"
-          export CODEQL_PATH="${{ steps.locate-codeql.outputs.codeql-binary }}"
-
-          echo "CODEQL_PATH=$CODEQL_PATH"
-          echo "codeql in PATH: $(command -v codeql 2>/dev/null || echo 'not found')"
-
-          # Use a long-running Node process as a stdin source to keep the
-          # STDIO transport alive. Cross-platform (no mkfifo needed).
-          node -e "setTimeout(()=>{},999999)" | \
-            node server/dist/codeql-development-mcp-server.js >stdout.txt 2>stderr.txt &
-          SERVER_PID=$!
-
-          # Give the server time to either start successfully or crash
-          sleep 5
-
-          if kill -0 "$SERVER_PID" 2>/dev/null; then
-            echo "✅ PASS: Server is running after 5 seconds (PID $SERVER_PID)"
-            echo "--- startup logs ---"
-            cat stderr.txt
-
-            # Verify stderr confirms CODEQL_PATH was used
-            if grep -q "CODEQL_PATH" stderr.txt; then
-              echo "✅ Server logged CODEQL_PATH resolution"
-            else
-              echo "⚠️ CODEQL_PATH not found in stderr (non-fatal)"
-            fi
-
-            # Clean up
-            kill "$SERVER_PID" 2>/dev/null || true
-            wait "$SERVER_PID" 2>/dev/null || true
-          else
-            wait "$SERVER_PID" 2>/dev/null
-            EXIT_CODE=$?
-            echo "::error::Server exited prematurely with code $EXIT_CODE"
-            cat stderr.txt
-            exit 1
-          fi
+        run: ./server/scripts/test-codeql-path-valid.sh "${{ steps.locate-codeql.outputs.codeql-binary }}"
 
       - name: CODEQL_PATH Tests - Summary
         shell: bash
@@ -366,6 +298,7 @@ jobs:
           echo "| Test | Result |" >> $GITHUB_STEP_SUMMARY
           echo "| ---- | ------ |" >> $GITHUB_STEP_SUMMARY
           echo "| Invalid CODEQL_PATH causes startup failure | ✅ Pass |" >> $GITHUB_STEP_SUMMARY
+          echo "| Missing codeql (no PATH, no CODEQL_PATH) causes startup failure | ✅ Pass |" >> $GITHUB_STEP_SUMMARY
           echo "| Valid CODEQL_PATH (no PATH) starts server | ✅ Pass |" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "| Detail | Value |" >> $GITHUB_STEP_SUMMARY

server/dist/codeql-development-mcp-server.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+##
+## Test: Server must fail at startup when CODEQL_PATH points to a non-existent file.
+##
+## Usage:
+##   ./server/scripts/test-codeql-path-invalid.sh [<server-bundle>]
+##
+## Arguments:
+##   <server-bundle>  Path to the server JS bundle (default: server/dist/codeql-development-mcp-server.js)
+##
+## Environment:
+##   CLEAN_PATH  Optional. When set, PATH is replaced with this value so that
+##               codeql is not discoverable via PATH. When unset, the current
+##               PATH is used as-is (useful for local testing).
+##
+## Exit codes:
+##   0  Server failed at startup with the expected CODEQL_PATH error
+##   1  Unexpected behavior (server did not fail, wrong error, etc.)
+##
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+SERVER_BUNDLE="${1:-server/dist/codeql-development-mcp-server.js}"
+
+# Resolve relative paths against the repo root
+if [[ ! "${SERVER_BUNDLE}" = /* ]]; then
+  SERVER_BUNDLE="${REPO_ROOT}/${SERVER_BUNDLE}"
+fi
+
+if [[ ! -f "${SERVER_BUNDLE}" ]]; then
+  echo "::error::Server bundle not found: ${SERVER_BUNDLE}"
+  exit 1
+fi
+
+# Replace PATH with CLEAN_PATH when provided
+if [[ -n "${CLEAN_PATH:-}" ]]; then
+  export PATH="${CLEAN_PATH}"
+fi
+
+# Point CODEQL_PATH at a non-existent file
+export CODEQL_PATH="/nonexistent/path/to/codeql"
+
+echo "=== Test: Server must fail when CODEQL_PATH is invalid ==="
+echo "  SERVER_BUNDLE=${SERVER_BUNDLE}"
+echo "  CODEQL_PATH=${CODEQL_PATH}"
+
+# Run the server directly (no pipe) with a watchdog timeout.
+# Feed /dev/null to stdin so the STDIO transport gets immediate EOF and the
+# process can exit cleanly after the startup error.
+# NOTE: We avoid GNU `timeout` because it may not be available on macOS CI runners.
+STDOUT_FILE="$(mktemp)"
+STDERR_FILE="$(mktemp)"
+cleanup() { rm -f "${STDOUT_FILE}" "${STDERR_FILE}"; }
+trap cleanup EXIT
+
+node "${SERVER_BUNDLE}" \
+  < /dev/null \
+  > "${STDOUT_FILE}" \
+  2> "${STDERR_FILE}" &
+SERVER_PID=$!
+
+# Watchdog: kill the server if it hasn't exited within 15 seconds
+( sleep 15; kill "${SERVER_PID}" 2>/dev/null ) &
+WATCHDOG_PID=$!
+
+wait "${SERVER_PID}" 2>/dev/null && EXIT_CODE=0 || EXIT_CODE=$?
+
+# Cancel the watchdog if the server exited on its own
+kill "${WATCHDOG_PID}" 2>/dev/null || true
+wait "${WATCHDOG_PID}" 2>/dev/null || true
+
+echo "  Exit code: ${EXIT_CODE}"
+
+if [[ "${EXIT_CODE}" -ne 0 ]] && grep -qi "does not exist" "${STDERR_FILE}"; then
+  echo ""
+  echo "--- stderr (first 20 lines) ---"
+  head -20 "${STDERR_FILE}"
+  echo ""
+  echo "✅ PASS: Server failed at startup with expected CODEQL_PATH error"
+  exit 0
+else
+  echo ""
+  echo "::error::Unexpected behavior (exit=${EXIT_CODE})"
+  echo "--- stderr ---"
+  cat "${STDERR_FILE}"
+  echo "--- stdout ---"
+  cat "${STDOUT_FILE}"
+  exit 1
+fi