feat: better testing server setup for init.sh

- Stop operations use PID files (.dev-pids/) with recursive kill_tree
  instead of pgrep/pkill, handles deep process trees (e.g. yarn->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)
- On compilation failure, errserver returns HTTP 500 with build error
  as JSON so the UI displays actual compiler output
- Watcher shuts down on inotifywait or errserver startup failure
- start-console.sh accepts --backend-port, --plugin-port,
  --console-port, --cidfile CLI args
- Dropped --network=host on Linux, uses -p port mapping everywhere
- 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/
- inotify-tools documented as optional dev prerequisite in README

Signed-off-by: Matej Vašek <matejvasek@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: matejvasek

.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.

.dockerignore

@@ -1 +1,4 @@
 /bin
+.dev-logs
+.dev-pids
+.dev-env.json

.gitignore

@@ -35,6 +35,8 @@ AGENTS.override.md
 # Local development configuration
 .dev
 .dev-logs
+.dev-pids
+.dev-env.json
 
 # Yarn v4 (Berry)
 .yarn/*

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 |

README.md

@@ -48,6 +48,7 @@ Available image tags are listed in the [container registry](https://github.com/t
 - [Docker](https://www.docker.com) or [podman 3.2.0+](https://podman.io)
 - An [OpenShift cluster](https://console.redhat.com/openshift/create)
 - Github [*Personal Access Token*](https://github.com/settings/personal-access-tokens) with *administration*, *content* and *workflow* write permissions in all repositories
+- [inotify-tools](https://github.com/inotify-tools/inotify-tools) (optional, enables Go backend auto-recompile on file changes)
 
 ### Option 1: Local
 

backend/cmd/errserver/main.go

@@ -0,0 +1,30 @@
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+)
+
+func main() {
+	port := flag.Int("port", 8080, "HTTP server port")
+	msgFile := flag.String("msg-file", "", "file containing the error message to serve")
+	flag.Parse()
+
+	msg, err := os.ReadFile(*msgFile)
+	if err != nil {
+		log.Fatalf("Failed to read message file: %v", err)
+	}
+
+	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusInternalServerError)
+		json.NewEncoder(w).Encode(map[string]string{"message": string(msg)})
+	})
+
+	log.Printf("Serving compilation error on :%d", *port)
+	log.Fatal(http.ListenAndServe(fmt.Sprintf(":%d", *port), nil))
+}

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
 

docs/claude-progress.txt

@@ -1,6 +1,32 @@
 # Claude Progress Log
 # Newest entries first. Agents: append your entry at the top after the header.
 
+---
+## 2026-05-18 | Session: Error server and JSON error responses
+Worked on: Errserver for failed Go compilation, JSON error responses for backend
+Completed:
+- Error server (backend/cmd/errserver): on Go build failure, the file watcher starts errserver which returns HTTP 500 with compilation error as JSON {"message": "..."}
+- OCP console's appFetch parses json.message automatically, so the UI shows actual compiler output instead of generic "Internal Server Error"
+Left off: Branch improve-test-cluster, PR #25 open. Backend JSON error response not yet pushed.
+Blockers: None
+
+---
+## 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, PR #25 open.
+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

docs/designs/2026-05-14-better-init-sh-design.md

@@ -0,0 +1,115 @@
+# Better Testing Server Setup (init.sh)
+
+## Goal
+
+Make init.sh suitable for running multiple dev environments concurrently (across different repo clones/worktrees) and improve the Go backend development loop with auto-recompile on file changes.
+
+## Use Case
+
+Multiple repos/worktrees running dev environments simultaneously. Each gets its own randomized ports so there are no collisions.
+
+## Changes
+
+### 1. PID File Management
+
+**Current:** `--stop` uses `pgrep -f` / `pkill -f` with name patterns (e.g. `"bin/backend"`, `"webpack serve"`). Fragile, can kill processes from other repos.
+
+**New:**
+
+- PID files stored in `.dev-pids/` directory (created on startup)
+- Files: `backend.pid`, `webpack.pid`, `backend-watcher.pid`
+- Console container ID stored in `.dev-pids/console.cid` (via `podman run --cidfile`)
+- Each `start_*` function writes `$!` (backgrounded PID) to its PID file
+- Each `stop_*` function reads the PID file, sends SIGTERM, waits briefly, removes the PID file
+- `--stop` iterates over whatever PID/CID files exist (safe if only some services are running)
+
+### 2. Port Randomization
+
+**Current:** Hardcoded ports: backend 8080, webpack 9001, console 9000.
+
+**New:**
+
+- By default, init.sh uses the same hardcoded defaults as today (8080, 9001, 9000) so human testers are not surprised
+- When `--randomize-ports` flag is passed, init.sh picks three random available ports from range 10000-60000
+- A `random_free_port()` helper function loops until it finds an unused port (TCP probe check)
+- `.dev-env.json` is always written at project root, regardless of whether ports are randomized or default:
+  ```json
+  {
+    "backendPort": 12345,
+    "pluginPort": 12346,
+    "consolePort": 12347
+  }
+  ```
+- `--stop` removes `.dev-env.json`
+
+### 3. Go Backend Auto-Recompile
+
+**Current:** `start_backend` builds once and runs the binary. Changes require manual restart.
+
+**New:**
+
+- After backend starts, init.sh spawns a watcher process in the background
+- Watcher uses `inotifywait -m -r -e modify,create,delete,move --include '\.(go|mod|sum)$' backend/` to monitor for Go source and module changes
+- On each event, debounce (1 second) to let rapid successive changes settle
+- Rebuild strategy (build-then-swap):
+  1. Build to temporary binary: `go build -buildvcs=false -o ../bin/backend-tmp .`
+  2. If build fails: log error to `.dev-logs/backend.log`, keep current backend running, continue watching
+  3. If build succeeds: kill current backend (via PID file), move `backend-tmp` to `backend`, start new process, write new PID to `.dev-pids/backend.pid`
+- Watcher gets its own PID file: `.dev-pids/backend-watcher.pid`
+- init.sh checks for `inotifywait` at startup. If missing, prints warning and skips the watcher (backend still works, no auto-reload)
+
+### 4. Port Passing to Downstream Scripts
+
+**start-console.sh:**
+
+- Accepts CLI arguments: `--backend-port`, `--plugin-port`, `--console-port`
+- Each argument falls back to the current hardcoded default (8080, 9001, 9000) so the script works standalone
+- Replaces hardcoded port values in `BRIDGE_PLUGINS`, `BRIDGE_PLUGIN_PROXY`, and the `-p` container port flag
+
+**webpack.config.ts:**
+
+- Dev server port changes from hardcoded `9001` to `Number(process.env.PLUGIN_PORT) || 9001`
+- init.sh exports `PLUGIN_PORT` before running `yarn start`
+
+**init.sh invocations:**
+
+```bash
+PLUGIN_PORT="$PLUGIN_PORT" yarn start > "$LOG_DIR/webpack.log" 2>&1 &
+
+./start-console.sh \
+  --backend-port "$BACKEND_PORT" \
+  --plugin-port "$PLUGIN_PORT" \
+  --console-port "$CONSOLE_PORT" \
+  > "$LOG_DIR/console.log" 2>&1 &
+```
+
+### 5. Agent Awareness
+
+Agents need to know where the dev server is running so they can connect to it (e.g. for browser testing or API calls).
+
+- **CLAUDE.md**: Add `.dev-env.json` and `.dev-logs/` to the knowledge base table, noting dev server ports and log file locations respectively
+- **WORKFLOW.md**: Add a step to the Startup Sequence (after "Run `./init.sh`") to read `.dev-env.json` and note the ports
+- **`.claude/commands/init-session.md`**: Add a step to read `.dev-env.json` and report the ports to the user
+
+## Files Modified
+
+| File | Change |
+|------|--------|
+| `init.sh` | PID files, `--randomize-ports` flag, `.dev-env.json` output, inotifywait backend watcher, pass ports downstream, `--stop` reads PIDs/CID |
+| `start-console.sh` | Accept `--backend-port`, `--plugin-port`, `--console-port` CLI args with fallback defaults |
+| `webpack.config.ts` | Read `PLUGIN_PORT` env var with fallback to 9001 |
+| `.gitignore` | Add `.dev-pids/` and `.dev-env.json` |
+| `.dockerignore` | Add `.dev-pids/` and `.dev-env.json` |
+| `CLAUDE.md` | Add `.dev-env.json` and `.dev-logs/` to knowledge base table |
+| `docs/WORKFLOW.md` | Add port discovery step to Startup Sequence |
+| `.claude/commands/init-session.md` | Add step to read and report dev server ports |
+
+No new files created (besides runtime artifacts which are gitignored/dockerignored).
+
+## Backwards Compatibility
+
+All three modified files retain current default behavior when invoked without the new arguments/env vars. Running `./start-console.sh` directly or `yarn start` without init.sh produces the same ports as today.
+
+## Prerequisites
+
+- `inotify-tools` package for the Go backend watcher. Gracefully degrades if missing (warning printed, watcher skipped).

docs/features.json

@@ -145,6 +145,17 @@
     ],
     "passes": true
   },
+  {
+    "category": "technical",
+    "description": "Better testing server setup (init.sh)",
+    "steps": [
+      "The --stop operation shall employ PID files, not kill processes by name.",
+      "The ports (go backend 8080, webpack server 9001, webconsole container 9000) shall randomized, so it's possible to run multiple testing servers (for multiple Claude instances).",
+      "The randomized ports shall be available to the Claude via a file.",
+      "The go backend service should be automatically recompiled/restarted upon change to the ./backend directory."
+    ],
+    "passes": true
+  },
   {
     "category": "functional",
     "description": "Function List Page shows deployed functions from all user-accessible namespaces without requiring a PAT",