@resolveio/server-lib 22.3.33 → 22.3.35

package/src/util/ai-runner-qa-tools.ts

@@ -0,0 +1,538 @@
+export interface ResolveIORunnerQaToolBundleOptions {
+	mode?: 'support' | 'runner';
+	qaClientPort?: number | string;
+	defaultUsername?: string;
+	defaultPassword?: string;
+	toolsBinPath?: string;
+	browserslistPath?: string;
+	mongodbBinaryCachePath?: string;
+	tmpRoot?: string;
+	homeRoot?: string;
+}
+
+function shellDoubleQuote(value: string): string {
+	return String(value || '').replace(/["\\$`]/g, '\\$&');
+}
+
+function normalizePort(value: number | string | undefined, fallback: string): string {
+	const parsed = Number.parseInt(String(value || ''), 10);
+	return Number.isFinite(parsed) && parsed > 0 ? String(parsed) : fallback;
+}
+
+function envVar(mode: 'support' | 'runner', suffix: string): string {
+	return mode === 'support' ? `RESOLVEIO_SUPPORT_QA_${suffix}` : `RESOLVEIO_RUNNER_QA_${suffix}`;
+}
+
+export function buildResolveIORunnerQaEnvScript(options: ResolveIORunnerQaToolBundleOptions = {}): string {
+	const mode = options.mode || 'runner';
+	const altMode = mode === 'support' ? 'runner' : 'support';
+	const tmpRoot = options.tmpRoot || (mode === 'support' ? '/tmp/resolveio-support-qa' : '/tmp/resolveio-ai-runner-qa');
+	const homeRoot = options.homeRoot || `${tmpRoot}/home`;
+	const defaultPort = normalizePort(options.qaClientPort, '4200');
+	const username = shellDoubleQuote(options.defaultUsername || 'admin');
+	const password = shellDoubleQuote(options.defaultPassword || '');
+	const toolsBinPath = options.toolsBinPath || '';
+	const browserslistPath = options.browserslistPath || '';
+	const mongodbBinaryCachePath = options.mongodbBinaryCachePath || '';
+	const clientPortVar = envVar(mode, 'CLIENT_PORT');
+	const altClientPortVar = envVar(altMode, 'CLIENT_PORT');
+	const clientUrlVar = envVar(mode, 'CLIENT_URL');
+	const altClientUrlVar = envVar(altMode, 'CLIENT_URL');
+	const serverUrlVar = envVar(mode, 'SERVER_URL');
+	const altServerUrlVar = envVar(altMode, 'SERVER_URL');
+	const usernameVar = envVar(mode, 'USERNAME');
+	const altUsernameVar = envVar(altMode, 'USERNAME');
+	const passwordVar = envVar(mode, 'PASSWORD');
+	const altPasswordVar = envVar(altMode, 'PASSWORD');
+	const viewportWidthVar = envVar(mode, 'VIEWPORT_WIDTH');
+	const altViewportWidthVar = envVar(altMode, 'VIEWPORT_WIDTH');
+	const viewportHeightVar = envVar(mode, 'VIEWPORT_HEIGHT');
+	const altViewportHeightVar = envVar(altMode, 'VIEWPORT_HEIGHT');
+	const timeoutVar = envVar(mode, 'ANGULAR_STARTUP_TIMEOUT_SECONDS');
+	const altTimeoutVar = envVar(altMode, 'ANGULAR_STARTUP_TIMEOUT_SECONDS');
+	const prebundleVar = envVar(mode, 'ANGULAR_PREBUNDLE');
+	const altPrebundleVar = envVar(altMode, 'ANGULAR_PREBUNDLE');
+	const reuseVar = envVar(mode, 'REUSE_RUNNING');
+	const altReuseVar = envVar(altMode, 'REUSE_RUNNING');
+	const keepaliveVar = envVar(mode, 'KEEPALIVE');
+	const altKeepaliveVar = envVar(altMode, 'KEEPALIVE');
+	const browserLoopVar = mode === 'support' ? 'RESOLVEIO_SUPPORT_QA_BROWSER' : 'RESOLVEIO_RUNNER_QA_BROWSER';
+	return [
+		`export ${mode === 'support' ? 'RESOLVEIO_SUPPORT_QA_TMP' : 'RESOLVEIO_RUNNER_QA_TMP'}="${'${' + (mode === 'support' ? 'RESOLVEIO_SUPPORT_QA_TMP' : 'RESOLVEIO_RUNNER_QA_TMP') + ':-' + tmpRoot + '}'}"`,
+		`export ${mode === 'support' ? 'RESOLVEIO_SUPPORT_QA_HOME' : 'RESOLVEIO_RUNNER_QA_HOME'}="${'${' + (mode === 'support' ? 'RESOLVEIO_SUPPORT_QA_HOME' : 'RESOLVEIO_RUNNER_QA_HOME') + ':-' + homeRoot + '}'}"`,
+		`RESOLVEIO_QA_TMP="${'${' + (mode === 'support' ? 'RESOLVEIO_SUPPORT_QA_TMP' : 'RESOLVEIO_RUNNER_QA_TMP') + '}'}"`,
+		`RESOLVEIO_QA_HOME="${'${' + (mode === 'support' ? 'RESOLVEIO_SUPPORT_QA_HOME' : 'RESOLVEIO_RUNNER_QA_HOME') + '}'}"`,
+		'mkdir -p "$RESOLVEIO_QA_HOME/.nvm" "$RESOLVEIO_QA_TMP/npm-cache" "$RESOLVEIO_QA_TMP/mongodb-binaries" "$RESOLVEIO_QA_TMP/mongodb-memory-server-core"',
+		'if [ ! -f "$RESOLVEIO_QA_HOME/.nvm/nvm.sh" ]; then',
+		'  cat > "$RESOLVEIO_QA_HOME/.nvm/nvm.sh" <<\'RESOLVEIO_NVM_SHIM\'',
+		'nvm() {',
+		'  case "$1" in',
+		'    use|install|alias) return 0 ;;',
+		'    current) node -v 2>/dev/null || true; return 0 ;;',
+		'    *) return 0 ;;',
+		'  esac',
+		'}',
+		'RESOLVEIO_NVM_SHIM',
+		'fi',
+		'export HOME="$RESOLVEIO_QA_HOME"',
+		'export NVM_DIR="$RESOLVEIO_QA_HOME/.nvm"',
+		toolsBinPath ? `export PATH="${toolsBinPath}:$PATH"` : '',
+		'export NODE_ENV=development',
+		browserslistPath ? `export BROWSERSLIST_CONFIG="${browserslistPath}"` : '',
+		`export ${clientPortVar}="${'${' + clientPortVar + ':-${' + altClientPortVar + ':-' + defaultPort + '}}'}"`,
+		`export ${altClientPortVar}="${'${' + altClientPortVar + ':-${' + clientPortVar + '}}'}"`,
+		`export ${clientUrlVar}="${'${' + clientUrlVar + ':-${' + altClientUrlVar + ':-http://localhost:${' + clientPortVar + '}}}'}"`,
+		`export ${altClientUrlVar}="${'${' + altClientUrlVar + ':-${' + clientUrlVar + '}}'}"`,
+		`export ${serverUrlVar}="${'${' + serverUrlVar + ':-${' + altServerUrlVar + ':-http://localhost:8080}}'}"`,
+		`export ${altServerUrlVar}="${'${' + altServerUrlVar + ':-${' + serverUrlVar + '}}'}"`,
+		'export ADDITIONAL_ALLOWED_ORIGINS="${ADDITIONAL_ALLOWED_ORIGINS:-$' + clientUrlVar + '}"',
+		`export ${viewportWidthVar}="${'${' + viewportWidthVar + ':-${' + altViewportWidthVar + ':-1920}}'}"`,
+		`export ${altViewportWidthVar}="${'${' + altViewportWidthVar + ':-${' + viewportWidthVar + '}}'}"`,
+		`export ${viewportHeightVar}="${'${' + viewportHeightVar + ':-${' + altViewportHeightVar + ':-1080}}'}"`,
+		`export ${altViewportHeightVar}="${'${' + altViewportHeightVar + ':-${' + viewportHeightVar + '}}'}"`,
+		`export ${timeoutVar}="${'${' + timeoutVar + ':-${' + altTimeoutVar + ':-900}}'}"`,
+		`export ${altTimeoutVar}="${'${' + altTimeoutVar + ':-${' + timeoutVar + '}}'}"`,
+		`export ${prebundleVar}="${'${' + prebundleVar + ':-${' + altPrebundleVar + ':-false}}'}"`,
+		`export ${altPrebundleVar}="${'${' + altPrebundleVar + ':-${' + prebundleVar + '}}'}"`,
+		`export ${reuseVar}="${'${' + reuseVar + ':-${' + altReuseVar + ':-true}}'}"`,
+		`export ${altReuseVar}="${'${' + altReuseVar + ':-${' + reuseVar + '}}'}"`,
+		`export ${keepaliveVar}="${'${' + keepaliveVar + ':-${' + altKeepaliveVar + ':-false}}'}"`,
+		`export ${altKeepaliveVar}="${'${' + altKeepaliveVar + ':-${' + keepaliveVar + '}}'}"`,
+		`export ${usernameVar}="${'${' + usernameVar + ':-${' + altUsernameVar + ':-' + username + '}}'}"`,
+		`export ${altUsernameVar}="${'${' + altUsernameVar + ':-${' + usernameVar + '}}'}"`,
+		`export ${passwordVar}="${'${' + passwordVar + ':-${' + altPasswordVar + ':-' + password + '}}'}"`,
+		`export ${altPasswordVar}="${'${' + altPasswordVar + ':-${' + passwordVar + '}}'}"`,
+		'export PUPPETEER_CACHE_DIR="${PUPPETEER_CACHE_DIR:-/var/lib/resolveio/puppeteer}"',
+		'if [ ! -d "$PUPPETEER_CACHE_DIR" ] || [ ! -w "$PUPPETEER_CACHE_DIR" ]; then',
+		'  export PUPPETEER_CACHE_DIR="$RESOLVEIO_QA_TMP/puppeteer"',
+		'  mkdir -p "$PUPPETEER_CACHE_DIR"',
+		'fi',
+		`for ${browserLoopVar} in "$PUPPETEER_CACHE_DIR"/chrome-headless-shell/linux-*/chrome-headless-shell-linux64/chrome-headless-shell "$PUPPETEER_CACHE_DIR"/chrome/linux-*/chrome-linux64/chrome; do`,
+		`  if [ -x "$${browserLoopVar}" ]; then`,
+		`    export PUPPETEER_EXECUTABLE_PATH="$${browserLoopVar}"`,
+		`    export CHROME_BIN="$${browserLoopVar}"`,
+		'    break',
+		'  fi',
+		'done',
+		`unset ${browserLoopVar}`,
+		'export NPM_CONFIG_CACHE="$RESOLVEIO_QA_TMP/npm-cache"',
+		'export NPM_CONFIG_PREFER_OFFLINE=true',
+		'export NPM_CONFIG_PRODUCTION=false',
+		'export npm_config_production=false',
+		'export RESOLVEIO_SUPPORT_MONGOMS_PACKAGE_ROOT="$RESOLVEIO_QA_TMP/mongodb-memory-server-core"',
+		'export MONGOMS_DOWNLOAD_DIR="$RESOLVEIO_QA_TMP/mongodb-binaries"',
+		mongodbBinaryCachePath ? `export RESOLVEIO_SUPPORT_SHARED_MONGOMS_DOWNLOAD_DIR="${mongodbBinaryCachePath}"` : '',
+		'export MONGOMS_VERSION="${MONGOMS_VERSION:-7.0.14}"',
+		''
+	].filter((line) => line !== '').join('\n');
+}
+
+export function buildResolveIORunnerLocalQaScript(): string {
+	return [
+		'#!/usr/bin/env bash',
+		'set -u',
+		'TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"',
+		'source "$TOOLS_DIR/env.sh"',
+		'PROJECT_ROOT="${1:-$(pwd)}"',
+		'PROJECT_ROOT="$(cd "$PROJECT_ROOT" && pwd)"',
+		'ARTIFACT_DIR="$PROJECT_ROOT/qa-artifacts"',
+		'mkdir -p "$ARTIFACT_DIR"',
+		'CLIENT_URL="${RESOLVEIO_RUNNER_QA_CLIENT_URL:-${RESOLVEIO_SUPPORT_QA_CLIENT_URL:-http://localhost:${RESOLVEIO_RUNNER_QA_CLIENT_PORT:-${RESOLVEIO_SUPPORT_QA_CLIENT_PORT:-4200}}}}"',
+		'SERVER_URL="${RESOLVEIO_RUNNER_QA_SERVER_URL:-${RESOLVEIO_SUPPORT_QA_SERVER_URL:-http://localhost:8080}}"',
+		'CLIENT_PORT="${RESOLVEIO_RUNNER_QA_CLIENT_PORT:-${RESOLVEIO_SUPPORT_QA_CLIENT_PORT:-4200}}"',
+		'SERVER_PORT="${RESOLVEIO_RUNNER_QA_SERVER_PORT:-${RESOLVEIO_SUPPORT_QA_SERVER_PORT:-8080}}"',
+		'MONGO_PORT="${RESOLVEIO_RUNNER_QA_MONGO_PORT:-${RESOLVEIO_SUPPORT_QA_MONGO_PORT:-3001}}"',
+		'STARTUP_TIMEOUT="${RESOLVEIO_RUNNER_QA_ANGULAR_STARTUP_TIMEOUT_SECONDS:-${RESOLVEIO_SUPPORT_QA_ANGULAR_STARTUP_TIMEOUT_SECONDS:-900}}"',
+		'ANGULAR_PREBUNDLE="${RESOLVEIO_RUNNER_QA_ANGULAR_PREBUNDLE:-${RESOLVEIO_SUPPORT_QA_ANGULAR_PREBUNDLE:-false}}"',
+		'REUSE_RUNNING="${RESOLVEIO_RUNNER_QA_REUSE_RUNNING:-${RESOLVEIO_SUPPORT_QA_REUSE_RUNNING:-true}}"',
+		'KEEPALIVE="${RESOLVEIO_RUNNER_QA_KEEPALIVE:-${RESOLVEIO_SUPPORT_QA_KEEPALIVE:-false}}"',
+		'SERVER_STABLE_SECONDS="${RESOLVEIO_RUNNER_QA_SERVER_STABLE_SECONDS:-${RESOLVEIO_SUPPORT_QA_SERVER_STABLE_SECONDS:-20}}"',
+		'LOCK_DIR="$ARTIFACT_DIR/.qa.lock"',
+		'SERVER_PID=""',
+		'CLIENT_PID=""',
+		'SERVER_REQUIRED=0',
+		'ANGULAR_PREBUNDLE_ARGS=()',
+		'case "${ANGULAR_PREBUNDLE,,}" in',
+		'  false|0|no|off) ANGULAR_PREBUNDLE_ARGS=(--prebundle=false) ;;',
+		'esac',
+		'kill_tree() {',
+		'  local pid="$1"',
+		'  [ -n "$pid" ] || return 0',
+		'  for child in $(pgrep -P "$pid" 2>/dev/null || true); do kill_tree "$child"; done',
+		'  kill "$pid" >/dev/null 2>&1 || true',
+		'  sleep 1',
+		'  kill -0 "$pid" >/dev/null 2>&1 && kill -9 "$pid" >/dev/null 2>&1 || true',
+		'}',
+		'cleanup_project_processes() {',
+		'  for pid_file in "$ARTIFACT_DIR/server.pid" "$ARTIFACT_DIR/client.pid"; do',
+		'    [ -f "$pid_file" ] || continue',
+		'    pid="$(cat "$pid_file" 2>/dev/null || true)"',
+		'    kill_tree "$pid"',
+		'    rm -f "$pid_file"',
+		'  done',
+		'  if command -v lsof >/dev/null 2>&1; then',
+		'    for port in "$CLIENT_PORT" "$SERVER_PORT" "$MONGO_PORT"; do',
+		'      [ -n "$port" ] || continue',
+		'      for pid in $(lsof -ti tcp:"$port" 2>/dev/null || true); do kill_tree "$pid"; done',
+		'    done',
+		'  fi',
+		'  for pid in $(ps -eo pid=,args= | awk -v root="$PROJECT_ROOT" \'index($0, root) && $0 ~ /(ng serve|node .*node_modules\\/\\.bin\\/ng|esbuild|npm run client|start_client\\.sh|npm run server|start_server\\.sh|nodemon|node .*tmp\\/index\\.js|mongod|mongodb-binaries\\/mongod)/ {print $1}\' 2>/dev/null || true); do',
+		'    [ "$pid" = "$$" ] && continue',
+		'    kill_tree "$pid"',
+		'  done',
+		'}',
+		'cleanup() {',
+		'  kill_tree "$SERVER_PID"',
+		'  kill_tree "$CLIENT_PID"',
+		'  cleanup_project_processes',
+		'  rmdir "$LOCK_DIR" >/dev/null 2>&1 || true',
+		'}',
+		'trap cleanup EXIT',
+		'probe_url() { node - "$1" <<\'RESOLVEIO_PROBE\'',
+		'const http = require("http");',
+		'const https = require("https");',
+		'const url = process.argv[2];',
+		'const mod = /^https:/i.test(url) ? https : http;',
+		'const req = mod.get(url, { timeout: 2500 }, (res) => { res.resume(); process.exit(res.statusCode && res.statusCode < 500 ? 0 : 1); });',
+		'req.on("timeout", () => req.destroy(new Error("timeout")));',
+		'req.on("error", () => process.exit(1));',
+		'RESOLVEIO_PROBE',
+		'}',
+		'truthy() { case "${1,,}" in true|1|yes|on) return 0 ;; *) return 1 ;; esac; }',
+		'reuse_running_app_if_ready() {',
+		'  truthy "$REUSE_RUNNING" || return 1',
+		'  [ -d "$PROJECT_ROOT/server" ] && SERVER_REQUIRED=1 || SERVER_REQUIRED=0',
+		'  probe_url "$CLIENT_URL" || return 1',
+		'  if [ "$SERVER_REQUIRED" = "1" ] && ! probe_url "$SERVER_URL"; then return 1; fi',
+		'  echo "ResolveIO AI runner QA reusing already-ready local app at $CLIENT_URL"',
+		'  return 0',
+		'}',
+		'log_has_fatal() {',
+		'  local file="$1"',
+		'  [ -f "$file" ] || return 1',
+		'  grep -Eiq "Unhandled Rejection|Cannot read properties of undefined|TypeError|ReferenceError|EADDRINUSE|app crashed|Failed to compile|Error: Cannot find module|NG[0-9]{4}|TS[0-9]{4}" "$file"',
+		'}',
+		'prepare_angular_cache_dirs() {',
+		'  [ -d "$PROJECT_ROOT" ] || return 0',
+		'  mkdir -p "$PROJECT_ROOT/.angular/cache" 2>/dev/null || true',
+		'  local version=""',
+		'  for pkg in "$PROJECT_ROOT/node_modules/@angular/build/package.json" "$PROJECT_ROOT/node_modules/@angular/cli/package.json" "$PROJECT_ROOT/node_modules/@angular-devkit/build-angular/package.json"; do',
+		'    if [ -f "$pkg" ]; then',
+		'      version="$(node -e "try{console.log(require(process.argv[1]).version||\\\"\\\")}catch(e){}" "$pkg" 2>/dev/null | head -1)"',
+		'      [ -n "$version" ] && break',
+		'    fi',
+		'  done',
+		'  [ -n "$version" ] || return 0',
+		'  node - "$PROJECT_ROOT/angular.json" "$(basename "$PROJECT_ROOT")" <<\'RESOLVEIO_ANGULAR_CACHE_PROJECTS\' | while IFS= read -r project; do',
+		'const fs = require("fs");',
+		'const path = process.argv[2];',
+		'const fallback = process.argv[3];',
+		'const names = new Set([fallback].filter(Boolean));',
+		'try {',
+		'  const parsed = JSON.parse(fs.readFileSync(path, "utf8"));',
+		'  if (parsed.defaultProject) names.add(String(parsed.defaultProject));',
+		'  if (parsed.projects && typeof parsed.projects === "object") Object.keys(parsed.projects).forEach((name) => names.add(String(name)));',
+		'} catch (error) {}',
+		'for (const name of names) console.log(name.replace(/[^A-Za-z0-9._-]/g, "_"));',
+		'RESOLVEIO_ANGULAR_CACHE_PROJECTS',
+		'    [ -n "$project" ] || continue',
+		'    mkdir -p "$PROJECT_ROOT/.angular/cache/$version/$project/vite" 2>/dev/null || true',
+		'  done',
+		'}',
+		'server_has_started() {',
+		'  local file="$ARTIFACT_DIR/server.log"',
+		'  [ -f "$file" ] || return 1',
+		'  grep -Eiq "nodemon.*starting|node .*tmp/index\\.js|Running as Worker|Standalone Node Reaper|listening on|server listening|Server listening|app listening|App listening|Finished .default." "$file"',
+		'}',
+		'wait_for_server_ready() {',
+		'  [ "$SERVER_REQUIRED" = "1" ] || return 0',
+		'  local end=$((SECONDS + STARTUP_TIMEOUT))',
+		'  while [ "$SECONDS" -lt "$end" ]; do',
+		'    if log_has_fatal "$ARTIFACT_DIR/server.log"; then return 4; fi',
+		'    if [ -n "$SERVER_PID" ] && ! kill -0 "$SERVER_PID" >/dev/null 2>&1; then return 4; fi',
+		'    if server_has_started; then',
+		'      local stable_until=$((SECONDS + SERVER_STABLE_SECONDS))',
+		'      while [ "$SECONDS" -lt "$stable_until" ]; do if log_has_fatal "$ARTIFACT_DIR/server.log"; then return 4; fi; sleep 2; done',
+		'      return 0',
+		'    fi',
+		'    sleep 5',
+		'  done',
+		'  return 4',
+		'}',
+		'wait_for_client() {',
+		'  local end=$((SECONDS + STARTUP_TIMEOUT))',
+		'  while [ "$SECONDS" -lt "$end" ]; do',
+		'    if [ -n "$CLIENT_PID" ] && ! kill -0 "$CLIENT_PID" >/dev/null 2>&1; then return 2; fi',
+		'    if log_has_fatal "$ARTIFACT_DIR/client.log"; then return 3; fi',
+		'    if log_has_fatal "$ARTIFACT_DIR/server.log"; then return 4; fi',
+		'    if probe_url "$CLIENT_URL"; then wait_for_server_ready || return $?; return 0; fi',
+		'    sleep 5',
+		'  done',
+		'  return 1',
+		'}',
+		'if reuse_running_app_if_ready; then exit 0; fi',
+		'if ! mkdir "$LOCK_DIR" 2>/dev/null; then',
+		'  echo "ResolveIO AI runner QA lock is already held for $PROJECT_ROOT; cleaning stale local QA processes before retrying." | tee "$ARTIFACT_DIR/runner.log"',
+		'  cleanup_project_processes',
+		'  rmdir "$LOCK_DIR" >/dev/null 2>&1 || true',
+		'  if ! mkdir "$LOCK_DIR" 2>/dev/null; then',
+		'    echo "ResolveIO AI runner QA lock is still held for $PROJECT_ROOT after cleanup. Stop the existing QA runner before starting another." | tee -a "$ARTIFACT_DIR/runner.log"',
+		'    exit 6',
+		'  fi',
+		'fi',
+		'cleanup_project_processes',
+		'if [ -d "$PROJECT_ROOT/server" ]; then',
+		'  SERVER_REQUIRED=1',
+		'  (cd "$PROJECT_ROOT/server" && source "$TOOLS_DIR/env.sh" && { npm run server || ./start_server.sh; } 2>&1 | tee "$ARTIFACT_DIR/server.log") &',
+		'  SERVER_PID=$!',
+		'  wait_for_server_ready',
+		'  SERVER_RESULT=$?',
+		'  if [ "$SERVER_RESULT" != "0" ]; then echo "ResolveIO AI runner QA server startup fatal error. See $ARTIFACT_DIR/server.log"; exit "$SERVER_RESULT"; fi',
+		'fi',
+		'CLIENT_HOST="${RESOLVEIO_RUNNER_QA_CLIENT_HOST:-${RESOLVEIO_SUPPORT_QA_CLIENT_HOST:-0.0.0.0}}"',
+		'if [ -x "$PROJECT_ROOT/node_modules/.bin/ng" ]; then',
+		'  prepare_angular_cache_dirs',
+		'  (cd "$PROJECT_ROOT" && source "$TOOLS_DIR/env.sh" && node --max_old_space_size=8048 ./node_modules/.bin/ng serve --watch --configuration local --host "$CLIENT_HOST" --port "$CLIENT_PORT" "${ANGULAR_PREBUNDLE_ARGS[@]}" 2>&1 | tee "$ARTIFACT_DIR/client.log") &',
+		'elif [ -x "$PROJECT_ROOT/start_client.sh" ]; then',
+		'  (cd "$PROJECT_ROOT" && source "$TOOLS_DIR/env.sh" && ./start_client.sh 2>&1 | tee "$ARTIFACT_DIR/client.log") &',
+		'elif node -e "const p=require(process.argv[1]); process.exit(p.scripts&&p.scripts.client?0:1)" "$PROJECT_ROOT/package.json" >/dev/null 2>&1; then',
+		'  (cd "$PROJECT_ROOT" && source "$TOOLS_DIR/env.sh" && npm run client 2>&1 | tee "$ARTIFACT_DIR/client.log") &',
+		'else',
+		'  echo "ResolveIO AI runner QA cannot find Angular CLI, start_client.sh, or npm client script for $PROJECT_ROOT" | tee "$ARTIFACT_DIR/client.log"',
+		'  exit 5',
+		'fi',
+		'CLIENT_PID=$!',
+		'wait_for_client',
+		'RESULT=$?',
+		'case "$RESULT" in',
+		'  0)',
+		'    echo "ResolveIO AI runner QA local app ready at $CLIENT_URL";',
+		'    echo "$SERVER_PID" > "$ARTIFACT_DIR/server.pid";',
+		'    echo "$CLIENT_PID" > "$ARTIFACT_DIR/client.pid";',
+		'    if truthy "$KEEPALIVE"; then echo "ResolveIO AI runner QA keepalive enabled; server/client remain running until this process is stopped."; wait; fi;',
+		'    exit 0',
+		'    ;;',
+		'  2) echo "ResolveIO AI runner QA client process exited before $CLIENT_URL became ready. See $ARTIFACT_DIR/client.log"; exit 2 ;;',
+		'  3) echo "ResolveIO AI runner QA client startup fatal error. See $ARTIFACT_DIR/client.log"; exit 3 ;;',
+		'  4) echo "ResolveIO AI runner QA server startup fatal error. See $ARTIFACT_DIR/server.log"; exit 4 ;;',
+		'  *) echo "ResolveIO AI runner QA local app did not become ready at $CLIENT_URL within ${STARTUP_TIMEOUT}s. See $ARTIFACT_DIR/client.log and $ARTIFACT_DIR/server.log"; exit 1 ;;',
+		'esac',
+		''
+	].join('\n');
+}
+
+export function buildResolveIORunnerLocalQaStopperScript(): string {
+	return [
+		'#!/usr/bin/env bash',
+		'set -u',
+		'TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"',
+		'source "$TOOLS_DIR/env.sh"',
+		'PROJECT_ROOT="${1:-$(pwd)}"',
+		'PROJECT_ROOT="$(cd "$PROJECT_ROOT" && pwd)"',
+		'ARTIFACT_DIR="$PROJECT_ROOT/qa-artifacts"',
+		'CLIENT_PORT="${RESOLVEIO_RUNNER_QA_CLIENT_PORT:-${RESOLVEIO_SUPPORT_QA_CLIENT_PORT:-4200}}"',
+		'SERVER_PORT="${RESOLVEIO_RUNNER_QA_SERVER_PORT:-${RESOLVEIO_SUPPORT_QA_SERVER_PORT:-8080}}"',
+		'MONGO_PORT="${RESOLVEIO_RUNNER_QA_MONGO_PORT:-${RESOLVEIO_SUPPORT_QA_MONGO_PORT:-3001}}"',
+		'kill_tree() {',
+		'  local pid="$1"',
+		'  [ -n "$pid" ] || return 0',
+		'  kill -0 "$pid" >/dev/null 2>&1 || return 0',
+		'  for child in $(pgrep -P "$pid" 2>/dev/null || true); do kill_tree "$child"; done',
+		'  kill "$pid" >/dev/null 2>&1 || true',
+		'  sleep 1',
+		'  kill -0 "$pid" >/dev/null 2>&1 && kill -9 "$pid" >/dev/null 2>&1 || true',
+		'}',
+		'for pid_file in "$ARTIFACT_DIR/server.pid" "$ARTIFACT_DIR/client.pid"; do',
+		'  [ -f "$pid_file" ] || continue',
+		'  pid="$(cat "$pid_file" 2>/dev/null || true)"',
+		'  kill_tree "$pid"',
+		'  rm -f "$pid_file"',
+		'done',
+		'if command -v lsof >/dev/null 2>&1; then',
+		'  for port in "$CLIENT_PORT" "$SERVER_PORT" "$MONGO_PORT"; do',
+		'    [ -n "$port" ] || continue',
+		'    for pid in $(lsof -ti tcp:"$port" 2>/dev/null || true); do kill_tree "$pid"; done',
+		'  done',
+		'fi',
+		'for pid in $(ps -eo pid=,args= | awk -v root="$PROJECT_ROOT" \'index($0, root) && $0 ~ /(ng serve|node .*node_modules\\/\\.bin\\/ng|esbuild|npm run client|start_client\\.sh|npm run server|start_server\\.sh|nodemon|node .*tmp\\/index\\.js|mongod|mongodb-binaries\\/mongod)/ {print $1}\' 2>/dev/null || true); do',
+		'  [ "$pid" = "$$" ] && continue',
+		'  kill_tree "$pid"',
+		'done',
+		'rmdir "$ARTIFACT_DIR/.qa.lock" >/dev/null 2>&1 || true',
+		'echo "ResolveIO AI runner QA local app stopped for $PROJECT_ROOT"',
+		''
+	].join('\n');
+}
+
+export function buildResolveIORunnerBugfixComparisonQaScript(): string {
+	return [
+		'#!/usr/bin/env bash',
+		'set -u',
+		'TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"',
+		'source "$TOOLS_DIR/env.sh"',
+		'PROJECT_ROOT="${1:-}"',
+		'if [ -z "$PROJECT_ROOT" ]; then',
+		'  echo "Usage: $0 <project-root> [baseline-ref] -- <qa-command...>" >&2',
+		'  exit 2',
+		'fi',
+		'shift || true',
+		'DEFAULT_BASELINE_REF="${RESOLVEIO_RUNNER_QA_BASELINE_REF:-${RESOLVEIO_SUPPORT_QA_BASELINE_REF:-origin/master}}"',
+		'if [ "${1:-}" = "--" ]; then',
+		'  BASELINE_REF="$DEFAULT_BASELINE_REF"',
+		'else',
+		'  BASELINE_REF="${1:-$DEFAULT_BASELINE_REF}"',
+		'  if [ "$#" -gt 0 ]; then shift || true; fi',
+		'fi',
+		'if [ "${1:-}" = "--" ]; then shift; fi',
+		'if [ "$#" -eq 0 ]; then',
+		'  echo "Usage: $0 <project-root> [baseline-ref] -- <qa-command...>" >&2',
+		'  exit 2',
+		'fi',
+		'PROJECT_ROOT="$(cd "$PROJECT_ROOT" && pwd)"',
+		'REPO_ROOT="$(git -C "$PROJECT_ROOT" rev-parse --show-toplevel)"',
+		'PROJECT_REL="$(git -C "$REPO_ROOT" ls-files --full-name "$PROJECT_ROOT" 2>/dev/null | head -1 | xargs dirname 2>/dev/null || true)"',
+		'if [ -z "$PROJECT_REL" ] || [ "$PROJECT_REL" = "." ]; then',
+		'  PROJECT_REL="$(node - "$REPO_ROOT" "$PROJECT_ROOT" <<\'RESOLVEIO_REL\'',
+		'const path = require("path");',
+		'console.log(path.relative(process.argv[2], process.argv[3]) || ".");',
+		'RESOLVEIO_REL',
+		'  )"',
+		'fi',
+		'ARTIFACT_DIR="$PROJECT_ROOT/qa-artifacts"',
+		'mkdir -p "$ARTIFACT_DIR/baseline" "$ARTIFACT_DIR/candidate"',
+		'RESULT_JSON="$ARTIFACT_DIR/bugfix-comparison-result.json"',
+		'CANDIDATE_PATCH="$ARTIFACT_DIR/bugfix-candidate.patch"',
+		'ORIGINAL_HEAD="$(git -C "$REPO_ROOT" rev-parse HEAD)"',
+		'ORIGINAL_BRANCH="$(git -C "$REPO_ROOT" symbolic-ref --short HEAD 2>/dev/null || true)"',
+		'QA_COMMAND=("$@")',
+		'STOPPER="$TOOLS_DIR/stop-local-qa.sh"',
+		'CURRENT_PHASE=""',
+		'stop_local_qa() {',
+		'  "$STOPPER" "$PROJECT_ROOT" >/dev/null 2>&1 || true',
+		'}',
+		'write_json() {',
+		'  node - "$RESULT_JSON" "$@" <<\'RESOLVEIO_WRITE_JSON\'',
+		'const fs = require("fs");',
+		'const [path, status, baselineExit, candidateExit, baselineRef, originalHead, projectRel, note] = process.argv.slice(2);',
+		'const payload = {',
+		'  status,',
+		'  baseline_ref: baselineRef,',
+		'  original_head: originalHead,',
+		'  project: projectRel,',
+		'  baseline_exit_code: Number(baselineExit),',
+		'  candidate_exit_code: Number(candidateExit),',
+		'  code_switch_proven: Number(baselineExit) !== 0 && Number(candidateExit) === 0,',
+		'  candidate_passed: Number(candidateExit) === 0,',
+		'  baseline_failed: Number(baselineExit) !== 0,',
+		'  note,',
+		'  artifact_dirs: { baseline: "qa-artifacts/baseline", candidate: "qa-artifacts/candidate" },',
+		'  created_at: new Date().toISOString()',
+		'};',
+		'fs.writeFileSync(path, JSON.stringify(payload, null, 2));',
+		'console.log(JSON.stringify(payload, null, 2));',
+		'RESOLVEIO_WRITE_JSON',
+		'}',
+		'snapshot_phase_artifacts() {',
+		'  local phase="$1"',
+		'  mkdir -p "$ARTIFACT_DIR/$phase"',
+		'  find "$ARTIFACT_DIR" -maxdepth 1 -type f \\( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.webp" -o -name "*.json" -o -name "*.txt" -o -name "*.log" -o -name "*.zip" \\) -print0 2>/dev/null | while IFS= read -r -d "" file; do',
+		'    cp "$file" "$ARTIFACT_DIR/$phase/$(basename "$file")" 2>/dev/null || true',
+		'  done',
+		'}',
+		'capture_candidate_patch() {',
+		'  : > "$CANDIDATE_PATCH"',
+		'  git -C "$REPO_ROOT" diff --binary -- "$PROJECT_REL" >> "$CANDIDATE_PATCH" || true',
+		'  git -C "$REPO_ROOT" diff --binary --cached -- "$PROJECT_REL" >> "$CANDIDATE_PATCH" || true',
+		'}',
+		'checkout_project_from_ref() {',
+		'  local ref="$1"',
+		'  git -C "$REPO_ROOT" checkout "$ref" -- "$PROJECT_REL"',
+		'}',
+		'restore_candidate() {',
+		'  stop_local_qa',
+		'  checkout_project_from_ref "$ORIGINAL_HEAD" || true',
+		'  if [ -s "$CANDIDATE_PATCH" ]; then',
+		'    git -C "$REPO_ROOT" apply --whitespace=nowarn "$CANDIDATE_PATCH" || true',
+		'  fi',
+		'}',
+		'trap restore_candidate EXIT',
+		'run_phase() {',
+		'  local phase="$1"',
+		'  CURRENT_PHASE="$phase"',
+		'  stop_local_qa',
+		'  export RESOLVEIO_RUNNER_QA_PHASE="$phase"',
+		'  export RESOLVEIO_SUPPORT_QA_PHASE="$phase"',
+		'  export RESOLVEIO_RUNNER_QA_ARTIFACT_DIR="$ARTIFACT_DIR/$phase"',
+		'  export RESOLVEIO_SUPPORT_QA_ARTIFACT_DIR="$ARTIFACT_DIR/$phase"',
+		'  mkdir -p "$ARTIFACT_DIR/$phase"',
+		'  set +e',
+		'  (cd "$REPO_ROOT" && "${QA_COMMAND[@]}") 2>&1 | tee "$ARTIFACT_DIR/$phase/qa-command.log"',
+		'  local rc="${PIPESTATUS[0]}"',
+		'  set +e',
+		'  snapshot_phase_artifacts "$phase"',
+		'  stop_local_qa',
+		'  return "$rc"',
+		'}',
+		'echo "ResolveIO bugfix comparison QA preserving candidate diff for $PROJECT_REL"',
+		'capture_candidate_patch',
+		'stop_local_qa',
+		'echo "ResolveIO bugfix comparison QA baseline phase: $BASELINE_REF"',
+		'checkout_project_from_ref "$BASELINE_REF"',
+		'run_phase baseline',
+		'BASELINE_EXIT="$?"',
+		'echo "ResolveIO bugfix comparison QA candidate phase: restored workspace candidate"',
+		'restore_candidate',
+		'run_phase candidate',
+		'CANDIDATE_EXIT="$?"',
+		'if [ "$CANDIDATE_EXIT" = "0" ] && [ "$BASELINE_EXIT" != "0" ]; then',
+		'  STATUS="pass"',
+		'  NOTE="Baseline failed and candidate passed for the same QA command."',
+		'elif [ "$CANDIDATE_EXIT" = "0" ]; then',
+		'  STATUS="inconclusive_baseline_also_passed"',
+		'  NOTE="Candidate passed, but baseline also passed; the code switch did not prove the bug fix."',
+		'else',
+		'  STATUS="fail_candidate_failed"',
+		'  NOTE="Candidate failed the QA command."',
+		'fi',
+		'write_json "$STATUS" "$BASELINE_EXIT" "$CANDIDATE_EXIT" "$BASELINE_REF" "$ORIGINAL_HEAD" "$PROJECT_REL" "$NOTE"',
+		'[ "$CANDIDATE_EXIT" = "0" ] || exit "$CANDIDATE_EXIT"',
+		'[ "$STATUS" = "pass" ] || exit 8',
+		''
+	].join('\n');
+}
+
+export function buildResolveIORunnerQaToolsReadme(options: ResolveIORunnerQaToolBundleOptions = {}): string {
+	const mode = options.mode || 'runner';
+	const toolsDir = mode === 'support' ? '.resolveio-support-tools' : '.resolveio-ai-runner-tools';
+	const port = normalizePort(options.qaClientPort, '4200');
+	const clientUrlVar = envVar(mode, 'CLIENT_URL');
+	const keepaliveVar = envVar(mode, 'KEEPALIVE');
+	const usernameVar = envVar(mode, 'USERNAME');
+	const passwordVar = envVar(mode, 'PASSWORD');
+	return [
+		`# ResolveIO ${mode === 'support' ? 'Support' : 'AI Runner'} Local QA Tools`,
+		'',
+		'These scripts are generated by `@resolveio/server-lib` and are shared by support tickets, AICoder app-builder runs, and AI-terminal runs.',
+		'',
+		'```bash',
+		`source ${toolsDir}/env.sh`,
+		`${toolsDir}/run-local-qa.sh <project-root>`,
+		`node ${toolsDir}/qa-auth-bootstrap.js <project-root> /target-route`,
+		`${toolsDir}/bugfix-comparison-qa.sh <project-root> origin/master -- bash -lc '<same QA command>'`,
+		'```',
+		'',
+		`This workspace reserves Angular QA client port ${port}; use \`$${clientUrlVar}\` instead of assuming 4200 is free.`,
+		'The local QA runner starts server/client, polls the reserved client URL, writes `qa-artifacts/server.log` and `qa-artifacts/client.log`, and fails fast on fatal startup/runtime errors.',
+		'The shared auth bootstrap calls `/login`, then `/accessToken`, clears service workers/cache/IndexedDB/local storage for the exact localhost client origin, seeds `refreshToken`, `accessToken`, `user`, and `lastURL`, and writes `qa-artifacts/auth-bootstrap-result.json` plus a ready/failure screenshot.',
+		`For browser clickthrough work, start the runner once with \`${keepaliveVar}=true ${toolsDir}/run-local-qa.sh <project-root> &\` and reuse \`$${clientUrlVar}\` for all login/upload/screenshot retries. Do not restart Angular for auth failures.`,
+		'Use desktop screenshots at 1920x1080 by default unless the task is explicitly mobile/responsive. Every screenshot must have a customer-facing caption.',
+		'For import/export/form-submit/data workflows, prove before/action/after with representative data and a concrete row/count/value assertion.',
+		'For bug fixes, use `bugfix-comparison-qa.sh` so baseline/master runs the exact same repro before the candidate/PR run. A passing candidate is not enough unless the comparison result shows baseline failed or the report explicitly explains why the baseline failure could not be reproduced.',
+		`Use \`$${usernameVar}\` and \`$${passwordVar}\` for the local fixture admin account unless ticket/app-specific credentials are provided.`,
+		'The env file reuses `/var/lib/resolveio/puppeteer`, npm cache, worker-safe Browserslist settings, and Angular cache prep so QA should not download a browser or rebuild cold caches unnecessarily.',
+		mode === 'support'
+			? 'Support workspaces also stage local `mongod` and `mongosh` wrappers so app server scripts can start MongoDB when the worker image does not have MongoDB installed.'
+			: '',
+		''
+	].filter((line) => line !== '').join('\n');
+}