Initial commit
This commit is contained in:
Zhongwei Li
314
commands/validate.md
Normal file
314
commands/validate.md
Normal file
@@ -0,0 +1,314 @@
|
||||
---
|
||||
description: Run AI-powered interaction flow validation for any software type (webapp, Android app, REST API, desktop GUI)
|
||||
args:
|
||||
- name: project_path
|
||||
description: Path to project to validate (defaults to current directory)
|
||||
required: false
|
||||
- name: --session-id
|
||||
description: Optional session ID for orchestration integration
|
||||
required: false
|
||||
- name: --type
|
||||
description: Override detected type (webapp|android|rest-api|desktop-gui)
|
||||
required: false
|
||||
- name: --flows
|
||||
description: Path to custom flows JSON file
|
||||
required: false
|
||||
- name: --url
|
||||
description: Override base URL for webapp (default http://localhost:5173)
|
||||
required: false
|
||||
---
|
||||
|
||||
# AI-Powered Feature Validation
|
||||
|
||||
Run comprehensive validation with intelligent flow generation, interactive error detection, and automatic project type detection.
|
||||
|
||||
## Initialize Validation
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
Block a user