thrivekit 2.0.0

package/ralph/verify/review.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# review.sh - Code review verification module for ralph
+
+# Run code review on changes
+run_code_review() {
+  local story="$1"
+
+  # Check if code review is enabled in config
+  local review_enabled
+  review_enabled=$(get_config '.verification.codeReviewEnabled' "true")
+  if [[ "$review_enabled" == "false" ]]; then
+    echo "    (code review disabled in config, skipping)"
+    return 0
+  fi
+
+  # Check if git is available
+  if ! command -v git &>/dev/null || [[ ! -d ".git" ]]; then
+    echo "    (no git repository, skipping)"
+    return 0
+  fi
+
+  # Get the diff of uncommitted changes (limit size to prevent memory issues)
+  local diff
+  local max_diff_lines=2000
+  diff=$(git diff HEAD 2>/dev/null | head -n "$max_diff_lines")
+
+  if [[ -z "$diff" ]]; then
+    # No uncommitted changes, check staged
+    diff=$(git diff --cached 2>/dev/null | head -n "$max_diff_lines")
+  fi
+
+  if [[ -z "$diff" ]]; then
+    echo "    (no changes to review)"
+    return 0
+  fi
+
+  # Check if diff was truncated
+  local full_diff_lines
+  full_diff_lines=$(git diff HEAD 2>/dev/null | wc -l)
+  if [[ "$full_diff_lines" -gt "$max_diff_lines" ]]; then
+    echo "    (diff truncated from $full_diff_lines to $max_diff_lines lines)"
+  fi
+
+  # Get story context for the review
+  local story_json
+  story_json=$(jq --arg id "$story" '.stories[] | select(.id==$id)' "$RALPH_DIR/prd.json" 2>/dev/null)
+
+  # Build the code review prompt
+  local prompt
+  prompt=$(cat <<EOF
+You are a senior code reviewer. Review this diff for a story implementation.
+
+## Story Context
+\`\`\`json
+$story_json
+\`\`\`
+
+## Code Diff
+\`\`\`diff
+$diff
+\`\`\`
+
+## Review Checklist
+
+Check for these issues:
+
+1. **Security** - SQL injection, XSS, command injection, hardcoded secrets, OWASP top 10
+2. **Error handling** - Missing try/catch, unhandled promise rejections, silent failures
+3. **Edge cases** - Null/undefined checks, empty arrays, boundary conditions
+4. **Code quality** - Unused variables, dead code, overly complex logic
+5. **Performance** - N+1 queries, unnecessary re-renders, memory leaks
+6. **Scalability** - Unbounded queries? Missing pagination? Missing indexes? No caching strategy?
+7. **Accessibility** - Missing ARIA labels, keyboard navigation, color contrast (if frontend)
+8. **Story compliance** - Does the code actually implement what the story requires?
+9. **Architecture** - Files in correct directories? Reusing existing components? File size < 300 lines?
+10. **No duplication** - Creating something that already exists? Reinventing utilities?
+
+## Response Format
+
+Respond with ONLY a JSON object:
+{
+  "pass": true/false,
+  "issues": [
+    {
+      "severity": "critical|warning|info",
+      "category": "security|error-handling|edge-case|quality|performance|scalability|a11y|architecture|compliance",
+      "file": "path/to/file",
+      "line": 123,
+      "message": "Description of the issue",
+      "suggestion": "How to fix it"
+    }
+  ],
+  "summary": "Brief overall assessment"
+}
+
+Only fail (pass: false) for critical or multiple warning-level issues.
+EOF
+)
+
+  echo "    Reviewing changes..."
+
+  local result
+  # Timeout for code review (defined in utils.sh)
+  result=$(echo "$prompt" | run_with_timeout "$CODE_REVIEW_TIMEOUT_SECONDS" claude -p --dangerously-skip-permissions 2>/dev/null) || {
+    print_warning "    Code review skipped (Claude unavailable or timed out)"
+    return 0
+  }
+
+  # Save review result
+  mkdir -p "$RALPH_DIR/reviews"
+  echo "$result" > "$RALPH_DIR/reviews/${story}-review.json"
+
+  # Extract JSON from markdown code blocks if present
+  local json_result
+  if echo "$result" | grep -q '```json'; then
+    json_result=$(echo "$result" | sed -n '/```json/,/```/p' | sed '1d;$d')
+  elif echo "$result" | grep -q '```'; then
+    json_result=$(echo "$result" | sed -n '/```/,/```/p' | sed '1d;$d')
+  else
+    json_result="$result"
+  fi
+
+  # Check if result is valid JSON
+  if ! echo "$json_result" | jq -e . >/dev/null 2>&1; then
+    print_warning "    Code review returned invalid response, skipping"
+    return 0
+  fi
+
+  local passed
+  passed=$(echo "$json_result" | jq -r '.pass // true' 2>/dev/null)
+
+  # Handle empty/null result
+  if [[ -z "$passed" || "$passed" == "null" ]]; then
+    print_warning "    Code review inconclusive, continuing"
+    return 0
+  fi
+
+  if [[ "$passed" == "true" ]]; then
+    print_success "passed"
+
+    # Show any warnings/info even on pass
+    local warnings
+    warnings=$(echo "$json_result" | jq -r '.issues[] | select(.severity != "critical") | "      [\(.severity)] \(.message)"' 2>/dev/null)
+    if [[ -n "$warnings" ]]; then
+      echo "    Notes:"
+      echo "$warnings"
+    fi
+    return 0
+  else
+    print_error "failed"
+    echo ""
+
+    # Show all issues
+    echo "    Issues found:"
+    echo "$json_result" | jq -r '.issues[] | "      [\(.severity)] \(.category): \(.message)"' 2>/dev/null
+    echo ""
+    echo "    Summary: $(echo "$json_result" | jq -r '.summary // "Review failed"' 2>/dev/null)"
+
+    # Save for failure context
+    echo "$json_result" > "$RALPH_DIR/last_review_failure.json"
+    return 1
+  fi
+}

package/ralph/verify/tests.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# tests.sh - Test verification module for ralph
+
+# Run unit tests
+run_unit_tests() {
+  local log_file
+  log_file=$(create_temp_file ".log") || return 1
+
+  # Try common test commands
+  local test_cmd
+  test_cmd=$(get_config '.checks.test' "")
+
+  if [[ -z "$test_cmd" ]]; then
+    # Auto-detect test command
+    if [[ -f "package.json" ]] && grep -q '"test"' package.json; then
+      test_cmd="npm test"
+    elif [[ -f "pytest.ini" ]] || [[ -f "pyproject.toml" ]]; then
+      test_cmd="pytest"
+    elif [[ -f "Cargo.toml" ]]; then
+      test_cmd="cargo test"
+    elif [[ -f "go.mod" ]]; then
+      test_cmd="go test ./..."
+    else
+      echo "    (no test command found, skipping)"
+      return 0
+    fi
+  fi
+
+  echo -n "    Running: $test_cmd... "
+
+  if safe_exec "$test_cmd" "$log_file"; then
+    print_success "passed"
+    rm -f "$log_file"
+    return 0
+  else
+    print_error "failed"
+    echo ""
+    echo "    Output (last $MAX_LOG_LINES lines):"
+    tail -"$MAX_LOG_LINES" "$log_file" | sed 's/^/      /'
+    cp "$log_file" "$RALPH_DIR/last_test_failure.log"
+    rm -f "$log_file"
+    return 1
+  fi
+}
+
+# Verify PRD acceptance criteria / test steps
+verify_prd_criteria() {
+  local story="$1"
+
+  local test_steps
+  test_steps=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .testSteps[]?' "$RALPH_DIR/prd.json" 2>/dev/null)
+
+  if [[ -z "$test_steps" ]]; then
+    echo "    (no testSteps defined)"
+    return 0
+  fi
+
+  local failed=0
+  local log_file
+  log_file=$(create_temp_file ".log") || return 1
+
+  while IFS= read -r step; do
+    [[ -z "$step" ]] && continue
+
+    echo -n "    $step... "
+
+    if safe_exec "$step" "$log_file"; then
+      print_success "passed"
+    else
+      print_error "failed"
+      echo ""
+      echo "    Output:"
+      tail -"$MAX_OUTPUT_PREVIEW_LINES" "$log_file" | sed 's/^/      /'
+      failed=1
+    fi
+  done <<< "$test_steps"
+
+  rm -f "$log_file"
+  return $failed
+}

package/ralph/verify.sh

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# verify.sh - Full UAT verification pipeline for ralph
+#
+# This file orchestrates the verification pipeline by sourcing modular components:
+#   - verify/review.sh  - Code review logic
+#   - verify/lint.sh    - Auto-fix + lint checks
+#   - verify/tests.sh   - Unit tests + PRD criteria
+#   - verify/browser.sh - Browser validation
+
+# Validate required source files exist before sourcing
+if [[ ! -f "$RALPH_LIB/playwright.sh" ]]; then
+  echo "Error: Missing $RALPH_LIB/playwright.sh" >&2
+  exit 1
+fi
+if [[ ! -f "$RALPH_LIB/api.sh" ]]; then
+  echo "Error: Missing $RALPH_LIB/api.sh" >&2
+  exit 1
+fi
+
+# Source verification modules
+source "$RALPH_LIB/playwright.sh"
+source "$RALPH_LIB/api.sh"
+
+# Determine the directory where this script lives
+VERIFY_DIR="${RALPH_LIB:-$(dirname "${BASH_SOURCE[0]}")}"
+
+# Source modular verification components
+source "$VERIFY_DIR/verify/review.sh"
+source "$VERIFY_DIR/verify/lint.sh"
+source "$VERIFY_DIR/verify/tests.sh"
+source "$VERIFY_DIR/verify/browser.sh"
+
+run_verification() {
+  local story="$1"
+
+  echo ""
+  print_info "=== Verification: $story ==="
+  echo ""
+
+  # Determine story type
+  local story_type
+  story_type=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .type // "frontend"' "$RALPH_DIR/prd.json" 2>/dev/null)
+
+  local has_test_url
+  has_test_url=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .testUrl // empty' "$RALPH_DIR/prd.json" 2>/dev/null)
+
+  local has_api_endpoints
+  has_api_endpoints=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .apiEndpoints[0] // empty' "$RALPH_DIR/prd.json" 2>/dev/null)
+
+  # Auto-detect type if not specified
+  if [[ -n "$has_api_endpoints" && -z "$has_test_url" ]]; then
+    story_type="backend"
+  fi
+
+  local failed=0
+
+  # ========================================
+  # STEP 1: Code review (catch issues before running tests)
+  # ========================================
+  echo "  [1/6] Running code review..."
+  if ! run_code_review "$story"; then
+    failed=1
+  fi
+
+  # ========================================
+  # STEP 2: Run configured checks (lint, build, etc.)
+  # ========================================
+  if [[ $failed -eq 0 ]]; then
+    echo ""
+    echo "  [2/6] Running configured checks..."
+    if ! run_configured_checks; then
+      failed=1
+    fi
+  fi
+
+  # ========================================
+  # STEP 3: Run unit tests
+  # ========================================
+  if [[ $failed -eq 0 ]]; then
+    echo ""
+    echo "  [3/6] Running unit tests..."
+    if ! run_unit_tests; then
+      failed=1
+    fi
+  fi
+
+  # ========================================
+  # STEP 4: Run Playwright tests (frontend) or API tests (backend)
+  # ========================================
+  if [[ $failed -eq 0 ]]; then
+    echo ""
+    if [[ "$story_type" == "backend" ]]; then
+      echo "  [4/6] Running API tests..."
+      if ! run_api_validation "$story"; then
+        failed=1
+      elif ! run_api_error_tests "$story"; then
+        # Only run error tests if validation passed
+        failed=1
+      fi
+    else
+      echo "  [4/6] Running Playwright tests..."
+      if ! run_playwright_tests "$story"; then
+        failed=1
+      fi
+    fi
+  fi
+
+  # ========================================
+  # STEP 5: Run browser validation (frontend) or API validation (backend)
+  # ========================================
+  if [[ $failed -eq 0 ]]; then
+    echo ""
+    if [[ "$story_type" == "backend" ]]; then
+      echo "  [5/6] Running API validation..."
+      if ! run_api_tests "$story"; then
+        failed=1
+      fi
+    else
+      echo "  [5/6] Running browser validation..."
+      if ! run_browser_validation "$story"; then
+        failed=1
+      fi
+    fi
+  fi
+
+  # ========================================
+  # STEP 6: Run PRD test steps
+  # ========================================
+  if [[ $failed -eq 0 ]]; then
+    echo ""
+    echo "  [6/6] Running PRD test steps..."
+    if ! verify_prd_criteria "$story"; then
+      failed=1
+    fi
+  fi
+
+  # ========================================
+  # Final result
+  # ========================================
+  echo ""
+  if [[ $failed -eq 0 ]]; then
+    print_success "=== All verification passed ==="
+    return 0
+  else
+    print_error "=== Verification failed ==="
+    # Save failure context for next iteration
+    save_failure_context "$story"
+    return 1
+  fi
+}
+
+# Save failure context for next iteration
+save_failure_context() {
+  local story="$1"
+
+  local context_file="$RALPH_DIR/last_failure.txt"
+
+  {
+    echo "=== Failure Context for $story ==="
+    echo "Timestamp: $(date -Iseconds 2>/dev/null || date)"
+    echo ""
+
+    if [[ -f "$RALPH_DIR/last_migration_failure.log" ]]; then
+      echo "--- Migration Failure ---"
+      echo "Database migrations failed. Fix the migration or the code causing it:"
+      tail -50 "$RALPH_DIR/last_migration_failure.log"
+      echo ""
+    fi
+
+    if [[ -f "$RALPH_DIR/last_review_failure.json" ]]; then
+      echo "--- Code Review Failure ---"
+      echo "Issues found by code review:"
+      jq -r '.issues[] | "- [\(.severity)] \(.category): \(.message)\n  File: \(.file // "unknown"):\(.line // "?")\n  Fix: \(.suggestion // "See above")"' "$RALPH_DIR/last_review_failure.json" 2>/dev/null
+      echo ""
+    fi
+
+    if [[ -f "$RALPH_DIR/last_test_failure.log" ]]; then
+      echo "--- Test Failure ---"
+      tail -50 "$RALPH_DIR/last_test_failure.log"
+      echo ""
+    fi
+
+    if [[ -f "$RALPH_DIR/last_playwright_failure.log" ]]; then
+      echo "--- Playwright Failure ---"
+      tail -50 "$RALPH_DIR/last_playwright_failure.log"
+      echo ""
+    fi
+
+    if [[ -f "$RALPH_DIR/last_browser_failure.json" ]]; then
+      echo "--- Browser Validation Failure ---"
+      jq -r '"Errors: " + (.errors | join(", "))' "$RALPH_DIR/last_browser_failure.json" 2>/dev/null
+      jq -r '"Console errors: " + (.consoleErrors | join(", "))' "$RALPH_DIR/last_browser_failure.json" 2>/dev/null
+      jq -r '"Missing elements: " + (.elementsMissing | join(", "))' "$RALPH_DIR/last_browser_failure.json" 2>/dev/null
+      echo ""
+    fi
+
+    if [[ -f "$RALPH_DIR/last_precommit_failure.log" ]]; then
+      echo "--- Pre-commit / Lint Failure ---"
+      echo "Fix these errors before the story can be completed:"
+      echo ""
+      # Extract actual error lines (not warnings-only or file modification messages)
+      grep -E "^error:|: error:|Error:|SyntaxError|✖ [0-9]+ problems|^[^:]+:[0-9]+:[0-9]+: [EF][0-9]+" "$RALPH_DIR/last_precommit_failure.log" | head -30
+      # If no errors shown, show the full log tail
+      if ! grep -qE "^error:|: error:|Error:|SyntaxError|✖ [0-9]+ problems" "$RALPH_DIR/last_precommit_failure.log"; then
+        echo "(Full output):"
+        tail -40 "$RALPH_DIR/last_precommit_failure.log"
+      fi
+      echo ""
+    fi
+
+    if [[ -f "$RALPH_DIR/last_fastapi_response_check.log" ]]; then
+      echo "--- FastAPI Response Model Failure ---"
+      echo "Add Pydantic response_model to these endpoints for proper Swagger docs:"
+      echo ""
+      cat "$RALPH_DIR/last_fastapi_response_check.log"
+      echo ""
+      echo "Fix by adding response_model parameter or return type annotation:"
+      echo '  @router.get("/items", response_model=list[ItemSchema])'
+      echo "  async def get_items() -> list[ItemSchema]:"
+      echo ""
+    fi
+  } > "$context_file"
+}

package/templates/PROMPT.md

@@ -0,0 +1,235 @@
+# Development Session
+
+You are an autonomous coding agent working on a feature using the Ralph workflow.
+
+## Session Startup Checklist
+
+Before writing any code, verify:
+1. Run `pwd` to confirm you're in the correct directory
+2. Read `.ralph/progress.txt` for recent session history
+3. Run `git status` to check for uncommitted work
+4. Review the current story details below
+
+## Your Task
+
+For each story, you must:
+
+### 1. Write Tests First
+
+**For frontend stories:**
+- Write a Playwright test that validates the acceptance criteria
+- Include tests for error handling (API fails, validation errors)
+- Include tests for empty/loading states
+- Include accessibility checks (axe-core)
+- Include mobile viewport test (375px)
+
+**For backend stories:**
+- Write unit tests for the business logic
+- Write API tests that validate all endpoints
+- Test error responses (400, 401, 500)
+- Test validation rules
+
+### 2. Implement the Feature
+
+- Write code to make all tests pass
+- Follow existing patterns in the codebase
+- Handle ALL error cases defined in the story
+- Implement loading states for async operations
+
+### 3. Verify It Actually Works
+
+**Do NOT say you're done until:**
+- All unit tests pass
+- All Playwright tests pass
+- You've opened the browser via MCP and visually verified
+- Console has no errors
+- It works on mobile (375px viewport)
+- Error states are handled gracefully
+
+## Rules
+
+1. **Focus**: Implement ONLY the current story. Do not work on other stories.
+2. **Test first**: Write failing tests before implementation when possible.
+3. **Test frequently**: Run tests after each significant change.
+4. **Error handling is required**: Every story defines error cases - implement them all.
+5. **Verification**: Never complete until browser validation passes.
+6. **NEVER edit prd.json**: Do NOT modify `.ralph/prd.json`. Ralph handles story completion automatically after verification. You only write code and tests.
+7. **Update notes**: After completing work, log what you did in `.ralph/progress.txt` including files created/modified and key decisions made. This helps the next session.
+
+## Verification Checklist
+
+Before considering any story complete:
+
+### Code
+- [ ] All acceptance criteria are met
+- [ ] All error handling from story is implemented
+- [ ] Loading states implemented (if frontend)
+- [ ] Validation implemented (if backend)
+- [ ] TypeScript compiles without errors
+
+### Tests
+- [ ] Unit tests written and passing
+- [ ] Playwright test written and passing (frontend)
+- [ ] API tests written and passing (backend)
+- [ ] Error cases tested
+- [ ] Edge cases tested (empty state, etc.)
+
+### Browser/API Validation
+- [ ] Browser check passes (frontend) - no console errors
+- [ ] Mobile viewport works (375px)
+- [ ] Accessibility passes (can Tab through, focus visible)
+- [ ] API returns correct responses (backend)
+
+### Documentation
+- [ ] Updated `.ralph/progress.txt` with files created/modified
+- [ ] Noted any key decisions or context for next story
+
+### Quality
+- [ ] Linting passes
+- [ ] Existing tests still pass
+
+## If Verification Fails
+
+If any check fails:
+1. Read the error message carefully
+2. Fix the issue
+3. Re-run verification
+4. Iterate until ALL checks pass
+
+Do NOT give up. Keep iterating until it works.
+
+## If Blocked
+
+If you encounter a blocker you cannot resolve:
+1. Document the issue in `.ralph/progress.txt`
+2. Note what you tried and why it didn't work
+3. Suggest potential solutions for the next session
+4. Do NOT mark the story as passing
+
+## Code Quality Standards
+
+### Core Principles
+- **Readability First**: Code is read more than written. Prioritize clarity.
+- **KISS**: Keep it simple. Avoid over-engineering.
+- **DRY**: Don't repeat yourself. Extract reusable logic.
+- **YAGNI**: Don't build features you don't need yet.
+
+### Naming Conventions
+- Variables: descriptive camelCase (`userProfile`, `isLoading`, `marketSearchQuery`)
+- Functions: verb-noun pattern (`fetchUserData`, `validateInput`, `handleSubmit`)
+- Components: PascalCase (`UserProfile`, `MarketCard`)
+- Constants: SCREAMING_SNAKE_CASE (`MAX_RETRIES`, `API_BASE_URL`)
+
+### Immutability (CRITICAL)
+Always use spread operators. Never mutate directly:
+```typescript
+// ❌ Bad - mutation
+user.name = 'new name';
+items.push(newItem);
+
+// ✅ Good - immutable
+const updatedUser = { ...user, name: 'new name' };
+const updatedItems = [...items, newItem];
+```
+
+### Error Handling
+Every async operation needs proper error handling:
+```typescript
+// ✅ Good
+try {
+  const data = await fetchData();
+  return { success: true, data };
+} catch (error) {
+  console.error('Failed to fetch data:', error);
+  return { success: false, error: error.message };
+}
+```
+
+### Type Safety
+- Use TypeScript interfaces for all data shapes
+- Never use `any` - use `unknown` if type is truly unknown
+- Define return types for functions
+
+### Functions
+- Max 50 lines per function (split if longer)
+- Single responsibility - one function does one thing
+- Early returns for guard clauses
+
+### React Specific
+- Functional components with typed props
+- Custom hooks for reusable stateful logic
+- Use `prev =>` for state updates that depend on previous state
+- Avoid excessive ternaries - extract to variables or early returns
+
+### General
+- Follow existing code patterns in the codebase
+- Handle ALL error cases defined in the story
+- Implement loading states for async operations
+- Use meaningful variable and function names
+- Add data-testid attributes for Playwright
+
+## Architecture Rules
+
+- **Put files in the right place**: Follow the directories specified in the PRD
+- **Reuse existing code**: Check for existing components/utils before creating new ones
+- **Don't duplicate**: If something exists, import and use it
+- **Max 300 lines per file**: Split large files into smaller, focused modules
+- **Scripts in scripts/**: Shell scripts and CLI tools go in scripts/ or bin/
+- **Docs in docs/**: Documentation files go in docs/
+- **Single responsibility**: Each file/function does one thing well
+
+## Scalability Rules
+
+For list/query endpoints:
+- **Always paginate**: Never return unbounded arrays
+- **Use cursor-based pagination**: When specified in the PRD
+- **Add database indexes**: For frequently queried fields
+- **Implement caching**: As specified in the PRD (TTL, invalidation)
+- **Eager load relationships**: To avoid N+1 queries
+
+For all endpoints:
+- **Rate limit public endpoints**: As specified in the PRD
+- **Set sensible limits**: Max page size, max request body size
+- **Batch operations**: Use bulk inserts when creating many records
+
+## AI/LLM Configuration
+
+**NEVER hardcode AI model names, API keys, or endpoints.** Always use environment variables or settings.
+
+```python
+# ❌ Bad - hardcoded model
+model = "gpt-4"
+client = OpenAI(api_key="sk-...")
+
+# ✅ Good - from environment/settings
+model = os.environ.get("OPENAI_MODEL", "gpt-4")
+client = OpenAI()  # Uses OPENAI_API_KEY env var
+```
+
+```python
+# ❌ Bad - hardcoded in code
+response = openai.chat.completions.create(
+    model="gpt-4-turbo",
+    max_tokens=4096,
+)
+
+# ✅ Good - from settings/config
+from django.conf import settings
+response = openai.chat.completions.create(
+    model=settings.AI_MODEL,
+    max_tokens=settings.AI_MAX_TOKENS,
+)
+```
+
+If the project has an AI gateway or wrapper, use it:
+```python
+# ✅ Best - use project's AI abstraction
+from myapp.ai import get_completion
+response = get_completion(prompt)
+```
+
+---
+
+## Current Story
+
+(Story details will be injected below by ralph.sh)