qa360 2.2.20 → 2.3.1

package/README.md

@@ -1,329 +1,222 @@
-# QA360 Proof CLI
+# qa360
 
-**Quality as Cryptographic Proof**
+**QA360 Proof CLI** - Quality as Cryptographic Proof
 
-> **🚀 BETA TESTING (Jan 15 - Feb 26, 2025)** - Join the beta program! See [BETA_TESTING.md](./docs/BETA_TESTING.md)
+[![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)
 
-![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)
+> **Official package** published by [xyqotech](https://github.com/xyqotech) with npm provenance signatures
 
-> **Versioning**: QA360 uses Node.js-style versioning (Major.Minor.Patch), e.g., `v2.0.0` (similar to Node.js `v18.20.5`)
+## Installation
 
-Verify cryptographically signed proof bundles locally, without network dependencies.
-
-## 🚀 Install
-
-### Installation (npm)
+### Option 1: Global installation (recommended for regular use)
 
 ```bash
-# Using npm
+# 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
 npm install -g qa360
+```
 
-# Using pnpm
-pnpm add -g qa360
+### Option 2: Direct usage with npx (no installation needed)
 
-# Using yarn
-yarn global add qa360
+```bash
+# Run directly without installing
+npx qa360@latest run test.yml
+npx qa360@latest verify proof.json
+npx qa360@latest doctor
 ```
 
-> **Note:** Join the [beta testing program](./docs/BETA_TESTING.md) (Jan 15 - Feb 26, 2025) and help improve QA360!
+**Note**: On first run, Playwright browsers will be automatically downloaded (~100MB). This happens only once.
 
-## ⚡ Quick Start
+## Quick Start
 
-**New to QA360?** → See the [**Quick Start Guide**](./QUICK_START.md) for a 5-minute tutorial!
+### 1. Generate a test pack
 
 ```bash
-# Run your first test
-qa360 run test-pack.yml
+# Option 1: Interactive mode (recommended for first-time users)
+qa360 init
 
-# View test history
-qa360 history list
-
-# Verify cryptographic proof
-qa360 verify .qa360/runs/<run-id>-proof.json
+# Option 2: Use a template directly
+qa360 init --template api-basic --yes
 
-# Check system readiness
-qa360 doctor
+# Option 3: Copy an example
+qa360 examples copy api-basic
+qa360 examples list              # See all available examples
 ```
 
-## 🛠️ Core Commands
+### 2. Run tests
 
 ```bash
-# Execute quality gates
-qa360 run pack.yaml
-
-# Verify proof signature
-qa360 verify .qa360/runs/proof.json
+qa360 run
+```
 
-# System diagnostics
-qa360 doctor --fix
+### 3. Verify proof
 
-# Start observability server
-qa360 serve --port 3600
+```bash
+qa360 verify .qa360/runs/
 ```
 
-## ✨ Why QA360?
-
-- **🔒 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
+## Usage
 
-## 🏗️ Architecture
+```bash
+# Generate test pack (interactive)
+qa360 init
 
-QA360 uses a clean monorepo architecture with unified packages and modular design.
+# Generate with template
+qa360 init --template api-basic
+qa360 init --template fullstack
+qa360 init --template security
+qa360 init --template complete
 
-### Structure
+# 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
 
-```
-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)
-```
+# System health check
+qa360 doctor
 
-### 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);
-```
+# Run test pack
+qa360 run                    # Auto-detects qa360.yml
+qa360 run custom-pack.yml    # Use specific file
 
-### Phase 1-3 Complete ✅
+# Verify proof bundle
+qa360 verify .qa360/runs/
+qa360 verify proof.json
 
-| 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** |
+# View run history
+qa360 history list
+qa360 history show <run-id>
 
-```bash
-# Test Ollama connection
-qa360 ollama test
+# Export proof bundle
+qa360 history export <run-id> --bundle proof-bundle.zip
 
-# List installed models
-qa360 ollama list
+# 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
 
-# Generate tests (preview)
-qa360 ollama generate "create API smoke tests for /users"
+# Pin/unpin runs (pinned runs are never deleted by gc)
+qa360 history pin <run-id>
+qa360 history unpin <run-id>
 
-# Configure Ollama
-qa360 ollama config
+# With JSON output (CI-friendly)
+qa360 doctor --json
+qa360 verify proof.json --json
+qa360 history list --json
 ```
 
-**See:** [`docs/OLLAMA_REFACTORING_ROADMAP.md`](./docs/OLLAMA_REFACTORING_ROADMAP.md) for the complete 10-week roadmap.
-
-## 📋 Development Phases
-
-QA360 Core is developed in structured phases:
-
-### 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
+## Available Templates
 
-### 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)
+| 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) |
 
-### Future Roadmap
-- **Phase 8**: ✅ TUI & Dashboard (COMPLETE)
-- **Phase 9**: ⏳ Parallel CI → consolidated proof
+## Example Files
 
-## 🚢 npm Publication Workflow (CRITICAL)
+Pre-made examples are included in the package:
 
-> **⚠️ WARNING: Publishing broken packages damages user trust permanently.**
+```bash
+# List examples
+ls examples/
 
-### Mandatory Pre-Publication Checklist
+# Copy an example
+cp examples/api-basic.yml qa360.yml
 
-**NEVER skip these steps - versions 2.2.4 and 2.2.5 were broken due to skipping these:**
+# Run example directly
+qa360 run examples/api-basic.yml
+```
 
-1. ✅ **CI MUST be green** on both `develop` AND `main`
-2. ✅ **Run bundle script**: `cd cli && bash scripts/bundle-for-npm.sh`
-3. ✅ **Test with npm pack**: `npm pack && tar -tzf qa360-*.tgz | grep "cli/dist/core/index.js"`
-4. ✅ **Test installation**: `cd /tmp && npm install -g ./qa360-*.tgz && qa360 --version`
-5. ✅ **Get EXPLICIT authorization** from maintainer before publishing
-6. ✅ **Publish from MAIN branch only** - NEVER from `develop`
+## Commands
 
-### The Fatal Mistakes (DO NOT REPEAT)
+| 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 |
 
-| Version | Mistake | Result |
-|---------|---------|--------|
-| **2.2.4** | Published without CI check | CI was failing - broken package |
-| **2.2.5** | Published without bundle script | Missing `cli/dist/core/` - completely broken |
-| **2.2.6** | Followed full checklist | ✅ Working package |
+### History Commands
 
-### Correct Publication Workflow
+The `history` command provides comprehensive management of test run history stored in the Evidence Vault:
 
-```bash
-# 1. Verify CI is green
-gh run list --branch develop --limit 1
-gh run list --branch main --limit 1
-
-# 2. Merge develop to main
-git checkout main
-git merge develop --no-ff
-git push origin main
-
-# 3. Wait for CI to pass on main
-gh run watch --branch main
-
-# 4. CREATE THE BUNDLE (THIS IS CRITICAL)
-cd cli
-bash scripts/bundle-for-npm.sh
-cd ..
-
-# 5. Verify bundle was created
-ls -la cli/dist/core/index.js  # Must exist
-grep "from '../core/index.js'" cli/dist/commands/ai.js  # Must show this, NOT qa360-core
-
-# 6. Test the package locally
-npm pack
-tar -tzf qa360-*.tgz | grep "cli/dist/core/index.js"  # Must exist
-cd /tmp && npm install -g /path/to/qa360-*.tgz && qa360 --version
-
-# 7. ONLY AFTER ALL TESTS PASS: Get authorization, then publish
-npm version patch  # or minor/major
-npm publish --access public
-git push origin main --tags
-
-# 8. ALWAYS return to develop
-git checkout develop
-```
+| 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` |
 
-### Why the Bundle Script Is Critical
+#### Export Bundle Contents
 
-The bundle script (`cli/scripts/bundle-for-npm.sh`) does:
-1. Copies `core/src/*` into `cli/src/core/`
-2. Changes imports from `'qa360-core'` to `'../core/index.js'`
-3. Builds TypeScript → `cli/dist/`
-4. **Result**: `cli/dist/core/` contains the bundled core engine
+When exporting a run with `qa360 history export <run-id> --bundle proof.zip`, the ZIP contains:
 
-**Without this step**: The CLI imports `'qa360-core'` which doesn't exist in the npm package → **COMPLETELY BROKEN**
+- `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
 
-### Recovery from Broken Publication
+#### Garbage Collection
 
-If a broken version is published:
-1. **Fix the issue** on `develop`
-2. **Follow the FULL checklist** above
-3. **Publish a patch version** (e.g., 2.2.5 → 2.2.6)
-4. **Add a warning** in CHANGELOG about broken versions
+The `gc` command removes old test runs and orphaned artifacts to free disk space:
 
-## 🛠️ Technology Stack
+```bash
+# Preview what would be deleted (dry-run)
+qa360 history gc --dry-run
 
-- **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
+# Keep last 20 runs, delete older ones
+qa360 history gc --keep-last 20
 
-## 📚 Documentation
+# Default behavior (keeps last 10 unpinned runs)
+qa360 history gc
+```
 
-- [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)
+**Important**: Pinned runs are NEVER deleted by garbage collection. Use `qa360 history pin <run-id>` to protect important runs.
 
-## 🤝 Contributing
+## Exit Codes
 
-QA360 Core aims to become the **global standard for portable software quality proof**.
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Verification failed |
+| 2 | File not found |
+| 3 | Invalid schema |
+| 4 | Missing key |
+| 5 | Internal error |
 
-Every contribution should advance this mission with **simplicity, auditability, and elegance**.
+## Requirements
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
+- Node.js >= 18.0.0
+- npm or pnpm
 
-## 📄 License
+## Documentation
 
-MIT License - see [LICENSE](./LICENSE) for details.
+- [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)
 
----
+## License
 
-**QA360 Core**: Making quality **executable, measurable, and legally provable**.
+MIT

package/{cli/dist → dist}/commands/ai.js

@@ -10,7 +10,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
 import Table from 'cli-table3';
-import { createBest, getProviderInfo, getProviderStatus, createLLMProvider, DeepSeekProvider, DeepSeekError, OllamaProvider, OllamaError, OpenAIProvider, OpenAIError, AnthropicProvider, AnthropicError } from 'qa360-core';
+import { createBest, getProviderInfo, getProviderStatus, createLLMProvider, DeepSeekProvider, DeepSeekError, OllamaProvider, OllamaError, OpenAIProvider, OpenAIError, AnthropicProvider, AnthropicError } from '../core/index.js';
 /**
  * List all available AI providers
  */

package/{cli/dist → dist}/commands/coverage.js

@@ -5,7 +5,7 @@
  */
 import { Command } from 'commander';
 import { existsSync } from 'fs';
-import { CoverageCollector, CoverageAnalyzer, parseCoverageThreshold, formatCoverageThreshold } from 'qa360-core';
+import { CoverageCollector, CoverageAnalyzer, parseCoverageThreshold, formatCoverageThreshold } from '../core/index.js';
 export const coverageCommand = new Command('coverage');
 coverageCommand.description('Coverage analytics and reporting');
 // Show coverage for a specific file or run

package/{cli/dist → dist}/commands/crawl.d.ts

@@ -1,7 +1,8 @@
 /**
  * QA360 Crawl Command
  *
- * Crawls a website and generates a complete pack.yml with E2E tests
+ * Universal crawler for all types of web applications.
+ * Supports presets for different platform types and custom auth/test data.
  */
 import { Command } from 'commander';
 /**
@@ -14,11 +15,21 @@ export declare function createCrawlCommand(): Command;
 export declare function crawlCommand(url: string, options?: {
     output?: string;
     name?: string;
+    preset?: string;
+    listPresets?: boolean;
     maxDepth?: string;
     maxPages?: string;
     headed?: boolean;
     a11y?: boolean;
     exclude?: string[];
+    only?: string[];
+    scenario?: string;
+    authEmail?: string;
+    authPassword?: string;
+    authUrl?: string;
+    testData?: string;
+    viewport?: string;
+    slowMo?: string;
     quick?: boolean;
 }): Promise<void>;
 export default createCrawlCommand;