AI-Powered Feature Validation

Run comprehensive validation with intelligent flow generation, interactive error detection, and automatic project type detection.

Initialize Validation

echo "🔍 SpecLabs Feature Validation v2.7.0"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""

# Parse arguments
PROJECT_PATH=""
SESSION_ID=""
TYPE_OVERRIDE="auto"
FLOWS_FILE=""
BASE_URL=""

# Check if first arg is a path (doesn't start with --)
if [ -n "$1" ] && [ "${1:0:2}" != "--" ]; then
  PROJECT_PATH="$1"
  shift
else
  PROJECT_PATH="$(pwd)"
fi

while [[ $# -gt 0 ]]; do
  case "$1" in
    --session-id) SESSION_ID="$2"; shift 2 ;;
    --type) TYPE_OVERRIDE="$2"; shift 2 ;;
    --flows) FLOWS_FILE="$2"; shift 2 ;;
    --url) BASE_URL="$2"; shift 2 ;;
    *) shift ;;
  esac
done

# Validate project path exists
if [ ! -d "$PROJECT_PATH" ]; then
  echo "❌ Error: Project path does not exist: $PROJECT_PATH"
  exit 1
fi

echo "📁 Project: $PROJECT_PATH"
echo ""

# Detect web project and Chrome DevTools MCP availability
PLUGIN_DIR="/home/marty/code-projects/specswarm/plugins/speclabs"
SPECSWARM_PLUGIN_DIR="/home/marty/code-projects/specswarm/plugins/specswarm"

if [ -f "$SPECSWARM_PLUGIN_DIR/lib/web-project-detector.sh" ]; then
  source "$SPECSWARM_PLUGIN_DIR/lib/web-project-detector.sh"

  # Check if Chrome DevTools MCP should be used
  if should_use_chrome_devtools "$PROJECT_PATH"; then
    export CHROME_DEVTOOLS_MODE="enabled"
    export WEB_FRAMEWORK="$WEB_FRAMEWORK"
    echo "🌐 Web project detected: $WEB_FRAMEWORK"
    echo "🎯 Chrome DevTools MCP: Available for browser automation"
    echo "   (saves ~200MB Chromium download)"
    echo ""
  elif is_web_project "$PROJECT_PATH"; then
    export CHROME_DEVTOOLS_MODE="fallback"
    export WEB_FRAMEWORK="$WEB_FRAMEWORK"
    echo "🌐 Web project detected: $WEB_FRAMEWORK"
    echo "📦 Using Playwright fallback for browser automation"
    echo ""
  else
    export CHROME_DEVTOOLS_MODE="disabled"
  fi
fi

# Source validation orchestrator
source "${PLUGIN_DIR}/lib/validate-feature-orchestrator.sh"

Execute Validation

# Build orchestrator arguments
ORCHESTRATOR_ARGS=(--project-path "$PROJECT_PATH")

[ -n "$SESSION_ID" ] && ORCHESTRATOR_ARGS+=(--session-id "$SESSION_ID")
[ "$TYPE_OVERRIDE" != "auto" ] && ORCHESTRATOR_ARGS+=(--type "$TYPE_OVERRIDE")
[ -n "$FLOWS_FILE" ] && ORCHESTRATOR_ARGS+=(--flows "$FLOWS_FILE")
[ -n "$BASE_URL" ] && ORCHESTRATOR_ARGS+=(--url "$BASE_URL")

# Execute validation
VALIDATION_RESULT=$(validate_feature_orchestrate "${ORCHESTRATOR_ARGS[@]}")
VALIDATION_EXIT_CODE=$?

if [ $VALIDATION_EXIT_CODE -ne 0 ]; then
  echo ""
  echo "❌ Validation failed to execute"
  echo ""
  echo "Result:"
  echo "$VALIDATION_RESULT" | jq '.'
  exit 1
fi

Display Results

# Parse result
STATUS=$(echo "$VALIDATION_RESULT" | jq -r '.status')
TYPE=$(echo "$VALIDATION_RESULT" | jq -r '.type')
TOTAL_FLOWS=$(echo "$VALIDATION_RESULT" | jq -r '.summary.total_flows')
PASSED_FLOWS=$(echo "$VALIDATION_RESULT" | jq -r '.summary.passed_flows')
FAILED_FLOWS=$(echo "$VALIDATION_RESULT" | jq -r '.summary.failed_flows')
ERROR_COUNT=$(echo "$VALIDATION_RESULT" | jq -r '.summary.error_count')
DURATION=$(echo "$VALIDATION_RESULT" | jq -r '.metadata.duration_seconds')

# Display summary using orchestrator helper
print_validation_summary "$VALIDATION_RESULT"

# Update session if session ID provided
if [ -n "$SESSION_ID" ]; then
  echo "💾 Updating session: $SESSION_ID"

  # Source feature orchestrator
  source "${PLUGIN_DIR}/lib/feature-orchestrator.sh"
  feature_init

  # Store validation results in session
  SESSION_FILE="${FEATURE_SESSION_DIR}/${SESSION_ID}.json"
  if [ -f "$SESSION_FILE" ]; then
    jq --argjson result "$VALIDATION_RESULT" \
       --arg completed_at "$(date -Iseconds)" \
       '.validation = $result |
        .validation.completed_at = $completed_at' \
       "$SESSION_FILE" > "${SESSION_FILE}.tmp"

    mv "${SESSION_FILE}.tmp" "$SESSION_FILE"
    echo "   ✅ Session updated with validation results"
  else
    echo "   ⚠️  Session file not found (validation results not persisted)"
  fi
fi

echo ""

Validation Status Exit Code

# Display Chrome DevTools MCP tip for web projects (if applicable)
if [ "$CHROME_DEVTOOLS_MODE" = "fallback" ]; then
  echo ""
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "💡 TIP: Enhanced Web Validation Available"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo ""
  echo "Chrome DevTools MCP provides enhanced browser automation:"
  echo "  • Real-time console error monitoring"
  echo "  • Network request inspection during flows"
  echo "  • Runtime state debugging"
  echo "  • Saves ~200MB Chromium download"
  echo ""
  echo "Install Chrome DevTools MCP:"
  echo "  claude mcp add ChromeDevTools/chrome-devtools-mcp"
  echo ""
  echo "Your validation will automatically use it next time!"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo ""
fi

# Exit with appropriate code based on validation status
if [ "$STATUS" = "passed" ]; then
  echo "✅ VALIDATION PASSED"
  exit 0
elif [ "$STATUS" = "failed" ]; then
  echo "⚠️  VALIDATION FAILED"
  exit 1
else
  echo "❌ VALIDATION ERROR"
  exit 1
fi

---

Features

Automatic Project Type Detection

• Webapp: Detects React, Vite, Next.js, React Router applications
• Android: Detects Android projects with AndroidManifest.xml
• REST API: Detects OpenAPI specs, Express, FastAPI, Flask
• Desktop GUI: Detects Electron, PyQt, Tkinter applications

Detection uses file-based analysis with confidence scoring. Manual override available via --type flag.

Intelligent Flow Generation (Webapp)

• User-Defined Flows: Parse from spec.md YAML frontmatter or custom flows file
• AI-Generated Flows: Analyze feature artifacts (spec.md, plan.md, tasks.md)
• Feature Type Detection: Identifies shopping_cart, social_feed, auth, forms, CRUD patterns
• Smart Merging: Combines user + AI flows with deduplication

Interactive Error Detection (Webapp)

• Browser Automation: Chrome DevTools MCP (if installed) or Playwright fallback
• Chrome DevTools MCP Benefits:
  • Saves ~200MB Chromium download
  • Persistent browser profile (~/.cache/chrome-devtools-mcp/)
  • Enhanced debugging with real-time console/network monitoring
• Real-Time Error Capture: Console errors, uncaught exceptions, network failures
• Terminal Monitoring: Tracks dev server output for compilation errors
• Auto-Fix Retry Loop: Attempts fixes up to 3 times before manual intervention
• Dev Server Lifecycle: Automatic startup and guaranteed cleanup

Standardized Results

• JSON Output: Consistent format across all validator types
• Rich Metadata: Duration, tool versions, retry attempts, flow counts
• Artifacts: Screenshots, logs, detailed reports
• Session Integration: Automatic persistence when session ID provided

---

Usage Examples

Standalone Validation

# Validate current directory (auto-detect type)
/speclabs:validate-feature

# Validate specific project
/speclabs:validate-feature /path/to/my-app

# Override detected type
/speclabs:validate-feature /path/to/project --type webapp

# Use custom flows
/speclabs:validate-feature --flows ./custom-flows.json

# Override base URL
/speclabs:validate-feature --url http://localhost:3000

Integrated with Orchestration

# Called automatically by orchestrate-feature when --validate is used
/speclabs:orchestrate-feature "Add shopping cart" /path/to/project --validate

# Manual validation with session tracking
/speclabs:validate-feature /path/to/project --session-id feature_20251103_143022

CI/CD Integration

# Exit code 0 = passed, 1 = failed, useful for CI/CD
/speclabs:validate-feature && echo "Deploy approved" || echo "Fix errors before deploy"

---

Output

Validation Summary

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  VALIDATION SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type: webapp
  Status: passed
  Duration: 47s

  Flows: 8/8 passed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Artifacts Location

• Flow Results: <project>/.speclabs/validation/flow-results.json
• Screenshots: <project>/.speclabs/validation/screenshots/*.png
• Dev Server Log: <project>/.speclabs/validation/dev-server.log
• Test Output: <project>/.speclabs/validation/test-output-*.log

---

Supported Validators

v2.7.0

• ✅ webapp: Full support with AI flows + Chrome DevTools MCP/Playwright + auto-fix

Future Versions

• ⏳ android: Planned for v2.7.1 (Appium-based)
• ⏳ rest-api: Planned for v2.7.2 (Newman/Postman-based)
• ⏳ desktop-gui: Planned for v2.7.3 (Electron/desktop automation)

---

Architecture: Generic orchestrator with pluggable type-specific validators. Extensible design allows adding new validator types without breaking changes.

Purpose: Provide comprehensive, automated validation across any software type, with intelligent flow generation and interactive error detection. Reduces manual testing burden and catches errors before deployment.