agentic-loop 1.0.0

package/ralph/playwright.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# playwright.sh - Playwright test integration for ralph
+
+# Ensure Playwright is installed and configured
+ensure_playwright() {
+  # Check if playwright config exists
+  if [[ ! -f "playwright.config.ts" ]] && [[ ! -f "playwright.config.js" ]]; then
+    print_info "Playwright not configured, initializing..."
+
+    # Check if npx is available
+    if ! command -v npx &>/dev/null; then
+      print_error "npx not found - cannot install Playwright"
+      return 1
+    fi
+
+    # Install Playwright package and browsers
+    npm install playwright 2>/dev/null && npx playwright install chromium 2>/dev/null || {
+      print_warning "Could not install Playwright - run: npm install playwright && npx playwright install chromium"
+    }
+
+    # Create minimal config if it doesn't exist
+    if [[ ! -f "playwright.config.ts" ]] && [[ ! -f "playwright.config.js" ]]; then
+      print_info "Creating playwright.config.ts..."
+      cat > playwright.config.ts << 'EOF'
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'mobile',
+      use: { ...devices['iPhone 13'] },
+    },
+  ],
+});
+EOF
+    fi
+
+    # Create test directory
+    mkdir -p tests/e2e
+
+    print_success "Playwright initialized"
+  fi
+
+  return 0
+}
+
+# Find test file for a story - uses explicit config or story-level testFile
+find_story_test_file() {
+  local story="$1"
+  local test_dir="$2"
+
+  # 1. Check story for explicit testFile path (preferred)
+  local explicit_file
+  explicit_file=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .testFile // empty' "$RALPH_DIR/prd.json" 2>/dev/null)
+  if [[ -n "$explicit_file" && -f "$explicit_file" ]]; then
+    echo "$explicit_file"
+    return 0
+  fi
+
+  # 2. Check config.json for e2e test directory pattern
+  local config_test_dir
+  config_test_dir=$(get_config '.playwright.testDir' "")
+  if [[ -n "$config_test_dir" ]]; then
+    test_dir="$config_test_dir"
+  fi
+
+  # 3. Standard naming: {testDir}/{story-id}.spec.ts
+  if [[ -f "${test_dir}/${story}.spec.ts" ]]; then
+    echo "${test_dir}/${story}.spec.ts"
+    return 0
+  fi
+  if [[ -f "${test_dir}/${story}.spec.js" ]]; then
+    echo "${test_dir}/${story}.spec.js"
+    return 0
+  fi
+
+  # 4. Slug-based naming from story title
+  local story_slug
+  story_slug=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .title // ""' "$RALPH_DIR/prd.json" 2>/dev/null | \
+    tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//')
+
+  if [[ -n "$story_slug" && -f "${test_dir}/${story_slug}.spec.ts" ]]; then
+    echo "${test_dir}/${story_slug}.spec.ts"
+    return 0
+  fi
+
+  return 1
+}
+
+# Run Playwright tests for a specific story or all tests
+run_playwright_tests() {
+  local story="$1"
+
+  # Check if Playwright is enabled in config
+  local pw_enabled
+  pw_enabled=$(get_config '.playwright.enabled' "true")
+  if [[ "$pw_enabled" == "false" ]]; then
+    echo "    (Playwright disabled in config, skipping)"
+    return 0
+  fi
+
+  # Ensure Playwright is set up
+  if ! ensure_playwright; then
+    return 1
+  fi
+
+  # Check if npx is available
+  if ! command -v npx &>/dev/null; then
+    print_error "npx not found - cannot run Playwright"
+    return 1
+  fi
+
+  # Get test directory from config or use default
+  local test_dir
+  test_dir=$(get_config '.playwright.testDir' "tests/e2e")
+
+  # Find the test file for this story
+  local test_file
+  test_file=$(find_story_test_file "$story" "$test_dir")
+
+  local log_file
+  log_file=$(create_temp_file ".log") || return 1
+
+  echo -n "  Running Playwright tests... "
+
+  if [[ -n "$test_file" && -f "$test_file" ]]; then
+    # Run story-specific test
+    echo -n "(${test_file##*/}) "
+    if npx playwright test "$test_file" --reporter=line > "$log_file" 2>&1; then
+      print_success "passed"
+      rm -f "$log_file"
+      return 0
+    fi
+  else
+    # No story-specific test - check if e2e was expected
+    local e2e_required
+    e2e_required=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .e2e // false' "$RALPH_DIR/prd.json" 2>/dev/null)
+
+    if [[ "$e2e_required" == "true" ]]; then
+      # Show where we looked and how to fix
+      print_warning "missing (e2e: true but no test file found)"
+      echo ""
+      echo "    Looked for: ${test_dir}/${story}.spec.ts"
+      echo ""
+      echo "    Fix options:"
+      echo "    1. Add 'testFile' to story: \"testFile\": \"apps/web/tests/e2e/my-test.spec.ts\""
+      echo "    2. Set testDir in .ralph/config.json: \"playwright\": {\"testDir\": \"apps/web/tests/e2e\"}"
+      echo "    3. Name test file: ${test_dir}/${story}.spec.ts"
+      rm -f "$log_file"
+      return 1  # Fail if e2e was expected but not created
+    fi
+
+    # Check if any tests exist to run
+    if [[ -z "$(find "$test_dir" -name '*.spec.ts' -o -name '*.spec.js' 2>/dev/null | head -1)" ]]; then
+      echo "skipped (not required for this story)"
+      rm -f "$log_file"
+      return 0
+    fi
+
+    # Run all tests
+    if npx playwright test --reporter=line > "$log_file" 2>&1; then
+      print_success "passed"
+      rm -f "$log_file"
+      return 0
+    fi
+  fi
+
+  # Tests failed
+  print_error "failed"
+  echo ""
+  echo "  Playwright output (last $MAX_LOG_LINES lines):"
+  tail -"$MAX_LOG_LINES" "$log_file" | sed 's/^/    /'
+
+  # Save failure for context
+  cp "$log_file" "$RALPH_DIR/last_playwright_failure.log"
+
+  rm -f "$log_file"
+  return 1
+}
+
+# Run Playwright with accessibility checks
+run_playwright_a11y() {
+  local story="$1"
+  local url="$2"
+
+  # Check if @axe-core/playwright is available
+  if ! npm list @axe-core/playwright &>/dev/null 2>&1; then
+    print_info "Installing @axe-core/playwright for accessibility testing..."
+    npm install -D @axe-core/playwright 2>/dev/null || {
+      print_warning "Could not install axe-core, skipping a11y tests"
+      return 0
+    }
+  fi
+
+  # a11y tests are typically part of the Playwright tests
+  # This function can be extended to run standalone a11y audits
+  return 0
+}
+
+# Run Playwright at specific viewport (for mobile testing)
+run_playwright_mobile() {
+  local story="$1"
+
+  local log_file
+  log_file=$(create_temp_file ".log") || return 1
+
+  echo -n "  Running mobile viewport tests... "
+
+  # Run tests with mobile project
+  if npx playwright test --project=mobile --reporter=line > "$log_file" 2>&1; then
+    print_success "passed"
+    rm -f "$log_file"
+    return 0
+  else
+    print_error "failed"
+    echo ""
+    echo "  Mobile test output:"
+    tail -"$MAX_OUTPUT_PREVIEW_LINES" "$log_file" | sed 's/^/    /'
+    rm -f "$log_file"
+    return 1
+  fi
+}

package/ralph/prd.sh

@@ -0,0 +1,295 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# prd.sh - PRD generation functions
+
+ralph_prd() {
+  local notes=""
+  local from_file=""
+
+  # Parse arguments
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --file|-f)
+        from_file="$2"
+        shift 2
+        ;;
+      --accept)
+        ralph_prd_accept
+        return $?
+        ;;
+      *)
+        notes="$notes $1"
+        shift
+        ;;
+    esac
+  done
+
+  # Read from file if specified
+  if [[ -n "$from_file" ]]; then
+    if [[ ! -f "$from_file" ]]; then
+      print_error "File not found: $from_file"
+      return 1
+    fi
+    notes=$(cat "$from_file") || { print_error "Failed to read $from_file"; return 1; }
+  fi
+
+  # Trim leading/trailing whitespace (safer than xargs)
+  notes="${notes#"${notes%%[![:space:]]*}"}"  # trim leading
+  notes="${notes%"${notes##*[![:space:]]}"}"  # trim trailing
+
+  if [[ -z "$notes" ]]; then
+    print_error "No notes provided. Usage: ralph prd <description>"
+    echo ""
+    echo "Examples:"
+    echo "  ralph prd 'Add user authentication with OAuth'"
+    echo "  ralph prd --file docs/feature-spec.md"
+    return 1
+  fi
+
+  # Check if PRD already exists
+  if [[ -f "$RALPH_DIR/prd.json" ]]; then
+    print_warning "A PRD already exists. Archive or delete it first."
+    echo "  Current feature: $(jq -r '.feature.name' "$RALPH_DIR/prd.json")"
+    echo ""
+    echo "Options:"
+    echo "  1. Archive it: mv .ralph/prd.json .ralph/archive/"
+    echo "  2. Delete it:  rm .ralph/prd.json"
+    echo "  3. Check status: ralph status"
+    return 1
+  fi
+
+  # Check Claude CLI is available
+  if ! command -v claude &>/dev/null; then
+    print_error "Claude CLI not found. Install it with: npm install -g @anthropic-ai/claude-code"
+    return 1
+  fi
+
+  echo ""
+  print_info "Starting interactive PRD generation..."
+  echo "Claude will ask clarifying questions to refine the PRD."
+  echo ""
+
+  # Get testUrlBase from config (default to localhost:3000)
+  local test_url_base
+  test_url_base=$(get_config "testUrlBase" "http://localhost:3000")
+
+  # Create the PRD generation prompt using printf to avoid heredoc issues
+  local prompt_file
+  prompt_file=$(create_temp_file ".md") || return 1
+
+  printf '%s\n' "You are generating a PRD (Product Requirements Document) for an autonomous coding agent called Ralph." > "$prompt_file"
+  printf '\n%s\n' "The user provided these feature notes:" >> "$prompt_file"
+  printf '\n%s\n' "---" >> "$prompt_file"
+  printf '%s\n' "$notes" >> "$prompt_file"
+  printf '%s\n' "---" >> "$prompt_file"
+  printf '\n%s\n' "## Your Task" >> "$prompt_file"
+  printf '\n%s\n' "1. First, ask up to 5 clarifying questions about:" >> "$prompt_file"
+  printf '%s\n' "   - Security requirements (auth, permissions, data access)" >> "$prompt_file"
+  printf '%s\n' "   - Scaling concerns (caching, pagination, rate limits)" >> "$prompt_file"
+  printf '%s\n' "   - Edge cases (empty states, error handling)" >> "$prompt_file"
+  printf '%s\n' "   - Related features (what existing features does this touch?)" >> "$prompt_file"
+  printf '%s\n' "   - Scope boundaries (what is explicitly OUT of scope?)" >> "$prompt_file"
+  printf '\n%s\n' "2. After the user answers, generate a prd.json file with this exact structure:" >> "$prompt_file"
+  printf '\n%s\n' '{' >> "$prompt_file"
+  printf '%s\n' '  "feature": {' >> "$prompt_file"
+  printf '%s\n' '    "name": "Feature Name",' >> "$prompt_file"
+  printf '%s\n' '    "branch": "feature/feature-name",' >> "$prompt_file"
+  printf '%s\n' '    "status": "pending"' >> "$prompt_file"
+  printf '%s\n' '  },' >> "$prompt_file"
+  printf '%s\n' '  "metadata": {' >> "$prompt_file"
+  printf '%s\n' '    "security": ["list of security requirements"],' >> "$prompt_file"
+  printf '%s\n' '    "scaling": ["list of scaling concerns"],' >> "$prompt_file"
+  printf '%s\n' '    "relatedFeatures": ["list of related features"],' >> "$prompt_file"
+  printf '%s\n' '    "estimatedStories": 5,' >> "$prompt_file"
+  printf '%s\n' '    "complexity": "low|medium|high"' >> "$prompt_file"
+  printf '%s\n' '  },' >> "$prompt_file"
+  printf '%s\n' '  "scalability": {' >> "$prompt_file"
+  printf '%s\n' '    "expectedScale": "100s | 1000s | 10000s+ users",' >> "$prompt_file"
+  printf '%s\n' '    "pagination": "cursor | offset | none",' >> "$prompt_file"
+  printf '%s\n' '    "caching": "none | in-memory | redis",' >> "$prompt_file"
+  printf '%s\n' '    "rateLimiting": "if needed, requests per minute"' >> "$prompt_file"
+  printf '%s\n' '  },' >> "$prompt_file"
+  printf '%s\n' '  "architecture": {' >> "$prompt_file"
+  printf '%s\n' '    "directories": {' >> "$prompt_file"
+  printf '%s\n' '      "components": "src/components/{feature}/",' >> "$prompt_file"
+  printf '%s\n' '      "api": "src/api/",' >> "$prompt_file"
+  printf '%s\n' '      "types": "src/types/",' >> "$prompt_file"
+  printf '%s\n' '      "scripts": "scripts/",' >> "$prompt_file"
+  printf '%s\n' '      "docs": "docs/"' >> "$prompt_file"
+  printf '%s\n' '    },' >> "$prompt_file"
+  printf '%s\n' '    "patterns": {' >> "$prompt_file"
+  printf '%s\n' '      "reuse": ["existing components/utils to use"],' >> "$prompt_file"
+  printf '%s\n' '      "follow": ["existing patterns to match"]' >> "$prompt_file"
+  printf '%s\n' '    },' >> "$prompt_file"
+  printf '%s\n' '    "principles": {' >> "$prompt_file"
+  printf '%s\n' '      "maxFileLines": 300,' >> "$prompt_file"
+  printf '%s\n' '      "singleResponsibility": true' >> "$prompt_file"
+  printf '%s\n' '    },' >> "$prompt_file"
+  printf '%s\n' '    "doNotCreate": ["things that already exist"]' >> "$prompt_file"
+  printf '%s\n' '  },' >> "$prompt_file"
+  printf '%s\n' '  "stories": [' >> "$prompt_file"
+  printf '%s\n' '    {' >> "$prompt_file"
+  printf '%s\n' '      "id": "TASK-001",' >> "$prompt_file"
+  printf '%s\n' '      "title": "Story title",' >> "$prompt_file"
+  printf '%s\n' '      "passes": false,' >> "$prompt_file"
+  printf '%s\n' "      \"testUrl\": \"${test_url_base}/path/to/test\"," >> "$prompt_file"
+  printf '%s\n' '      "files": {' >> "$prompt_file"
+  printf '%s\n' '        "create": ["paths to new files"],' >> "$prompt_file"
+  printf '%s\n' '        "modify": ["paths to existing files"],' >> "$prompt_file"
+  printf '%s\n' '        "reuse": ["paths to files to import from"]' >> "$prompt_file"
+  printf '%s\n' '      },' >> "$prompt_file"
+  printf '%s\n' '      "acceptanceCriteria": ["AC 1", "AC 2"],' >> "$prompt_file"
+  printf '%s\n' '      "errorHandling": ["what happens on failure"],' >> "$prompt_file"
+  printf '%s\n' '      "testSteps": ["executable shell commands only"],' >> "$prompt_file"
+  printf '%s\n' '      "notes": ""' >> "$prompt_file"
+  printf '%s\n' '    }' >> "$prompt_file"
+  printf '%s\n' '  ]' >> "$prompt_file"
+  printf '%s\n' '}' >> "$prompt_file"
+  printf '\n%s\n' "## Test Steps - CRITICAL" >> "$prompt_file"
+  printf '\n%s\n' "testSteps MUST be executable shell commands. Ralph runs them with bash." >> "$prompt_file"
+  printf '\n%s\n' "GOOD: curl -s http://localhost:3000/api/health | grep ok" >> "$prompt_file"
+  printf '%s\n' "GOOD: test -f src/components/Button.tsx" >> "$prompt_file"
+  printf '%s\n' "GOOD: grep -q 'export function' src/api/users.ts" >> "$prompt_file"
+  printf '%s\n' "GOOD: cd frontend && npx tsc --noEmit" >> "$prompt_file"
+  printf '%s\n' "GOOD: npx playwright test tests/e2e/dashboard.spec.ts" >> "$prompt_file"
+  printf '%s\n' "GOOD: npx playwright test --grep 'login flow'" >> "$prompt_file"
+  printf '\n%s\n' "For UI/visual checks, use Playwright tests that can verify:" >> "$prompt_file"
+  printf '%s\n' "- Element visibility and positioning" >> "$prompt_file"
+  printf '%s\n' "- Console errors (no errors in DevTools)" >> "$prompt_file"
+  printf '%s\n' "- Network requests completing" >> "$prompt_file"
+  printf '%s\n' "- Accessibility (axe-core)" >> "$prompt_file"
+  printf '\n%s\n' "BAD: Visit the page (not a command)" >> "$prompt_file"
+  printf '%s\n' "BAD: User can see the form (not a command)" >> "$prompt_file"
+  printf '%s\n' "BAD: Click submit button (not a command)" >> "$prompt_file"
+  printf '%s\n' "BAD: Check DevTools for errors (not a command)" >> "$prompt_file"
+  printf '\n%s\n' "If something can't be automated, put it in acceptanceCriteria instead." >> "$prompt_file"
+  printf '\n%s\n' "## Context Size Limits" >> "$prompt_file"
+  printf '\n%s\n' "Each story must be completable in ONE Claude session without context overflow:" >> "$prompt_file"
+  printf '%s\n' "- Max ~1000 tokens for story description (title + criteria + error handling)" >> "$prompt_file"
+  printf '%s\n' "- Max 3-4 files created or modified per story" >> "$prompt_file"
+  printf '%s\n' "- If a story feels too big, SPLIT IT" >> "$prompt_file"
+  printf '\n%s\n' "## UI Stories Must Include Browser Verification" >> "$prompt_file"
+  printf '\n%s\n' "For frontend stories, acceptanceCriteria MUST include:" >> "$prompt_file"
+  printf '%s\n' '- "Page loads without console errors"' >> "$prompt_file"
+  printf '%s\n' '- "Required elements render" (specify which: header, form, button)' >> "$prompt_file"
+  printf '%s\n' '- "Works on mobile viewport (375px)"' >> "$prompt_file"
+  printf '\n%s\n' "These get verified by Playwright automatically." >> "$prompt_file"
+  printf '\n%s\n' "## Notes Field" >> "$prompt_file"
+  printf '\n%s\n' 'The "notes" field starts empty. Claude fills it as it works:' >> "$prompt_file"
+  printf '%s\n' "- Files created/modified" >> "$prompt_file"
+  printf '%s\n' "- Key decisions made" >> "$prompt_file"
+  printf '%s\n' "- Context for the next story" >> "$prompt_file"
+  printf '\n%s\n' "## Context Rot Check" >> "$prompt_file"
+  printf '\n%s\n' "Before finalizing, validate:" >> "$prompt_file"
+  printf '%s\n' "- If > 10 stories, recommend splitting into phases" >> "$prompt_file"
+  printf '%s\n' '- If complexity is "high" AND > 5 stories, MUST split' >> "$prompt_file"
+  printf '%s\n' "- Each story should be completable in one Claude session (~10 min)" >> "$prompt_file"
+  printf '\n%s\n' "If splitting is needed, generate ONLY phase 1 and note deferred items." >> "$prompt_file"
+  printf '\n%s\n' "## Output" >> "$prompt_file"
+  printf '\n%s\n' "After questions are answered, output the prd.json content between these exact markers:" >> "$prompt_file"
+  printf '%s\n' "--- BEGIN PRD.JSON ---" >> "$prompt_file"
+  printf '%s\n' "{the json here}" >> "$prompt_file"
+  printf '%s\n' "--- END PRD.JSON ---" >> "$prompt_file"
+
+  # Run Claude interactively (not -p mode so user can answer questions)
+  local output_file
+  output_file=$(create_temp_file ".txt") || return 1
+
+  claude < "$prompt_file" | tee "$output_file"
+
+  # Save output for --accept command (store in RALPH_DIR for security)
+  mkdir -p "$RALPH_DIR"
+  cp "$output_file" "$RALPH_DIR/prd_output.txt"
+
+  rm -f "$prompt_file" "$output_file"
+
+  echo ""
+  echo "---"
+  echo ""
+  print_info "PRD generation complete."
+  echo ""
+  echo "To save the PRD, run: ralph prd --accept"
+  echo "Or manually copy the JSON to .ralph/prd.json"
+}
+
+# Extract PRD from Claude output and save
+ralph_prd_accept() {
+  local output_file="$RALPH_DIR/prd_output.txt"
+
+  if [[ ! -f "$output_file" ]]; then
+    print_error "No PRD output found. Run 'ralph prd' first."
+    return 1
+  fi
+
+  # Extract JSON between markers
+  local prd_json
+  prd_json=$(sed -n '/--- BEGIN PRD.JSON ---/,/--- END PRD.JSON ---/p' "$output_file" | sed '1d;$d')
+
+  if [[ -z "$prd_json" ]]; then
+    print_error "Could not find PRD JSON in output"
+    echo ""
+    echo "The output should contain JSON between markers:"
+    echo "  --- BEGIN PRD.JSON ---"
+    echo "  {...}"
+    echo "  --- END PRD.JSON ---"
+    return 1
+  fi
+
+  # Validate JSON syntax
+  if ! echo "$prd_json" | jq . > /dev/null 2>&1; then
+    print_error "Invalid JSON in PRD"
+    echo ""
+    echo "JSON parsing error. Content:"
+    echo "$prd_json" | head -20
+    return 1
+  fi
+
+  # Validate required fields exist
+  if ! echo "$prd_json" | jq -e '.feature.name and .stories' > /dev/null 2>&1; then
+    print_error "PRD JSON missing required fields (feature.name or stories)"
+    echo ""
+    echo "Ensure the PRD has this structure:"
+    echo '  { "feature": { "name": "..." }, "stories": [...] }'
+    return 1
+  fi
+
+  # Ensure .ralph directory exists
+  mkdir -p "$RALPH_DIR"
+
+  # Normalize the PRD before saving:
+  # - Ensure all stories have passes: false
+  # - Ensure all stories have id and title
+  # - Set status to pending
+  prd_json=$(echo "$prd_json" | jq '
+    .feature.status = "pending" |
+    .stories = [.stories[] | . + {passes: (.passes // false)}]
+  ')
+
+  # Save
+  echo "$prd_json" > "$RALPH_DIR/prd.json"
+
+  # Run full validation
+  if ! validate_prd "$RALPH_DIR/prd.json"; then
+    rm -f "$RALPH_DIR/prd.json"
+    return 1
+  fi
+
+  # Show summary
+  local name stories complexity
+  name=$(echo "$prd_json" | jq -r '.feature.name')
+  stories=$(echo "$prd_json" | jq '.stories | length')
+  complexity=$(echo "$prd_json" | jq -r '.metadata.complexity // "unknown"')
+
+  print_success "PRD saved to $RALPH_DIR/prd.json"
+  echo ""
+  echo "Feature:    $name"
+  echo "Stories:    $stories"
+  echo "Complexity: $complexity"
+  echo ""
+  echo "Next: Run ralph run to start the autonomous loop"
+
+  # Clean up
+  rm -f "$RALPH_DIR/prd_output.txt"
+
+  return 0
+}