zhongwei/gh-martybonacci-specswarm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-martybonacci-specswarm/commands/validate.md
Zhongwei Li 7e16d8a2a1 Initial commit
2025-11-30 08:39:24 +08:00

10 KiB
Raw Permalink Blame History

description, args
description args
Run AI-powered interaction flow validation for any software type (webapp, Android app, REST API, desktop GUI)
name description required
project_path Path to project to validate (defaults to current directory) false
name description required
--session-id Optional session ID for orchestration integration false
name description required
--type Override detected type (webapp|android|rest-api|desktop-gui) false
name description required
--flows Path to custom flows JSON file false
name description required
--url Override base URL for webapp (default http://localhost:5173) false

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.

Reference in New Issue View Git Blame Copy Permalink