feat: better testing server setup for init.sh

matejvasek · claude · matejvasek · commit e5757493428b · 2026-05-15T17:51:39.000+02:00
- Stop operations use PID files (.dev-pids/) instead of pgrep/pkill,
  with recursive kill_tree to handle process trees (e.g. yarn-&gt;webpack)
- Ports randomized via --randomize-ports flag (default ports unchanged)
- Active ports written to .dev-env.json for agent and tooling discovery
- Go backend auto-recompiles on .go/.mod/.sum changes via inotifywait
  with build-then-swap strategy (build to tmp, swap only on success)
- start-console.sh accepts --backend-port, --plugin-port, --console-port,
  --cidfile CLI args; uses -p port mapping on all platforms
- webpack.config.ts reads PLUGIN_PORT env var with fallback to 9001
- Agent docs (AGENTS.md, WORKFLOW.md, init-session) reference
  .dev-env.json and .dev-logs/

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.claude/commands/init-session.md b/.claude/commands/init-session.md
@@ -1,5 +1,5 @@
 ---
-allowed-tools: Bash(git log:*), Bash(pwd), Bash(./init.sh), Bash(yarn test*), Read
+allowed-tools: Bash(git log:*), Bash(pwd), Bash(./init.sh), Bash(yarn test*), Bash(cat .dev-env.json), Read
 description: Run startup sequence (steps 1-6 from docs/WORKFLOW.md)
 ---
 
@@ -19,5 +19,6 @@ Execute the startup sequence from `docs/WORKFLOW.md`. AGENTS.md is always in con
 3. **Check struggles** — read `docs/agent-struggles.json`. If unresolved entries exist, present to user.
 4. **Pick feature** — read `docs/features.json`, find first `"passes": false` entry.
 5. **Start dev env** — run `./init.sh`.
-6. **Run tests** — run `yarn test` and verify app is healthy.
-7. **Wait** — tell the user you're oriented, report the picked feature and which step of the Feature Development Sequence you'd start at. When the user says to proceed, follow the Feature Development Sequence in `docs/WORKFLOW.md` step by step. Do NOT start any work autonomously.
+6. **Read ports** — read `.dev-env.json` and note the backend, plugin, and console ports.
+7. **Run tests** — run `yarn test` and verify app is healthy.
+8. **Wait** — tell the user you're oriented, report the picked feature and which step of the Feature Development Sequence you'd start at. When the user says to proceed, follow the Feature Development Sequence in `docs/WORKFLOW.md` step by step. Do NOT start any work autonomously.
diff --git a/.dockerignore b/.dockerignore
@@ -1 +1,4 @@
 /bin
+.dev-logs
+.dev-pids
+.dev-env.json
diff --git a/.gitignore b/.gitignore
@@ -35,6 +35,8 @@ AGENTS.override.md
 # Local development configuration
 .dev
 .dev-logs
+.dev-pids
+.dev-env.json
 
 # Yarn v4 (Berry)
 .yarn/*
diff --git a/AGENTS.md b/AGENTS.md
@@ -32,5 +32,7 @@ No em dashes (`—`). Use commas, periods, or parentheses instead.
 | `docs/potential-features.json` | Candidate features for future implementation |
 | `docs/claude-progress.txt` | Session handoff log — see [`references/claude-progress-readme.md`](docs/references/claude-progress-readme.md) |
 | `docs/agent-struggles.json` | Struggle log — see [`references/agent-struggles-readme.md`](docs/references/agent-struggles-readme.md) |
+| `.dev-env.json` | Dev server ports (backendPort, pluginPort, consolePort), written by init.sh |
+| `.dev-logs/` | Dev server log files (backend.log, webpack.log, console.log) |
 | `docs/references/ocp-plugin-guide.md` | OCP dynamic plugin mechanics, i18n, extension points |
 | `docs/references/commit-message-guide.md` | Git commit conventions and authorship rules |
diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md
@@ -9,8 +9,9 @@ Every session, before doing any work:
 3. Read `docs/agent-struggles.json` — if unresolved entries exist, present to user
 4. Read `docs/features.json` — pick first `"passes": false` entry
 5. Run `./init.sh` — start dev env
-6. Run tests — verify app is healthy
-7. If broken → fix first. If clean → start [Feature Development Sequence](#feature-development-sequence).
+6. Read `.dev-env.json` — note the dev server ports (backend, plugin, console)
+7. Run tests — verify app is healthy
+8. If broken → fix first. If clean → start [Feature Development Sequence](#feature-development-sequence).
 
 ## Feature Development Sequence
 
diff --git a/docs/claude-progress.txt b/docs/claude-progress.txt
@@ -1,6 +1,23 @@
 # Claude Progress Log
 # Newest entries first. Agents: append your entry at the top after the header.
 
+---
+## 2026-05-15 | Session: Better testing server setup (init.sh)
+Worked on: Improve init.sh with PID files, port randomization, Go auto-recompile, agent docs
+Completed:
+- Stop operations use PID files (.dev-pids/) with recursive kill_tree instead of pgrep/pkill
+- Ports randomized via --randomize-ports flag (default ports unchanged for human testers)
+- Active ports written to .dev-env.json for agent and tooling discovery
+- Go backend auto-recompiles on .go/.mod/.sum changes via inotifywait (build-then-swap strategy)
+- start-console.sh accepts --backend-port, --plugin-port, --console-port, --cidfile CLI args
+- Dropped --network=host on Linux in favor of -p port mapping (enables console port randomization)
+- webpack.config.ts reads PLUGIN_PORT env var with fallback to 9001
+- Agent docs (AGENTS.md, WORKFLOW.md, init-session) reference .dev-env.json and .dev-logs/
+- Design spec and implementation plan written
+- 13 suites, 112 tests, all passing
+Left off: Branch improve-test-cluster, ready to push. Feature not yet marked as passes:true (needs manual testing confirmation).
+Blockers: None
+
 ---
 ## 2026-05-13 | Session: Fix function list not updating on GitHub user switch
 Worked on: Bug fix for PAT switching via Avatar button not refreshing the function list
diff --git a/init.sh b/init.sh
@@ -8,6 +8,7 @@ BACKEND_PORT=8080
 PLUGIN_PORT=9001
 CONSOLE_PORT=9000
 TIMEOUT=60
+PID_DIR=".dev-pids"
 
 wait_for_port() {
   local port=$1
@@ -25,37 +26,124 @@ wait_for_port() {
   done
 }
 
+kill_tree() {
+  local pid=$1
+  local children
+  children=$(pgrep -P "$pid" 2>/dev/null || true)
+  for child in $children; do
+    kill_tree "$child"
+  done
+  kill "$pid" 2>/dev/null || true
+}
+
+stop_pid() {
+  local pidfile="$PID_DIR/$1"
+  local label=$2
+
+  if [ ! -f "$pidfile" ]; then
+    return
+  fi
+
+  local pid
+  pid=$(cat "$pidfile")
+  if kill -0 "$pid" 2>/dev/null; then
+    kill_tree "$pid"
+    while kill -0 "$pid" 2>/dev/null; do sleep 0.1; done
+    echo "Stopped $label (PID $pid)."
+  fi
+  rm -f "$pidfile"
+}
+
+random_free_port() {
+  local port
+  while true; do
+    port=$((RANDOM % 50001 + 10000))
+    if ! bash -c "echo >/dev/tcp/localhost/$port" 2>/dev/null; then
+      echo "$port"
+      return
+    fi
+  done
+}
+
+write_dev_env() {
+  cat > .dev-env.json <<EOF
+{
+  "backendPort": $BACKEND_PORT,
+  "pluginPort": $PLUGIN_PORT,
+  "consolePort": $CONSOLE_PORT
+}
+EOF
+}
+
 start_backend() {
   echo "Building Go backend..."
   (cd backend && go build -buildvcs=false -o ../bin/backend .)
   echo "Starting Go backend..."
-  ./bin/backend --http-port "$BACKEND_PORT" >"$LOG_DIR/backend.log" 2>&1 &
+  ./bin/backend --http-port "$BACKEND_PORT" >>"$LOG_DIR/backend.log" 2>&1 &
+  echo $! > "$PID_DIR/backend.pid"
 }
 
-stop_backend() {
-  if pgrep -f "bin/backend" >/dev/null 2>&1; then
-    pkill -f "bin/backend" && echo "Stopped Go backend."
+start_backend_watcher() {
+  if ! command -v inotifywait &>/dev/null; then
+    echo "Warning: inotifywait not found. Install inotify-tools for auto-recompile."
+    return
   fi
+
+  echo "Starting backend file watcher..."
+  (
+    while true; do
+      inotifywait -r -e modify,create,delete,move --include '\.(go|mod|sum)$' backend/ >/dev/null 2>&1
+      sleep 1  # debounce
+
+      echo "[watcher] Detected change, rebuilding backend..."
+      if (cd backend && go build -buildvcs=false -o ../bin/backend-tmp .); then
+        old_pid=$(cat "$PID_DIR/backend.pid" 2>/dev/null || true)
+        if [ -n "$old_pid" ]; then
+          kill "$old_pid" 2>/dev/null || true
+          while kill -0 "$old_pid" 2>/dev/null; do sleep 0.1; done
+        fi
+        mv bin/backend-tmp bin/backend
+        ./bin/backend --http-port "$BACKEND_PORT" >>"$LOG_DIR/backend.log" 2>&1 &
+        echo $! > "$PID_DIR/backend.pid"
+        echo "[watcher] Backend restarted (PID $!)."
+      else
+        echo "[watcher] Build failed. Keeping current backend running."
+        rm -f bin/backend-tmp
+      fi
+    done
+  ) >>"$LOG_DIR/backend.log" 2>&1 &
+  echo $! > "$PID_DIR/backend-watcher.pid"
+}
+
+stop_backend() {
+  stop_pid "backend-watcher.pid" "backend watcher"
+  stop_pid "backend.pid" "Go backend"
 }
 
 stop_plugin() {
-  if pgrep -f "webpack serve" >/dev/null 2>&1; then
-    pkill -f "webpack serve" && echo "Stopped plugin dev server."
-  fi
+  stop_pid "webpack.pid" "plugin dev server"
 }
 
 stop_console() {
-  local container
-  container=$(podman ps -q --filter ancestor="$CONSOLE_IMAGE" 2>/dev/null || true)
-  if [ -n "$container" ]; then
-    podman stop "$container" >/dev/null && echo "Stopped OpenShift console."
+  local cidfile="$PID_DIR/console.cid"
+
+  if [ ! -f "$cidfile" ]; then
+    return
   fi
+
+  local cid
+  cid=$(cat "$cidfile")
+  if podman stop "$cid" >/dev/null 2>&1; then
+    echo "Stopped OpenShift console (container $cid)."
+  fi
+  rm -f "$cidfile"
 }
 
 stop_dev() {
   stop_backend
   stop_plugin
   stop_console
+  rm -f .dev-env.json
 }
 
 check_prerequisites() {
@@ -79,12 +167,18 @@ install_dependencies() {
 
 start_plugin() {
   echo "Starting plugin dev server..."
-  yarn start >"$LOG_DIR/webpack.log" 2>&1 &
+  PLUGIN_PORT="$PLUGIN_PORT" yarn start >"$LOG_DIR/webpack.log" 2>&1 &
+  echo $! > "$PID_DIR/webpack.pid"
 }
 
 start_console() {
   echo "Starting OpenShift console..."
-  yarn start-console >"$LOG_DIR/console.log" 2>&1 &
+  ./start-console.sh \
+    --backend-port "$BACKEND_PORT" \
+    --plugin-port "$PLUGIN_PORT" \
+    --console-port "$CONSOLE_PORT" \
+    --cidfile "$PID_DIR/console.cid" \
+    >"$LOG_DIR/console.log" 2>&1 &
 }
 
 print_status() {
@@ -98,21 +192,42 @@ print_status() {
 }
 
 main() {
-  mkdir -p "$LOG_DIR" bin
+  mkdir -p "$LOG_DIR" "$PID_DIR" bin
   check_prerequisites
   install_dependencies
   stop_dev
+  write_dev_env
   start_backend
   wait_for_port "$BACKEND_PORT" "Go backend"
+  start_backend_watcher
   start_plugin
   wait_for_port "$PLUGIN_PORT" "Plugin dev server"
   start_console
   wait_for_port "$CONSOLE_PORT" "OpenShift console"
   print_status
 }
 
-if [ "${1:-}" = "--stop" ]; then
-  stop_dev
-else
-  main
-fi
+case "${1:-}" in
+  --stop)
+    stop_dev
+    ;;
+  --randomize-ports)
+    BACKEND_PORT=$(random_free_port)
+    PLUGIN_PORT=$(random_free_port)
+    while [ "$PLUGIN_PORT" -eq "$BACKEND_PORT" ]; do
+      PLUGIN_PORT=$(random_free_port)
+    done
+    CONSOLE_PORT=$(random_free_port)
+    while [ "$CONSOLE_PORT" -eq "$BACKEND_PORT" ] || [ "$CONSOLE_PORT" -eq "$PLUGIN_PORT" ]; do
+      CONSOLE_PORT=$(random_free_port)
+    done
+    main
+    ;;
+  "")
+    main
+    ;;
+  *)
+    echo "Usage: $0 [--stop | --randomize-ports]"
+    exit 1
+    ;;
+esac
diff --git a/start-console.sh b/start-console.sh
@@ -2,8 +2,23 @@
 
 set -euo pipefail
 
+# Parse CLI arguments (all optional, with defaults)
+BACKEND_PORT=8080
+PLUGIN_PORT=9001
+CIDFILE=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --backend-port) BACKEND_PORT="$2"; shift 2 ;;
+    --plugin-port) PLUGIN_PORT="$2"; shift 2 ;;
+    --console-port) CONSOLE_PORT="$2"; shift 2 ;;
+    --cidfile) CIDFILE="$2"; shift 2 ;;
+    *) echo "Unknown argument: $1"; exit 1 ;;
+  esac
+done
+
 CONSOLE_IMAGE=${CONSOLE_IMAGE:="quay.io/openshift/origin-console:latest"}
-CONSOLE_PORT=${CONSOLE_PORT:=9000}
+CONSOLE_PORT=${CONSOLE_PORT:-9000}
 CONSOLE_IMAGE_PLATFORM=${CONSOLE_IMAGE_PLATFORM:="linux/amd64"}
 
 # Plugin metadata is declared in package.json
@@ -42,22 +57,15 @@ echo "Console Platform: $CONSOLE_IMAGE_PLATFORM"
 # Prefer podman if installed. Otherwise, fall back to docker.
 if [ -x "$(command -v podman)" ]; then
     CONTAINER_CMD="podman"
-    if [ "$(uname -s)" = "Linux" ]; then
-        # Use host networking on Linux since host.containers.internal is unreachable in some environments.
-        PLUGIN_HOST="localhost"
-        CONTAINER_NETWORK_OPTS="--network=host"
-    else
-        PLUGIN_HOST="host.containers.internal"
-        CONTAINER_NETWORK_OPTS="-p ${CONSOLE_PORT}:9000"
-    fi
+    PLUGIN_HOST="host.containers.internal"
 else
     CONTAINER_CMD="docker"
     PLUGIN_HOST="host.docker.internal"
-    CONTAINER_NETWORK_OPTS="-p ${CONSOLE_PORT}:9000"
 fi
+CONTAINER_NETWORK_OPTS="-p ${CONSOLE_PORT}:9000"
 
-BRIDGE_PLUGINS="${PLUGIN_NAME}=http://${PLUGIN_HOST}:9001"
-BRIDGE_PLUGIN_PROXY='{"services":[{"consoleAPIPath":"/api/proxy/plugin/'"${PLUGIN_NAME}"'/backend/","endpoint":"http://'"${PLUGIN_HOST}"':8080","authorize":false}]}'
+BRIDGE_PLUGINS="${PLUGIN_NAME}=http://${PLUGIN_HOST}:${PLUGIN_PORT}"
+BRIDGE_PLUGIN_PROXY='{"services":[{"consoleAPIPath":"/api/proxy/plugin/'"${PLUGIN_NAME}"'/backend/","endpoint":"http://'"${PLUGIN_HOST}"':'"${BACKEND_PORT}"'","authorize":false}]}'
 
 # Allow browser to connect to GitHub API (CSP connect-src).
 # Production uses ConsolePlugin.spec.contentSecurityPolicy instead.
@@ -66,4 +74,9 @@ BRIDGE_CONTENT_SECURITY_POLICY="connect-src=https://api.github.com"
 echo "BRIDGE_PLUGINS=$BRIDGE_PLUGINS"
 echo "BRIDGE_PLUGIN_PROXY=$BRIDGE_PLUGIN_PROXY"
 
-$CONTAINER_CMD run --pull always --platform $CONSOLE_IMAGE_PLATFORM --rm $CONTAINER_NETWORK_OPTS --env-file <(env | grep ^BRIDGE) $CONSOLE_IMAGE
+CIDFILE_OPTS=""
+if [ -n "$CIDFILE" ]; then
+  CIDFILE_OPTS="--cidfile $CIDFILE"
+fi
+
+$CONTAINER_CMD run --pull always --platform $CONSOLE_IMAGE_PLATFORM --rm $CIDFILE_OPTS $CONTAINER_NETWORK_OPTS --env-file <(env | grep ^BRIDGE) $CONSOLE_IMAGE
diff --git a/webpack.config.ts b/webpack.config.ts
@@ -61,7 +61,7 @@ const config: Configuration = {
   },
   devServer: {
     static: './dist',
-    port: 9001,
+    port: Number(process.env.PLUGIN_PORT) || 9001,
     // Allow Bridge running in a container to connect to the plugin dev server.
     allowedHosts: 'all',
     headers: {
