qa360 2.1.7 → 2.2.0

package/docs/readiness-ci.md

@@ -0,0 +1,654 @@
+# QA360 Readiness CI - Guide d'Intégration
+
+Ce guide détaille l'utilisation du système de readiness QA360 pour les pipelines CI/CD, permettant des checks rapides et des conditions de fail-fast.
+
+## 🎯 Objectifs Readiness
+
+- **Validation rapide** : Vérifier l'état du système avant les tests (< 10 secondes)
+- **Fail-fast** : Échouer rapidement si l'environnement n'est pas prêt
+- **Feedback actionnable** : Fournir des solutions concrètes aux problèmes
+- **Intégration native** : Support pour tous les systèmes CI/CD majeurs
+
+## 🚀 Utilisation Basique
+
+### Check de readiness simple
+
+```bash
+# Check basique avec exit code
+qa360 serve --readiness-check
+
+# Exit codes:
+# 0 = Ready (tous les checks passent)
+# 1 = Not ready (au moins un problème critique)
+```
+
+### Avec timeout et retry
+
+```bash
+# Avec timeout de 30 secondes
+timeout 30 qa360 serve --readiness-check
+
+# Avec retry (3 tentatives)
+for i in {1..3}; do
+  qa360 serve --readiness-check && break
+  echo "Attempt $i failed, retrying..."
+  sleep 5
+done
+```
+
+## 🔍 Checks Effectués
+
+### Checks critiques (bloquants)
+
+| Check | Description | Code erreur | Solution |
+|-------|-------------|-------------|----------|
+| **tmp_writable** | Répertoire temporaire accessible | HLT001 | Vérifier permissions `/tmp` |
+| **config_access** | Accès au répertoire `.qa360` | HLT002 | Créer `.qa360/` ou permissions |
+| **disk_space** | Espace disque suffisant (>100MB) | HLT003 | Libérer de l'espace disque |
+
+### Checks informatifs (non-bloquants)
+
+| Check | Description | Impact | Recommandation |
+|-------|-------------|--------|----------------|
+| **playwright** | Playwright installé | Tests UI | `qa360 doctor --fix tools=playwright` |
+| **k6** | k6 installé | Tests performance | `qa360 doctor --fix tools=k6` |
+| **zap** | ZAP installé | Tests sécurité | `qa360 doctor --fix tools=zap` |
+| **secrets** | Fichier secrets présent | Tests auth | `qa360 secrets add API_TOKEN` |
+
+## 📋 Exemples CI/CD
+
+### GitHub Actions
+
+#### Exemple basique
+
+```yaml
+name: QA360 Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          
+      - name: Install QA360
+        run: npm install -g @qa360/cli
+        
+      - name: QA360 Readiness Check
+        run: qa360 serve --readiness-check
+        
+      - name: Run QA360 Tests
+        if: success()
+        run: qa360 run pack.yml
+```
+
+#### Exemple avancé avec retry et cache
+
+```yaml
+name: QA360 Advanced CI
+on: [push, pull_request]
+
+jobs:
+  readiness:
+    runs-on: ubuntu-latest
+    outputs:
+      ready: ${{ steps.check.outputs.ready }}
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Cache QA360 Dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.qa360
+            ~/.cache/ms-playwright
+          key: qa360-${{ runner.os }}-${{ hashFiles('pack.yml') }}
+          
+      - name: Install QA360
+        run: npm install -g @qa360/cli
+        
+      - name: QA360 Doctor Auto-fix
+        run: qa360 doctor --fix
+        
+      - name: QA360 Readiness Check with Retry
+        id: check
+        run: |
+          for i in {1..3}; do
+            if qa360 serve --readiness-check; then
+              echo "ready=true" >> $GITHUB_OUTPUT
+              exit 0
+            fi
+            echo "Attempt $i failed, retrying in 10s..."
+            sleep 10
+          done
+          echo "ready=false" >> $GITHUB_OUTPUT
+          exit 1
+          
+  test:
+    needs: readiness
+    if: needs.readiness.outputs.ready == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        pack: [api-tests, ui-tests, perf-tests]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run QA360 Pack
+        run: qa360 run packs/${{ matrix.pack }}.yml
+```
+
+### GitLab CI
+
+#### Pipeline avec stages
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - readiness
+  - test
+  - report
+
+variables:
+  QA360_VERSION: "latest"
+
+.qa360_base: &qa360_base
+  before_script:
+    - npm install -g @qa360/cli@$QA360_VERSION
+    - qa360 doctor --fix
+
+readiness_check:
+  <<: *qa360_base
+  stage: readiness
+  script:
+    - qa360 serve --readiness-check
+  retry:
+    max: 2
+    when: script_failure
+  only:
+    - merge_requests
+    - main
+
+api_tests:
+  <<: *qa360_base
+  stage: test
+  script:
+    - qa360 run packs/api.yml
+  dependencies:
+    - readiness_check
+  artifacts:
+    reports:
+      junit: qa360-api-results.xml
+    paths:
+      - qa360-api-report.html
+    expire_in: 1 week
+
+ui_tests:
+  <<: *qa360_base
+  stage: test
+  script:
+    - qa360 run packs/ui.yml
+  dependencies:
+    - readiness_check
+  artifacts:
+    paths:
+      - qa360-ui-report.html
+      - screenshots/
+    expire_in: 1 week
+
+consolidated_report:
+  stage: report
+  script:
+    - qa360 report --consolidate
+  dependencies:
+    - api_tests
+    - ui_tests
+  artifacts:
+    paths:
+      - qa360-consolidated-report.html
+```
+
+### Jenkins Pipeline
+
+#### Declarative Pipeline
+
+```groovy
+pipeline {
+    agent any
+    
+    environment {
+        QA360_VERSION = 'latest'
+    }
+    
+    stages {
+        stage('Setup') {
+            steps {
+                sh 'npm install -g @qa360/cli@${QA360_VERSION}'
+                sh 'qa360 doctor --fix'
+            }
+        }
+        
+        stage('Readiness') {
+            steps {
+                retry(3) {
+                    sh 'qa360 serve --readiness-check'
+                }
+            }
+            post {
+                failure {
+                    sh 'qa360 serve --readiness-check || qa360 doctor'
+                }
+            }
+        }
+        
+        stage('Tests') {
+            parallel {
+                stage('API Tests') {
+                    steps {
+                        sh 'qa360 run packs/api.yml'
+                    }
+                    post {
+                        always {
+                            archiveArtifacts 'qa360-api-report.html'
+                        }
+                    }
+                }
+                
+                stage('UI Tests') {
+                    steps {
+                        sh 'qa360 run packs/ui.yml'
+                    }
+                    post {
+                        always {
+                            archiveArtifacts 'qa360-ui-report.html'
+                        }
+                    }
+                }
+            }
+        }
+    }
+    
+    post {
+        always {
+            sh 'qa360 report --consolidate'
+            archiveArtifacts 'qa360-consolidated-report.html'
+        }
+        failure {
+            emailext (
+                subject: "QA360 Tests Failed - ${env.JOB_NAME} #${env.BUILD_NUMBER}",
+                body: "QA360 tests failed. Check the console output and reports.",
+                to: "${env.CHANGE_AUTHOR_EMAIL}"
+            )
+        }
+    }
+}
+```
+
+### Azure DevOps
+
+```yaml
+# azure-pipelines.yml
+trigger:
+  - main
+  - develop
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+variables:
+  qa360Version: 'latest'
+
+stages:
+- stage: Readiness
+  displayName: 'QA360 Readiness Check'
+  jobs:
+  - job: ReadinessCheck
+    displayName: 'Check System Readiness'
+    steps:
+    - task: NodeTool@0
+      inputs:
+        versionSpec: '18.x'
+      displayName: 'Install Node.js'
+      
+    - script: |
+        npm install -g @qa360/cli@$(qa360Version)
+        qa360 doctor --fix
+      displayName: 'Install and Setup QA360'
+      
+    - script: |
+        qa360 serve --readiness-check
+      displayName: 'QA360 Readiness Check'
+      retryCountOnTaskFailure: 2
+
+- stage: Test
+  displayName: 'QA360 Tests'
+  dependsOn: Readiness
+  condition: succeeded()
+  jobs:
+  - job: APITests
+    displayName: 'API Tests'
+    steps:
+    - script: qa360 run packs/api.yml
+      displayName: 'Run API Tests'
+    - task: PublishTestResults@2
+      inputs:
+        testResultsFormat: 'JUnit'
+        testResultsFiles: 'qa360-api-results.xml'
+        
+  - job: UITests
+    displayName: 'UI Tests'
+    steps:
+    - script: qa360 run packs/ui.yml
+      displayName: 'Run UI Tests'
+    - task: PublishHtmlReport@1
+      inputs:
+        reportDir: '.'
+        indexFile: 'qa360-ui-report.html'
+```
+
+## 🐳 Docker et Containers
+
+### Dockerfile avec readiness
+
+```dockerfile
+FROM node:18-alpine
+
+# Install QA360
+RUN npm install -g @qa360/cli
+
+# Setup working directory
+WORKDIR /app
+COPY pack.yml .
+
+# Health check using readiness
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD qa360 serve --readiness-check || exit 1
+
+# Auto-fix on startup
+RUN qa360 doctor --fix
+
+CMD ["qa360", "serve", "--host", "0.0.0.0"]
+```
+
+### Docker Compose avec services
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+
+services:
+  qa360:
+    build: .
+    ports:
+      - "4060:4060"
+    environment:
+      - QA360_CONFIG_DIR=/app/.qa360
+    volumes:
+      - ./packs:/app/packs
+      - qa360_cache:/app/.qa360
+    healthcheck:
+      test: ["CMD", "qa360", "serve", "--readiness-check"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+      
+  prometheus:
+    image: prom/prometheus:latest
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml
+    depends_on:
+      qa360:
+        condition: service_healthy
+
+volumes:
+  qa360_cache:
+```
+
+### Kubernetes avec readiness probe
+
+```yaml
+# k8s-deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: qa360
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: qa360
+  template:
+    metadata:
+      labels:
+        app: qa360
+    spec:
+      containers:
+      - name: qa360
+        image: qa360:latest
+        ports:
+        - containerPort: 4060
+        readinessProbe:
+          exec:
+            command:
+            - qa360
+            - serve
+            - --readiness-check
+          initialDelaySeconds: 10
+          periodSeconds: 30
+          timeoutSeconds: 10
+          failureThreshold: 3
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 4060
+          initialDelaySeconds: 30
+          periodSeconds: 60
+          timeoutSeconds: 5
+          failureThreshold: 3
+        env:
+        - name: QA360_SERVE_HOST
+          value: "0.0.0.0"
+        - name: QA360_SERVE_PORT
+          value: "4060"
+```
+
+## 🔧 Configuration Avancée
+
+### Variables d'environnement
+
+```bash
+# Timeouts personnalisés
+export QA360_READINESS_TIMEOUT=30
+export QA360_TOOL_CHECK_TIMEOUT=10
+
+# Seuils personnalisés
+export QA360_MIN_DISK_MB=500
+export QA360_MAX_LOAD_AVERAGE=2.0
+
+# Modes de fonctionnement
+export QA360_READINESS_MODE=strict  # strict|lenient
+export QA360_FAIL_ON_WARNINGS=false
+```
+
+### Configuration par fichier
+
+```yaml
+# .qa360/readiness.yml
+checks:
+  disk:
+    min_free_mb: 1000
+    paths:
+      - /tmp
+      - /var/tmp
+      
+  tools:
+    required:
+      - playwright
+    optional:
+      - k6
+      - zap
+    timeout_seconds: 15
+    
+  network:
+    endpoints:
+      - https://registry.npmjs.org
+      - https://github.com
+    timeout_seconds: 5
+    
+timeouts:
+  global: 60
+  per_check: 10
+  
+mode: strict  # strict|lenient
+fail_on_warnings: false
+```
+
+## 📊 Monitoring et Alertes
+
+### Métriques Prometheus
+
+```yaml
+# prometheus-rules.yml
+groups:
+  - name: qa360_readiness
+    rules:
+      - alert: QA360ReadinessFailure
+        expr: qa360_readiness_check_failures_total > 3
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "QA360 readiness checks failing repeatedly"
+          description: "QA360 readiness has failed {{ $value }} times in the last 5 minutes"
+          
+      - alert: QA360ToolsMissing
+        expr: qa360_tools_missing_count > 0
+        for: 1m
+        labels:
+          severity: info
+        annotations:
+          summary: "QA360 tools missing"
+          description: "{{ $value }} QA360 tools are missing or not configured"
+```
+
+### Dashboard Grafana
+
+```json
+{
+  "dashboard": {
+    "title": "QA360 Readiness",
+    "panels": [
+      {
+        "title": "Readiness Status",
+        "type": "stat",
+        "targets": [
+          {
+            "expr": "qa360_readiness_status",
+            "legendFormat": "Ready"
+          }
+        ]
+      },
+      {
+        "title": "Check Duration",
+        "type": "graph",
+        "targets": [
+          {
+            "expr": "qa360_readiness_check_duration_seconds",
+            "legendFormat": "Duration"
+          }
+        ]
+      },
+      {
+        "title": "Tools Status",
+        "type": "table",
+        "targets": [
+          {
+            "expr": "qa360_tools_status",
+            "legendFormat": "{{ tool }}"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## 🚨 Troubleshooting
+
+### Problèmes courants
+
+**Readiness check échoue systématiquement :**
+```bash
+# Debug détaillé
+qa360 serve --readiness-check --verbose
+
+# Diagnostic complet
+qa360 doctor
+
+# Auto-fix
+qa360 doctor --fix
+```
+
+**Timeouts en CI :**
+```bash
+# Augmenter les timeouts
+timeout 60 qa360 serve --readiness-check
+
+# Mode lenient
+QA360_READINESS_MODE=lenient qa360 serve --readiness-check
+```
+
+**Outils manquants en CI :**
+```bash
+# Installation automatique
+qa360 doctor --fix --install-missing
+
+# Mode Docker fallback
+qa360 run --docker pack.yml
+```
+
+### Logs de debug
+
+```bash
+# Logs structurés JSON
+qa360 serve --readiness-check --verbose 2>&1 | jq .
+
+# Filtrer les erreurs
+qa360 serve --readiness-check 2>&1 | grep -E "(ERROR|WARN|HLT[0-9]+)"
+
+# Sauvegarder les logs
+qa360 serve --readiness-check --verbose > readiness.log 2>&1
+```
+
+## 🎯 Bonnes Pratiques
+
+### Intégration CI/CD
+
+1. **Toujours faire le readiness check** avant les tests
+2. **Utiliser des retry** avec backoff pour la robustesse
+3. **Cacher les dépendances** QA360 entre les builds
+4. **Configurer des timeouts** appropriés (30-60s)
+5. **Archiver les logs** de readiness pour le debug
+
+### Performance
+
+1. **Paralléliser** les checks non-dépendants
+2. **Utiliser le cache** pour les outils installés
+3. **Optimiser les images Docker** avec layers
+4. **Monitorer les métriques** de durée des checks
+
+### Sécurité
+
+1. **Valider les permissions** avant les tests
+2. **Isoler les environnements** de test
+3. **Utiliser des secrets** pour l'authentification
+4. **Auditer les logs** de readiness
+
+Le système de readiness QA360 garantit des pipelines CI/CD robustes avec des conditions de fail-fast intelligentes et un feedback actionnable pour tous les environnements.

package/docs/rfc/README.md

@@ -0,0 +1,20 @@
+# QA360 RFC Documents
+
+This directory contains official Request for Comments (RFC) documents that define QA360's technical specifications.
+
+## Active RFCs
+
+| RFC | Title | Status |
+|-----|-------|--------|
+| [proof-bundle-v1.md](./proof-bundle-v1.md) | Proof Bundle Specification v1 | ✅ Active |
+
+## Archived Documents
+
+Phase completion reports and intermediate status documents have been moved to `/docs/archive/`.
+
+## Contributing
+
+To propose a new RFC:
+1. Create a new file `rfc-XXXX-title.md` 
+2. Follow the template structure
+3. Submit a PR for review