qa360 2.1.7 → 2.2.0

package/QUICK_START.md

@@ -0,0 +1,191 @@
+# 🚀 QA360 - Guide de Démarrage Simple
+
+Transformez vos tests en preuves vérifiables en 5 minutes.
+
+> **🚀 Beta Testing (15 Jan - 26 Fév 2025)** - Rejoignez le programme ! [Voir le plan beta](./docs/BETA_TESTING.md)
+
+---
+
+## ⚡ Installation (2 minutes)
+
+### Windows
+
+1. Ouvrez **PowerShell** en administrateur
+2. Installez QA360 :
+
+```powershell
+npm install -g xyqotech/qa360#develop
+```
+
+### Mac / Linux
+
+1. Ouvrez le **Terminal**
+2. Installez QA360 :
+
+```bash
+npm install -g xyqotech/qa360#develop
+```
+
+### Vérifier l'installation
+
+```bash
+qa360 --version
+```
+
+Vous devriez voir : `v1.4.5` ou plus.
+
+> **Problème ?** Lancez `qa360 doctor --fix` pour un diagnostic automatique
+
+---
+
+## 🧪 Votre Premier Test (3 minutes)
+
+### Étape 1 : Créer un dossier
+
+```bash
+mkdir mon-test
+cd mon-test
+```
+
+### Étape 2 : Créer votre fichier de test
+
+Créez un fichier `test.yml` :
+
+```yaml
+name: "Mon Premier Test"
+description: "Test simple d'API"
+
+gates:
+  - api_health
+
+targets:
+  api:
+    baseUrl: "https://httpbin.org"
+    smoke:
+      - "GET /status/200 -> 200"
+      - "GET /get -> 200"
+```
+
+### Étape 3 : Lancer le test
+
+```bash
+qa360 run test.yml
+```
+
+### Résultat attendu
+
+```
+✅ API Health : PASSED (2/2)
+✅ Preuve générée : .qa360/runs/xxxxx-proof.json
+```
+
+---
+
+## 🎓 Ce que vous venez de faire
+
+1. **Tester une API** - Vous avez vérifié que httpbin.org fonctionne
+2. **Générer une preuve** - QA360 a signé cryptographiquement les résultats
+3. **Sauvegarder l'historique** - Les résultats sont stockés localement
+
+---
+
+## 🔐 Vérifier la Preuve
+
+```bash
+qa360 verify .qa360/runs/<dernier>-proof.json
+```
+
+Résultat :
+
+```
+✅ Preuve VALIDE
+✅ Signature : Ed25519
+✅ Date : 2025-01-03
+```
+
+---
+
+## 📋 Commandes Utiles
+
+| Commande | Ce que ça fait |
+|----------|---------------|
+| `qa360 run <fichier.yml>` | Lance les tests |
+| `qa360 verify <preuve.json>` | Vérifie une preuve |
+| `qa360 history list` | Voir les tests passés |
+| `qa360 doctor` | Diagnostic système |
+| `qa360 examples list` | Voir les exemples |
+| `qa360 init --beginner` | Créer un test facilement |
+
+---
+
+## 📁 Exemples Disponibles
+
+```bash
+# Voir tous les exemples
+qa360 examples list
+
+# Copier un exemple
+qa360 examples copy api-basic
+qa360 examples copy fullstack
+qa360 examples copy perf-test
+
+# Lancer un exemple
+qa360 run api-basic/qa360.yml
+```
+
+---
+
+## 🎯 Prochaines Étapes
+
+1. **Tester votre propre API** : Modifiez `baseUrl` dans le fichier `test.yml`
+2. **Explorer les exemples** : `qa360 examples list`
+3. **Créer des tests complexes** : Consultez le [Guide Utilisateur](./docs/USER_GUIDE.md)
+
+---
+
+## 🐛 Un Problème ?
+
+### Erreur : `command not found: qa360`
+
+```bash
+# Vérifiez que npm est dans le PATH
+npm config get prefix
+
+# Si besoin, ajoutez à votre PATH :
+# Windows : $env:Path += ";C:\Users\<votre-user>\AppData\Roaming\npm"
+# Mac/Linux : export PATH="$PATH:$(npm config get prefix)/bin"
+```
+
+### Erreur : `EACCES` (permission refusée)
+
+```bash
+# Mac/Linux : utilisez sudo
+sudo npm install -g xyqotech/qa360#develop
+
+# Ou corrigez les permissions npm
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+export PATH=~/.npm-global/bin:$PATH
+```
+
+### Autre erreur
+
+```bash
+qa360 doctor --fix > diagnostic.txt
+```
+
+Envoyez `diagnostic.txt` sur :
+- Discord : https://discord.gg/qa360
+- GitHub : https://github.com/xyqotech/qa360/issues
+
+---
+
+## 📚 En Savoir Plus
+
+- [Programme Beta Test](./docs/BETA_TESTING.md) - Participez au beta !
+- [Guide Utilisateur Complet](./docs/USER_GUIDE.md) - Toutes les fonctionnalités
+- [Documentation Technique](./docs/ARCHITECTURE.md) - Comment ça marche
+
+---
+
+**C'est tout !** Vous savez utiliser QA360 en 5 minutes 🚀

package/README.md

@@ -1,222 +1,250 @@
-# qa360
+# QA360 Proof CLI
 
-**QA360 Proof CLI** - Quality as Cryptographic Proof
+**Quality as Cryptographic Proof**
 
-[![Version](https://img.shields.io/npm/v/qa360.svg)](https://www.npmjs.com/package/qa360)
-[![License](https://img.shields.io/npm/l/qa360.svg)](https://github.com/xyqotech/qa360/blob/main/LICENSE)
-[![Tests](https://img.shields.io/badge/tests-282%20passing-success)](https://github.com/xyqotech/qa360)
-[![Coverage](https://img.shields.io/badge/coverage-55%25-brightgreen)](https://github.com/xyqotech/qa360)
+> **🚀 BETA TESTING (Jan 15 - Feb 26, 2025)** - Join the beta program! See [BETA_TESTING.md](./docs/BETA_TESTING.md)
 
-> **Official package** published by [xyqotech](https://github.com/xyqotech) with npm provenance signatures
+![Version](https://img.shields.io/badge/version-2.0.0%20%5Bstable%5D-brightgreen)
+![Tests](https://img.shields.io/badge/tests-2177%20passing-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-55%25-yellow)
+![CI](https://img.shields.io/badge/CI-passing-brightgreen)
+![Platform](https://img.shields.io/badge/platform-Win%20%7C%20macOS%20%7C%20Linux-lightgrey)
+![License](https://img.shields.io/badge/license-MIT-green)
 
-## Installation
+> **Versioning**: QA360 uses Node.js-style versioning (Major.Minor.Patch), e.g., `v2.0.0` (similar to Node.js `v18.20.5`)
 
-### Option 1: Global installation (recommended for regular use)
+Verify cryptographically signed proof bundles locally, without network dependencies.
+
+## 🚀 Install
+
+### Installation (npm)
 
 ```bash
-# macOS: use sudo if you get EACCES permission errors
-sudo npm install -g qa360
-
-# Or configure npm prefix (one-time setup)
-mkdir -p ~/.npm-global
-npm config set prefix '~/.npm-global'
-echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
-source ~/.zshrc
+# Using npm
 npm install -g qa360
-```
 
-### Option 2: Direct usage with npx (no installation needed)
+# Using pnpm
+pnpm add -g qa360
 
-```bash
-# Run directly without installing
-npx qa360@latest run test.yml
-npx qa360@latest verify proof.json
-npx qa360@latest doctor
+# Using yarn
+yarn global add qa360
 ```
 
-**Note**: On first run, Playwright browsers will be automatically downloaded (~100MB). This happens only once.
+> **Note:** Join the [beta testing program](./docs/BETA_TESTING.md) (Jan 15 - Feb 26, 2025) and help improve QA360!
 
-## Quick Start
+## ⚡ Quick Start
 
-### 1. Generate a test pack
+**New to QA360?** → See the [**Quick Start Guide**](./QUICK_START.md) for a 5-minute tutorial!
 
 ```bash
-# Option 1: Interactive mode (recommended for first-time users)
-qa360 init
-
-# Option 2: Use a template directly
-qa360 init --template api-basic --yes
-
-# Option 3: Copy an example
-qa360 examples copy api-basic
-qa360 examples list              # See all available examples
-```
+# Run your first test
+qa360 run test-pack.yml
 
-### 2. Run tests
-
-```bash
-qa360 run
-```
+# View test history
+qa360 history list
 
-### 3. Verify proof
+# Verify cryptographic proof
+qa360 verify .qa360/runs/<run-id>-proof.json
 
-```bash
-qa360 verify .qa360/runs/
+# Check system readiness
+qa360 doctor
 ```
 
-## Usage
+## 🛠️ Core Commands
 
 ```bash
-# Generate test pack (interactive)
-qa360 init
+# Execute quality gates
+qa360 run pack.yaml
 
-# Generate with template
-qa360 init --template api-basic
-qa360 init --template fullstack
-qa360 init --template security
-qa360 init --template complete
+# Verify proof signature
+qa360 verify .qa360/runs/proof.json
 
-# Examples commands
-qa360 examples list              # List all examples
-qa360 examples copy api-basic    # Copy example to qa360.yml
-qa360 examples show fullstack    # Preview example content
+# System diagnostics
+qa360 doctor --fix
 
-# System health check
-qa360 doctor
-
-# Run test pack
-qa360 run                    # Auto-detects qa360.yml
-qa360 run custom-pack.yml    # Use specific file
+# Start observability server
+qa360 serve --port 3600
+```
 
-# Verify proof bundle
-qa360 verify .qa360/runs/
-qa360 verify proof.json
+## ✨ Why QA360?
 
-# View run history
-qa360 history list
-qa360 history show <run-id>
+- **🔒 Local-first** - No network dependencies, 100% offline
+- **🔐 Cryptographic trust** - Ed25519 signatures, SHA-256 hashing
+- **🌍 Cross-OS verified** - Windows, macOS, Linux
+- **⚡ Zero friction** - Auto-generates keys, clear error messages
+- **
+- **🧠 AI-Native** - Local test generation with Ollama (100% free)
+- **🚀 Playwright Native** - 87% faster API tests, 80% less memory
+- **📦 Smart Caching** - LRU cache for HTTP responses, 96% faster cache hits
 
-# Export proof bundle
-qa360 history export <run-id> --bundle proof-bundle.zip
+## 🏗️ Architecture
 
-# Clean up old runs (garbage collection)
-qa360 history gc                    # Default: keep last 10 runs
-qa360 history gc --keep-last 20     # Keep last 20 runs
-qa360 history gc --dry-run          # Preview what would be deleted
+QA360 uses a clean monorepo architecture with unified packages and modular design.
 
-# Pin/unpin runs (pinned runs are never deleted by gc)
-qa360 history pin <run-id>
-qa360 history unpin <run-id>
+### Structure
 
-# With JSON output (CI-friendly)
-qa360 doctor --json
-qa360 verify proof.json --json
-qa360 history list --json
+```
+QA360/
+├── cli/              # CLI interface (@qa360/cli v1.4.5)
+│   └── src/commands/ # 22 CLI commands
+├── core/             # Proof generation engine (qa360-core v1.0.1)
+│   └── src/adapters/ # 7 test framework adapters
+│       ├── playwright-native-api.ts   # API testing (87% faster)
+│       ├── playwright-ui.ts           # UI/E2E + A11y
+│       ├── k6-perf.ts                # Performance testing
+│       ├── semgrep-sast.ts            # SAST analysis
+│       ├── gitleaks-secrets.ts        # Secret scanning
+│       ├── osv-deps.ts                # Dependency vulnerabilities
+│       └── zap-dast.ts                # DAST security scanning
+├── packages/mcp/     # MCP server (@qa360/mcp v1.0.0, 23 tools)
+├── docs/             # 54 documentation files
+├── examples/         # 15 example packs
+└── tests/            # 100 test files (2177 tests passing)
 ```
 
-## Available Templates
-
-| Template | Description | Gates |
-|----------|-------------|-------|
-| **api-basic** | Simple API smoke tests | api_smoke |
-| **ui-basic** | Basic UI/E2E tests | ui |
-| **fullstack** | API + UI + Performance | api_smoke, ui, perf |
-| **security** | Security testing suite | sast, dast, secrets, deps |
-| **accessibility** | Accessibility testing | ui, a11y |
-| **complete** | All quality gates | All (8 gates) |
+### Recent Updates (Phase 1 Complete - January 2025)
+
+**January 3, 2025** - F8 Smart Retry Module (Vision 2.0):
+- ✅ **Smart Retry Engine**: 6 retry strategies (NONE, FIXED, LINEAR, EXPONENTIAL, ADAPTIVE, INTELLIGENT)
+- ✅ **Flakiness-Aware Retry**: Integrates with flakiness scoring for intelligent retry decisions
+- ✅ **Pattern-Based Retry**: Adjusts strategy based on failure patterns (timing, race conditions, selectors)
+- ✅ **Non-Retriable Error Detection**: Automatically identifies unrecoverable errors
+- ✅ **Jitter Support**: Avoids thundering herd problem with configurable jitter
+- 📊 **Tests**: 48 passing tests
+
+**January 2, 2025** - Phase 1 Performance Optimizations:
+- ✅ **Playwright Native API**: Zero-overhead HTTP testing (87% faster, 80% less memory)
+- ✅ **LRU Cache**: Intelligent HTTP response caching (96% faster cache hits)
+- ✅ **Watch Mode**: Continuous testing with file monitoring
+- ✅ **Benchmark Mode**: Performance testing with detailed statistics
+- 📊 **Performance**: See [`docs/PHASE1_PERFORMANCE.md`](./docs/PHASE1_PERFORMANCE.md)
+
+**December 23, 2024** - Major architecture improvements:
+- ✅ **Unified MCP Package**: Merged 2 MCP packages into 1 (`@qa360/mcp v1.2.0`)
+- ✅ **Removed Duplicates**: Deleted 4 empty packages + eliminated 10,503 duplicate lines
+- ✅ **Clean Structure**: Moved `/api` to `examples/future-api/` (Phase 3)
+- ✅ **Build Performance**: +50% faster builds after consolidation
+
+**See:** [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for complete documentation.
+
+## 🧠 AI Integration with Ollama
+
+QA360 is an **AI-native testing platform** using [Ollama](https://ollama.com/) for 100% free, local LLM inference.
+
+### Phase 4 Complete ✅ - AI Test Generation
+
+**January 2, 2025** - AI Test Generation Module:
+- ✅ **SourceAnalyzer**: Analyze TypeScript, JavaScript, Python, and Go source code
+  - Extract functions, classes, imports, and complexity metrics
+  - Generate test suggestions (unit/integration/e2e)
+  - Generate API specs from Express/Fastify handlers
+- ✅ **PackGenerator**: Convert AI-generated specs to QA360 pack YAML (v2 format)
+- ✅ **CodeGenerator**: Generate test code using LLM providers (Ollama, DeepSeek, etc.)
+- ✅ **Real Provider Integration**: Tests for Ollama and DeepSeek providers
+- 📊 **Test Coverage**: 160 generation tests + 187 real-world tests
+
+```typescript
+// Example: Analyze source code and generate tests
+import { SourceAnalyzer, PackGenerator } from 'qa360/core/generation';
+
+const analyzer = new SourceAnalyzer();
+const analysis = analyzer.analyzeFile('./src/userService.ts');
+
+// Generate test suggestions
+const suggestions = analyzer.generateSuggestions(analysis);
+// → [{ type: 'unit', priority: 'high', description: 'Test UserService.createUser', ... }]
+
+// Generate API spec from handlers
+const apiSpec = analyzer.generateApiSpec(analysis);
+// → { type: 'api', baseUrl: 'https://...', endpoints: [...] }
+
+// Convert to pack YAML
+const packGenerator = new PackGenerator();
+const packYaml = packGenerator.generateFromApiSpec(apiSpec);
+```
 
-## Example Files
+### Phase 1-3 Complete ✅
 
-Pre-made examples are included in the package:
+| Component | Status | Tests |
+|-----------|--------|-------|
+| OllamaProvider | ✅ Complete | 41 tests |
+| TestDiscoverer | ✅ Complete | 55 tests |
+| PackConfig | ✅ Complete | - |
+| Auth Module (9 providers) | ✅ Complete | 92 tests |
+| Pack Validation | ✅ Complete | 210+ tests |
+| **Phase 4 Generation** | ✅ Complete | **160 tests** |
 
 ```bash
-# List examples
-ls examples/
+# Test Ollama connection
+qa360 ollama test
 
-# Copy an example
-cp examples/api-basic.yml qa360.yml
+# List installed models
+qa360 ollama list
 
-# Run example directly
-qa360 run examples/api-basic.yml
-```
+# Generate tests (preview)
+qa360 ollama generate "create API smoke tests for /users"
 
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `init` | Generate test pack interactively |
-| `examples` | Manage example templates (list, copy, show) |
-| `run` | Execute test pack |
-| `verify` | Verify cryptographic proof bundles |
-| `doctor` | Check system health, auto-fix issues |
-| `history` | View run history and results |
-| `report` | Generate reports |
-| `secrets` | Manage encrypted secrets |
-| `pack` | Pack validation and linting |
-
-### History Commands
-
-The `history` command provides comprehensive management of test run history stored in the Evidence Vault:
+# Configure Ollama
+qa360 ollama config
+```
 
-| Subcommand | Description | Example |
-|------------|-------------|---------|
-| `list` | List recent test runs | `qa360 history list --limit 20` |
-| `show <run-id>` | Show detailed run information | `qa360 history show abc123` |
-| `diff <id1> <id2>` | Compare two test runs | `qa360 history diff abc123 def456` |
-| `trend` | Show trust score trends | `qa360 history trend --window 30` |
-| `export <run-id>` | Export run as ZIP bundle | `qa360 history export abc123 --bundle proof.zip` |
-| `gc` | Garbage collect old runs | `qa360 history gc --keep-last 10` |
-| `pin <run-id>` | Pin run (protect from gc) | `qa360 history pin abc123` |
-| `unpin <run-id>` | Unpin run | `qa360 history unpin abc123` |
+**See:** [`docs/OLLAMA_REFACTORING_ROADMAP.md`](./docs/OLLAMA_REFACTORING_ROADMAP.md) for the complete 10-week roadmap.
 
-#### Export Bundle Contents
+## 📋 Development Phases
 
-When exporting a run with `qa360 history export <run-id> --bundle proof.zip`, the ZIP contains:
+QA360 Core is developed in structured phases:
 
-- `proof.json` - Cryptographically signed proof document
-- `report.pdf` - Human-readable PDF report (if generated)
-- `run.json` - Complete run details (gates, findings, artifacts)
-- `artifacts/` - All test artifacts (screenshots, logs, etc.)
-- `VERIFICATION.json` - Verification instructions and metadata
+### Core Platform
+- **Phase 0**: ✅ Initialization & Structure
+- **Phase 1**: ✅ Runner CLI "zero friction"
+- **Phase 2**: ✅ Pack configuration + encrypted secrets
+- **Phase 3**: ✅ Declarative hooks + Docker provisioning
+- **Phase 4**: ✅ OOTB Adapters (Playwright, k6, Semgrep, ZAP, etc.)
+- **Phase 5**: ✅ Health/Diag/Metrics endpoints
+- **Phase 6**: ✅ Evidence Vault + SQLite WAL history
+- **Phase 7**: ✅ Complete Proof Bundle
 
-#### Garbage Collection
+### AI Integration (Ollama)
+- **AI Phase 1**: ✅ Ollama Provider + TestDiscoverer
+- **AI Phase 2**: ✅ Auth Module (9 providers)
+- **AI Phase 3**: ✅ Pack Validation
+- **AI Phase 4**: ✅ AI Test Generation (SourceAnalyzer, PackGenerator, 160 tests)
+- **AI Phase 5**: ⏳ Integration & Polish (in progress)
 
-The `gc` command removes old test runs and orphaned artifacts to free disk space:
+### Future Roadmap
+- **Phase 8**: ✅ TUI & Dashboard (COMPLETE)
+- **Phase 9**: ⏳ Parallel CI → consolidated proof
 
-```bash
-# Preview what would be deleted (dry-run)
-qa360 history gc --dry-run
+## 🛠️ Technology Stack
 
-# Keep last 20 runs, delete older ones
-qa360 history gc --keep-last 20
+- **Runtime**: Node.js 18+ with TypeScript 5+
+- **Storage**: SQLite WAL for evidence vault
+- **Crypto**: Ed25519 signatures for proof verification
+- **AI**: Ollama for local LLM inference (100% free)
+- **PDF**: Puppeteer for report generation
+- **Testing**: Vitest for unit/integration tests
 
-# Default behavior (keeps last 10 unpinned runs)
-qa360 history gc
-```
+## 📚 Documentation
 
-**Important**: Pinned runs are NEVER deleted by garbage collection. Use `qa360 history pin <run-id>` to protect important runs.
+- [Quick Start Guide](./QUICK_START.md) - 5-minute tutorial
+- [User Guide](./docs/USER_GUIDE.md) - Complete documentation
+- [Beta Testing Plan](./docs/BETA_TESTING_PLAN.md) - User testing program
+- [Contributing Guide](./CONTRIBUTING.md)
+- [Changelog](./CHANGELOG.md)
+- [Code Owners](./CODEOWNERS)
 
-## Exit Codes
+## 🤝 Contributing
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | Verification failed |
-| 2 | File not found |
-| 3 | Invalid schema |
-| 4 | Missing key |
-| 5 | Internal error |
+QA360 Core aims to become the **global standard for portable software quality proof**.
 
-## Requirements
+Every contribution should advance this mission with **simplicity, auditability, and elegance**.
 
-- Node.js >= 18.0.0
-- npm or pnpm
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
 
-## Documentation
+## 📄 License
 
-- [Quick Start](https://github.com/xyqotech/qa360/blob/main/docs/quickstart-5min.md)
-- [Full Documentation](https://github.com/xyqotech/qa360/blob/main/docs/README.md)
+MIT License - see [LICENSE](./LICENSE) for details.
 
-## License
+---
 
-MIT
+**QA360 Core**: Making quality **executable, measurable, and legally provable**.

package/adapters/README.md

@@ -0,0 +1,46 @@
+# QA360 Adapters
+
+> **ℹ️ NOTE - This directory is reserved for future standalone adapter packages**
+>
+> All current adapters are implemented in **`core/src/adapters/`** and are part of the core package.
+>
+> See [README.md](../README.md) for available adapters.
+
+## Current Implementation
+
+All adapters are currently integrated in the `core` package:
+
+```bash
+core/src/adapters/
+├── playwright-native-api.ts  # API testing adapter
+├── playwright-ui.ts           # UI testing adapter
+├── playwright-native-api.ts  # Native API adapter (zero overhead)
+└── ... (more adapters planned)
+```
+
+## Future Architecture
+
+This directory is reserved for potential future standalone adapter packages that would be published separately:
+
+```bash
+# Future structure (if needed)
+adapters/
+├── playwright-adapter/  # Standalone Playwright adapter package
+├── cypress-adapter/      # Standalone Cypress adapter package
+└── vitest-adapter/       # Standalone Vitest adapter package
+```
+
+**Note**: No standalone adapter packages are planned at this time. All adapters remain in `core/src/adapters/` for better integration and simpler dependency management.
+
+## Available Adapters (in core)
+
+| Adapter | Status | Description |
+|---------|--------|-------------|
+| `playwright-api` | ✅ Implemented | API testing with Playwright |
+| `playwright-ui` | ✅ Implemented | UI testing with Playwright |
+| `playwright-native-api` | ✅ Implemented | Zero-overhead native API adapter |
+| `k6-perf` | ✅ Implemented | Performance testing with K6 |
+| `semgrep-sast` | ✅ Implemented | Static security analysis |
+| `gitleaks-secrets` | ✅ Implemented | Secret scanning |
+| `zap-dast` | ✅ Implemented | Dynamic security testing |
+| `osv-deps` | ✅ Implemented | Dependency vulnerability scanning |