agentic-loop 3.19.0 → 3.21.0

package/ralph/hooks/common.sh

@@ -87,3 +87,50 @@ hook_block() {
     "message": $msg
   }'
 }
+
+# Run a warn-* hook with shared boilerplate
+# Usage: run_warn_hook <extensions> <check_fn> [--skip-tests] [--block]
+#   extensions: comma-separated file extensions to match (e.g., "ts,tsx,js,jsx,py")
+#   check_fn:   function name that sets WARNINGS variable
+#   --skip-tests: skip test files
+#   --block:      use hook_block instead of hook_warn on warning
+run_warn_hook() {
+  local extensions="$1"
+  local check_fn="$2"
+  shift 2
+
+  local skip_tests=false
+  local block=false
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --skip-tests) skip_tests=true ;;
+      --block) block=true ;;
+    esac
+    shift
+  done
+
+  parse_hook_input
+
+  if [[ "$skip_tests" == "true" ]] && is_test_file; then
+    hook_allow
+    exit 0
+  fi
+
+  if ! is_code_file "$extensions"; then
+    hook_allow
+    exit 0
+  fi
+
+  WARNINGS=""
+  "$check_fn"
+
+  if [[ -n "$WARNINGS" ]]; then
+    if [[ "$block" == "true" ]]; then
+      hook_block "$WARNINGS"
+    else
+      hook_warn "$WARNINGS"
+    fi
+  else
+    hook_allow
+  fi
+}

package/ralph/hooks/warn-debug.sh

@@ -5,32 +5,18 @@
 
 source "$(dirname "$0")/common.sh"
 
-parse_hook_input
+_check_debug() {
+  if echo "$NEW_CONTENT" | grep -qE 'console\.(log|debug|info|warn|error)[[:space:]]*\('; then
+    WARNINGS="⚠️  Debug statement detected: console.log/debug. Remove before commit."
+  fi
 
-# Only check code files
-if ! is_code_file "ts,tsx,js,jsx,py,go,rs"; then
-  hook_allow
-  exit 0
-fi
+  if echo "$NEW_CONTENT" | grep -qE '^[[:space:]]*debugger[[:space:]]*;?[[:space:]]*$'; then
+    WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Debugger statement detected. Remove before commit."
+  fi
 
-# Check for debug patterns
-WARNINGS=""
+  if echo "$NEW_CONTENT" | grep -qE '^[[:space:]]*print[[:space:]]*\('; then
+    WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Print statement detected. Remove before commit."
+  fi
+}
 
-if echo "$NEW_CONTENT" | grep -qE 'console\.(log|debug|info|warn|error)[[:space:]]*\('; then
-  WARNINGS="⚠️  Debug statement detected: console.log/debug. Remove before commit."
-fi
-
-if echo "$NEW_CONTENT" | grep -qE '^[[:space:]]*debugger[[:space:]]*;?[[:space:]]*$'; then
-  WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Debugger statement detected. Remove before commit."
-fi
-
-if echo "$NEW_CONTENT" | grep -qE '^[[:space:]]*print[[:space:]]*\('; then
-  WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Print statement detected. Remove before commit."
-fi
-
-# Output warning or allow
-if [[ -n "$WARNINGS" ]]; then
-  hook_warn "$WARNINGS"
-else
-  hook_allow
-fi
+run_warn_hook "ts,tsx,js,jsx,py,go,rs" _check_debug

package/ralph/hooks/warn-empty-catch.sh

@@ -5,43 +5,30 @@
 
 source "$(dirname "$0")/common.sh"
 
-parse_hook_input
-
-# Only check code files
-if ! is_code_file "ts,tsx,js,jsx,py"; then
-  hook_allow
-  exit 0
-fi
-
-WARNINGS=""
-
-# JavaScript/TypeScript: catch (e) { } or catch { }
-if echo "$NEW_CONTENT" | grep -qE 'catch[[:space:]]*\([^)]*\)[[:space:]]*\{[[:space:]]*\}'; then
-  WARNINGS="⚠️  Empty catch block detected. Handle the error or add a comment explaining why it's ignored."
-fi
+_check_empty_catch() {
+  # JavaScript/TypeScript: catch (e) { } or catch { }
+  if echo "$NEW_CONTENT" | grep -qE 'catch[[:space:]]*\([^)]*\)[[:space:]]*\{[[:space:]]*\}'; then
+    WARNINGS="⚠️  Empty catch block detected. Handle the error or add a comment explaining why it's ignored."
+  fi
 
-# Also check for catch with only a comment (no actual handling)
-if echo "$NEW_CONTENT" | grep -qE 'catch[[:space:]]*\([^)]*\)[[:space:]]*\{[[:space:]]*(//[^}]*)?\}'; then
-  if [[ -z "$WARNINGS" ]]; then
-    WARNINGS="⚠️  Catch block with no error handling. Consider logging or rethrowing the error."
+  # Also check for catch with only a comment (no actual handling)
+  if echo "$NEW_CONTENT" | grep -qE 'catch[[:space:]]*\([^)]*\)[[:space:]]*\{[[:space:]]*(//[^}]*)?\}'; then
+    if [[ -z "$WARNINGS" ]]; then
+      WARNINGS="⚠️  Catch block with no error handling. Consider logging or rethrowing the error."
+    fi
   fi
-fi
 
-# Python: except: pass or except Exception: pass
-if echo "$NEW_CONTENT" | grep -qE 'except.*:[[:space:]]*pass[[:space:]]*$'; then
-  WARNINGS="⚠️  Empty except block (pass). Handle the exception or add logging."
-fi
+  # Python: except: pass or except Exception: pass
+  if echo "$NEW_CONTENT" | grep -qE 'except.*:[[:space:]]*pass[[:space:]]*$'; then
+    WARNINGS="⚠️  Empty except block (pass). Handle the exception or add logging."
+  fi
 
-# Python: bare except with just pass on next line
-if echo "$NEW_CONTENT" | grep -qE 'except.*:[[:space:]]*$' && echo "$NEW_CONTENT" | grep -qE '^[[:space:]]*pass[[:space:]]*$'; then
-  if [[ -z "$WARNINGS" ]]; then
-    WARNINGS="⚠️  Except block with only 'pass'. Consider logging or reraising the exception."
+  # Python: bare except with just pass on next line
+  if echo "$NEW_CONTENT" | grep -qE 'except.*:[[:space:]]*$' && echo "$NEW_CONTENT" | grep -qE '^[[:space:]]*pass[[:space:]]*$'; then
+    if [[ -z "$WARNINGS" ]]; then
+      WARNINGS="⚠️  Except block with only 'pass'. Consider logging or reraising the exception."
+    fi
   fi
-fi
+}
 
-# Block if empty catch detected (this hook blocks, doesn't just warn)
-if [[ -n "$WARNINGS" ]]; then
-  hook_block "$WARNINGS"
-else
-  hook_allow
-fi
+run_warn_hook "ts,tsx,js,jsx,py" _check_empty_catch --block

package/ralph/hooks/warn-secrets.sh

@@ -7,65 +7,52 @@
 
 source "$(dirname "$0")/common.sh"
 
-parse_hook_input
-
-# Only check code files
-if ! is_code_file "ts,tsx,js,jsx,py,json,yaml,yml,env,env.local,env.development,env.production"; then
-  hook_allow
-  exit 0
-fi
-
-WARNINGS=""
-
-# AWS Access Key (AKIA followed by 16 alphanumeric chars)
-if echo "$NEW_CONTENT" | grep -qE 'AKIA[0-9A-Z]{16}'; then
-  WARNINGS="🚨 SECURITY: Possible AWS Access Key detected! Use environment variables."
-fi
+_check_secrets() {
+  # AWS Access Key (AKIA followed by 16 alphanumeric chars)
+  if echo "$NEW_CONTENT" | grep -qE 'AKIA[0-9A-Z]{16}'; then
+    WARNINGS="🚨 SECURITY: Possible AWS Access Key detected! Use environment variables."
+  fi
 
-# Stripe keys (sk_live_* or sk_test_*)
-if echo "$NEW_CONTENT" | grep -qE 'sk_(live|test)_[0-9a-zA-Z]{24,}'; then
-  WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: Stripe API key detected! Use environment variables."
-fi
+  # Stripe keys (sk_live_* or sk_test_*)
+  if echo "$NEW_CONTENT" | grep -qE 'sk_(live|test)_[0-9a-zA-Z]{24,}'; then
+    WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: Stripe API key detected! Use environment variables."
+  fi
 
-# GitHub tokens (ghp_, gho_, ghu_, ghs_, ghr_)
-if echo "$NEW_CONTENT" | grep -qE 'gh[pousr]_[A-Za-z0-9_]{36,}'; then
-  WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: GitHub token detected! Use environment variables."
-fi
+  # GitHub tokens (ghp_, gho_, ghu_, ghs_, ghr_)
+  if echo "$NEW_CONTENT" | grep -qE 'gh[pousr]_[A-Za-z0-9_]{36,}'; then
+    WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: GitHub token detected! Use environment variables."
+  fi
 
-# Slack tokens (xoxb-, xoxp-, xoxa-, xoxr-, xoxs-)
-if echo "$NEW_CONTENT" | grep -qE 'xox[baprs]-[0-9]{10,}-[0-9a-zA-Z]{24,}'; then
-  WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: Slack token detected! Use environment variables."
-fi
+  # Slack tokens (xoxb-, xoxp-, xoxa-, xoxr-, xoxs-)
+  if echo "$NEW_CONTENT" | grep -qE 'xox[baprs]-[0-9]{10,}-[0-9a-zA-Z]{24,}'; then
+    WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: Slack token detected! Use environment variables."
+  fi
 
-# SendGrid keys (SG.*)
-if echo "$NEW_CONTENT" | grep -qE 'SG\.[a-zA-Z0-9_-]{22}\.[a-zA-Z0-9_-]{43}'; then
-  WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: SendGrid API key detected! Use environment variables."
-fi
+  # SendGrid keys (SG.*)
+  if echo "$NEW_CONTENT" | grep -qE 'SG\.[a-zA-Z0-9_-]{22}\.[a-zA-Z0-9_-]{43}'; then
+    WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: SendGrid API key detected! Use environment variables."
+  fi
 
-# Private keys
-if echo "$NEW_CONTENT" | grep -q -- '-----BEGIN.*PRIVATE KEY-----'; then
-  WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: Private key detected! Never commit private keys."
-fi
+  # Private keys
+  if echo "$NEW_CONTENT" | grep -q -- '-----BEGIN.*PRIVATE KEY-----'; then
+    WARNINGS="${WARNINGS}${WARNINGS:+\\n}🚨 SECURITY: Private key detected! Never commit private keys."
+  fi
 
-# Generic API key patterns (api_key = "...", apikey: "...", etc.)
-if echo "$NEW_CONTENT" | grep -qiE '(api[_-]?key|api[_-]?secret)[[:space:]]*[:=][[:space:]]*['"'"'"][a-zA-Z0-9_-]{20,}['"'"'"]'; then
-  # Check it's not a placeholder
-  if ! echo "$NEW_CONTENT" | grep -qiE '(example|placeholder|your[_-]?key|xxx|test|dummy|fake|sample|demo)'; then
-    WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Possible hardcoded API key - use environment variables."
+  # Generic API key patterns (api_key = "...", apikey: "...", etc.)
+  if echo "$NEW_CONTENT" | grep -qiE '(api[_-]?key|api[_-]?secret)[[:space:]]*[:=][[:space:]]*['"'"'"][a-zA-Z0-9_-]{20,}['"'"'"]'; then
+    # Check it's not a placeholder
+    if ! echo "$NEW_CONTENT" | grep -qiE '(example|placeholder|your[_-]?key|xxx|test|dummy|fake|sample|demo)'; then
+      WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Possible hardcoded API key - use environment variables."
+    fi
   fi
-fi
 
-# Generic secrets (password = "...", token = "...", etc.)
-if echo "$NEW_CONTENT" | grep -qiE '(password|passwd|pwd|secret|token)[[:space:]]*[:=][[:space:]]*['"'"'"][^'"'"'"]{8,}['"'"'"]'; then
-  # Check it's not a placeholder or type annotation
-  if ! echo "$NEW_CONTENT" | grep -qiE '(example|placeholder|xxx|test|dummy|type|interface|password:)'; then
-    WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Possible hardcoded secret - use environment variables."
+  # Generic secrets (password = "...", token = "...", etc.)
+  if echo "$NEW_CONTENT" | grep -qiE '(password|passwd|pwd|secret|token)[[:space:]]*[:=][[:space:]]*['"'"'"][^'"'"'"]{8,}['"'"'"]'; then
+    # Check it's not a placeholder or type annotation
+    if ! echo "$NEW_CONTENT" | grep -qiE '(example|placeholder|xxx|test|dummy|type|interface|password:)'; then
+      WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Possible hardcoded secret - use environment variables."
+    fi
   fi
-fi
+}
 
-# Output warning or allow
-if [[ -n "$WARNINGS" ]]; then
-  hook_warn "$WARNINGS"
-else
-  hook_allow
-fi
+run_warn_hook "ts,tsx,js,jsx,py,json,yaml,yml,env,env.local,env.development,env.production" _check_secrets

package/ralph/hooks/warn-urls.sh

@@ -7,55 +7,35 @@
 
 source "$(dirname "$0")/common.sh"
 
-parse_hook_input
-
-# Skip test files
-if is_test_file; then
-  hook_allow
-  exit 0
-fi
-
-# Only check code files
-if ! is_code_file "ts,tsx,js,jsx,py"; then
-  hook_allow
-  exit 0
-fi
-
-WARNINGS=""
+SAFE_DOMAINS="cdn.jsdelivr.net|cdnjs.cloudflare.com|unpkg.com|fonts.googleapis.com|fonts.gstatic.com|api.github.com|raw.githubusercontent.com|registry.npmjs.org|schema.org|www.w3.org|example.com|example.org"
 
-# Check for localhost URLs
-if echo "$NEW_CONTENT" | grep -qE 'https?://localhost(:[0-9]+)?'; then
-  # Skip if it's in a fallback pattern (|| or ?? or default)
-  if ! echo "$NEW_CONTENT" | grep -qE '(\|\||\?\?|default|fallback).*localhost'; then
-    WARNINGS="⚠️  Hardcoded localhost URL detected - use environment variable (e.g., process.env.API_URL)"
+_check_urls() {
+  # Check for localhost URLs
+  if echo "$NEW_CONTENT" | grep -qE 'https?://localhost(:[0-9]+)?'; then
+    if ! echo "$NEW_CONTENT" | grep -qE '(\|\||\?\?|default|fallback).*localhost'; then
+      WARNINGS="⚠️  Hardcoded localhost URL detected - use environment variable (e.g., process.env.API_URL)"
+    fi
   fi
-fi
 
-# Check for 127.0.0.1 URLs
-if echo "$NEW_CONTENT" | grep -qE 'https?://127\.0\.0\.1(:[0-9]+)?'; then
-  if ! echo "$NEW_CONTENT" | grep -qE '(\|\||\?\?|default|fallback).*127\.0\.0\.1'; then
-    WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Hardcoded 127.0.0.1 URL detected - use environment variable"
+  # Check for 127.0.0.1 URLs
+  if echo "$NEW_CONTENT" | grep -qE 'https?://127\.0\.0\.1(:[0-9]+)?'; then
+    if ! echo "$NEW_CONTENT" | grep -qE '(\|\||\?\?|default|fallback).*127\.0\.0\.1'; then
+      WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Hardcoded 127.0.0.1 URL detected - use environment variable"
+    fi
   fi
-fi
-
-# Check for hardcoded production-looking URLs (skip CDNs and common safe domains)
-SAFE_DOMAINS="cdn.jsdelivr.net|cdnjs.cloudflare.com|unpkg.com|fonts.googleapis.com|fonts.gstatic.com|api.github.com|raw.githubusercontent.com|registry.npmjs.org|schema.org|www.w3.org|example.com|example.org"
-
-# Look for https:// URLs that aren't safe domains
-PROD_URLS=$(echo "$NEW_CONTENT" | grep -oE 'https://[a-zA-Z0-9][a-zA-Z0-9.-]+\.[a-zA-Z]{2,}' | grep -vE "$SAFE_DOMAINS" || true)
 
-if [[ -n "$PROD_URLS" ]]; then
-  # Skip if they look like example/placeholder URLs
-  PROD_URLS=$(echo "$PROD_URLS" | grep -v -E '(example|placeholder|test|mock)' || true)
-  if [[ -n "$PROD_URLS" ]]; then
-    FIRST_URL=$(echo "$PROD_URLS" | head -1)
-    WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Hardcoded URL ($FIRST_URL) - consider using environment variable"
+  # Look for https:// URLs that aren't safe domains
+  local prod_urls
+  prod_urls=$(echo "$NEW_CONTENT" | grep -oE 'https://[a-zA-Z0-9][a-zA-Z0-9.-]+\.[a-zA-Z]{2,}' | grep -vE "$SAFE_DOMAINS" || true)
+
+  if [[ -n "$prod_urls" ]]; then
+    prod_urls=$(echo "$prod_urls" | grep -v -E '(example|placeholder|test|mock)' || true)
+    if [[ -n "$prod_urls" ]]; then
+      local first_url
+      first_url=$(echo "$prod_urls" | head -1)
+      WARNINGS="${WARNINGS}${WARNINGS:+\\n}⚠️  Hardcoded URL ($first_url) - consider using environment variable"
+    fi
   fi
-fi
+}
 
-# Output warning or allow
-if [[ -n "$WARNINGS" ]]; then
-  hook_warn "$WARNINGS"
-else
-  hook_allow
-fi
+run_warn_hook "ts,tsx,js,jsx,py" _check_urls --skip-tests

package/ralph/init.sh

@@ -84,7 +84,7 @@ configure_test_auth() {
   print_info "=== Test Authentication Setup ==="
   echo ""
   echo "Ralph needs test credentials to verify authenticated endpoints."
-  echo "(You can skip this and edit .ralph/config.json later)"
+  echo "(You can skip this and add to .env later)"
   echo ""
 
   # Ask if they want to configure auth
@@ -92,7 +92,7 @@ configure_test_auth() {
   echo ""
 
   if [[ ! $REPLY =~ ^[Yy]$ ]]; then
-    print_info "Skipped. Edit .ralph/config.json to add credentials later."
+    print_info "Skipped. Add RALPH_TEST_USER and RALPH_TEST_PASSWORD to .env when needed."
     return 0
   fi
 
@@ -103,84 +103,31 @@ configure_test_auth() {
 
   if [[ -z "$test_user" || -z "$test_password" ]]; then
     print_warning "Credentials not provided."
-    echo "  Options to add them later:"
-    echo "    1. Edit .ralph/config.json (stored in plain text)"
-    echo "    2. Set RALPH_TEST_USER and RALPH_TEST_PASSWORD env vars (recommended)"
+    echo "  Add to .env later:"
+    echo "    RALPH_TEST_USER=your-email"
+    echo "    RALPH_TEST_PASSWORD=your-password"
     return 0
   fi
 
-  # Update config.json with credentials
-  local config="$RALPH_DIR/config.json"
-  if [[ -f "$config" ]]; then
+  # Save credentials to .env (gitignored, never committed)
+  if [[ ! -f ".env" ]]; then
+    touch ".env"
+  fi
+
+  # Remove old entries if present
+  if grep -q "^RALPH_TEST_USER=" .env 2>/dev/null; then
     local tmpfile
     tmpfile=$(mktemp)
-    if jq --arg user "$test_user" --arg pass "$test_password" \
-       '.auth.testUser = $user | .auth.testPassword = $pass' \
-       "$config" > "$tmpfile" 2>/dev/null; then
-      mv "$tmpfile" "$config"
-      print_success "Test credentials saved to .ralph/config.json"
-      print_warning "Note: Credentials stored in plain text. Consider using env vars instead:"
-      echo "    export RALPH_TEST_USER='$test_user'"
-      echo "    export RALPH_TEST_PASSWORD='****'"
-    else
-      rm -f "$tmpfile"
-      print_warning "Failed to update config. Edit .ralph/config.json manually."
-    fi
+    grep -v "^RALPH_TEST_USER=\|^RALPH_TEST_PASSWORD=" .env > "$tmpfile" && mv "$tmpfile" .env
   fi
-}
 
-# Detect the type of project based on files present
-detect_project_type() {
-  local project_type="minimal"
-
-  # Check for fullstack patterns first (more specific)
-  if [[ -d "frontend" && -d "core" ]]; then
-    project_type="fullstack"
-  elif [[ -d "frontend" && -d "backend" ]]; then
-    project_type="fullstack"
-  elif [[ -d "apps" ]]; then
-    project_type="fullstack"  # Monorepo
-  # Then check for single-language projects
-  elif [[ -f "Cargo.toml" ]]; then
-    project_type="rust"
-  elif [[ -f "go.mod" ]]; then
-    project_type="go"
-  elif [[ -f "mix.exs" ]]; then
-    project_type="elixir"
-  # Check for Python framework variants (more specific first)
-  elif [[ -f "pyproject.toml" ]]; then
-    # FastMCP detection (check for fastmcp in any quote style)
-    if grep -qiE "(fastmcp|\"fastmcp\"|'fastmcp')" pyproject.toml 2>/dev/null; then
-      project_type="fastmcp"
-    # Django detection
-    elif grep -qiE "(django|\"django\"|'django')" pyproject.toml 2>/dev/null || [[ -f "manage.py" ]]; then
-      project_type="django"
-    # FastAPI detection
-    elif grep -qiE "(fastapi|\"fastapi\"|'fastapi')" pyproject.toml 2>/dev/null; then
-      project_type="fastapi"
-    else
-      project_type="python"
-    fi
-  elif [[ -f "requirements.txt" || -f "setup.py" ]]; then
-    # Check requirements.txt for frameworks
-    if [[ -f "requirements.txt" ]]; then
-      if grep -qi 'fastmcp' requirements.txt 2>/dev/null; then
-        project_type="fastmcp"
-      elif grep -qi 'django' requirements.txt 2>/dev/null || [[ -f "manage.py" ]]; then
-        project_type="django"
-      elif grep -qi 'fastapi' requirements.txt 2>/dev/null; then
-        project_type="fastapi"
-      else
-        project_type="python"
-      fi
-    else
-      project_type="python"
-    fi
-  elif [[ -f "package.json" ]]; then
-    project_type="node"
-  fi
+  # Append credentials
+  echo "" >> .env
+  echo "# Test credentials for browser automation (auto-added by ralph init)" >> .env
+  printf 'RALPH_TEST_USER=%s\n' "$test_user" >> .env
+  printf 'RALPH_TEST_PASSWORD=%s\n' "$test_password" >> .env
 
-  echo "$project_type"
+  print_success "Test credentials saved to .env (gitignored — never committed)"
 }
 
 # Auto-detect and configure project-specific settings
@@ -215,7 +162,7 @@ auto_configure_project() {
     fi
   fi
 
-  # 2. Detect testUrlBase by parsing actual config files for port values
+  # 2. Detect urls.frontend by parsing actual config files for port values
   local base_url=""
   local web_port=""
 
@@ -281,11 +228,11 @@ auto_configure_project() {
   fi
 
   if [[ -n "$base_url" ]]; then
-    if jq -e '.testUrlBase' "$tmpfile" >/dev/null 2>&1 && [[ "$(jq -r '.testUrlBase' "$tmpfile")" != "" ]]; then
-      : # Already set
-    else
-      jq --arg url "$base_url" '.testUrlBase = $url' "$tmpfile" > "${tmpfile}.new" && mv "${tmpfile}.new" "$tmpfile"
-      echo "  Auto-detected testUrlBase: $base_url"
+    local existing_frontend
+    existing_frontend=$(jq -r '.urls.frontend // empty' "$tmpfile" 2>/dev/null)
+    if [[ -z "$existing_frontend" ]]; then
+      jq --arg url "$base_url" '.urls.frontend = $url' "$tmpfile" > "${tmpfile}.new" && mv "${tmpfile}.new" "$tmpfile"
+      echo "  Auto-detected urls.frontend: $base_url"
       updated=true
     fi
   fi
@@ -448,7 +395,7 @@ auto_configure_project() {
       if ! jq -e '.mcp.serverModule' "$tmpfile" >/dev/null 2>&1 || [[ "$(jq -r '.mcp.serverModule' "$tmpfile")" == "" ]]; then
         jq --arg mod "$mcp_module" '.mcp.serverModule = $mod' "$tmpfile" > "${tmpfile}.new" && mv "${tmpfile}.new" "$tmpfile"
         # Also update the dev command
-        jq --arg cmd "python -m ${mcp_module}.server" '.commands.dev = $cmd' "$tmpfile" > "${tmpfile}.new" && mv "${tmpfile}.new" "$tmpfile"
+        jq --arg cmd "python3 -m ${mcp_module}.server" '.commands.dev = $cmd' "$tmpfile" > "${tmpfile}.new" && mv "${tmpfile}.new" "$tmpfile"
         echo "  Auto-detected mcp.serverModule: $mcp_module"
         updated=true
       fi
@@ -586,11 +533,13 @@ auto_configure_project() {
       updated=true
     fi
   else
-    # No tests found - check if warning is suppressed
+    # No tests found by auto-detection - check if already configured or warning suppressed
     local require_tests
     require_tests=$(jq -r '.checks.requireTests // true' "$tmpfile" 2>/dev/null)
+    local existing_test_dir
+    existing_test_dir=$(jq -r '.tests.directory // empty' "$tmpfile" 2>/dev/null)
 
-    if [[ "$require_tests" == "true" ]]; then
+    if [[ "$require_tests" == "true" && -z "$existing_test_dir" ]]; then
       echo ""
       print_warning "No test directory or test files found."
       echo "  Without tests, Ralph relies on lint, type-checking, and PRD test steps."
@@ -630,6 +579,20 @@ auto_configure_project() {
         echo "  Auto-updated commands.dev: $new_dev"
         updated=true
       fi
+    else
+      # No runner detected — convert bare 'python' to 'python3' for macOS compat
+      local current_dev
+      current_dev=$(jq -r '.commands.dev // ""' "$tmpfile" 2>/dev/null)
+      if [[ "$current_dev" == "python "* ]]; then
+        local new_dev="python3 ${current_dev#python }"
+        jq --arg dev "$new_dev" '.commands.dev = $dev' "$tmpfile" > "${tmpfile}.new" && mv "${tmpfile}.new" "$tmpfile"
+        echo "  Auto-updated commands.dev: $new_dev (macOS compat)"
+        updated=true
+      fi
+      echo ""
+      echo "  Tip: No Python package manager detected. Consider uv for faster deps & consistent environments:"
+      echo "       curl -LsSf https://astral.sh/uv/install.sh | sh"
+      echo "       https://docs.astral.sh/uv/"
     fi
   fi
 
@@ -742,13 +705,22 @@ Commands:
   prd <notes>             Generate PRD interactively (quick mode)
   prd --file <file>       Generate PRD from file
   run                     Run autonomous loop until all stories pass
-  run --max <n>           Run with max iterations (default: 20)
+  run --max <n>           Limit to n iterations (no limit by default)
   run --fast              Skip code review for faster iterations
+  run --quiet             Suppress the live activity feed
   stop                    Stop loop after current story finishes
   skip                    Skip the current story, move to next
   status                  Show current feature and story status
   check                   Run verification checks only
   verify <story-id>       Verify a specific story
+  uat                     Run UAT loop (team explores, tests, fixes bugs)
+  uat --plan-only         Generate test plan without executing
+  uat --focus <id|cat>    Run specific test case or category
+  uat --no-fix            Write tests but don't fix app bugs
+  uat --review            Force review of existing plan
+  chaos-agent             Run Chaos Agent (adversarial red team testing)
+  chaos-agent --plan-only Generate chaos plan without executing
+  chaos-agent --no-fix    Find vulnerabilities without fixing
   sign <pattern> [cat]    Add a learned pattern (sign)
   signs                   List all learned patterns
   backup                  Backup detected databases to .backups/
@@ -766,6 +738,10 @@ Examples:
   npx agentic-loop prd "Add a contact form"
   npx agentic-loop run
   npx agentic-loop run --max 10
+  npx agentic-loop uat
+  npx agentic-loop uat --focus auth
+  npx agentic-loop chaos-agent
+  npx agentic-loop chaos-agent --no-fix
   npx agentic-loop status
   npx agentic-loop sign "Always use camelCase" frontend