qa360 2.1.4 → 2.1.5

package/README.md

@@ -1,250 +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
+# Option 2: Use a template directly
+qa360 init --template api-basic --yes
 
-# Verify cryptographic proof
-qa360 verify .qa360/runs/<run-id>-proof.json
+# Option 3: Copy an example
+qa360 examples copy api-basic
+qa360 examples list              # See all available examples
+```
 
-# Check system readiness
-qa360 doctor
+### 2. Run tests
+
+```bash
+qa360 run
 ```
 
-## 🛠️ Core Commands
+### 3. Verify proof
 
 ```bash
-# Execute quality gates
-qa360 run pack.yaml
+qa360 verify .qa360/runs/
+```
 
-# Verify proof signature
-qa360 verify .qa360/runs/proof.json
+## Usage
 
-# System diagnostics
-qa360 doctor --fix
+```bash
+# Generate test pack (interactive)
+qa360 init
 
-# Start observability server
-qa360 serve --port 3600
-```
+# Generate with template
+qa360 init --template api-basic
+qa360 init --template fullstack
+qa360 init --template security
+qa360 init --template complete
 
-## ✨ Why QA360?
+# 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
 
-- **🔒 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
+# System health check
+qa360 doctor
 
-## 🏗️ Architecture
+# Run test pack
+qa360 run                    # Auto-detects qa360.yml
+qa360 run custom-pack.yml    # Use specific file
 
-QA360 uses a clean monorepo architecture with unified packages and modular design.
+# Verify proof bundle
+qa360 verify .qa360/runs/
+qa360 verify proof.json
 
-### Structure
+# View run history
+qa360 history list
+qa360 history show <run-id>
 
-```
-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)
-```
+# Export proof bundle
+qa360 history export <run-id> --bundle proof-bundle.zip
+
+# 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
+
+# Pin/unpin runs (pinned runs are never deleted by gc)
+qa360 history pin <run-id>
+qa360 history unpin <run-id>
 
-### 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);
+# With JSON output (CI-friendly)
+qa360 doctor --json
+qa360 verify proof.json --json
+qa360 history list --json
 ```
 
-### Phase 1-3 Complete ✅
+## Available Templates
 
-| 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** |
+| 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) |
 
-```bash
-# Test Ollama connection
-qa360 ollama test
+## Example Files
+
+Pre-made examples are included in the package:
 
-# List installed models
-qa360 ollama list
+```bash
+# List examples
+ls examples/
 
-# Generate tests (preview)
-qa360 ollama generate "create API smoke tests for /users"
+# Copy an example
+cp examples/api-basic.yml qa360.yml
 
-# Configure Ollama
-qa360 ollama config
+# Run example directly
+qa360 run examples/api-basic.yml
 ```
 
-**See:** [`docs/OLLAMA_REFACTORING_ROADMAP.md`](./docs/OLLAMA_REFACTORING_ROADMAP.md) for the complete 10-week roadmap.
+## Commands
 
-## 📋 Development Phases
+| 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 |
 
-QA360 Core is developed in structured phases:
+### History Commands
 
-### 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
+The `history` command provides comprehensive management of test run history stored in the Evidence Vault:
 
-### 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)
+| 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` |
 
-### Future Roadmap
-- **Phase 8**: ✅ TUI & Dashboard (COMPLETE)
-- **Phase 9**: ⏳ Parallel CI → consolidated proof
+#### Export Bundle Contents
 
-## 🛠️ Technology Stack
+When exporting a run with `qa360 history export <run-id> --bundle proof.zip`, the ZIP contains:
 
-- **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
+- `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
 
-## 📚 Documentation
+#### Garbage Collection
+
+The `gc` command removes old test runs and orphaned artifacts to free disk space:
+
+```bash
+# Preview what would be deleted (dry-run)
+qa360 history gc --dry-run
+
+# Keep last 20 runs, delete older ones
+qa360 history gc --keep-last 20
+
+# 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/dist/cli-minimal.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * QA360 CLI - Minimal version for E2E tests
+ * Only includes doctor and verify commands
+ */
+export {};

package/dist/cli-minimal.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * QA360 CLI - Minimal version for E2E tests
+ * Only includes doctor and verify commands
+ */
+import { Command } from 'commander';
+import { doctorCommand } from './commands/doctor.js';
+import { verifyCommand } from './commands/verify.js';
+const program = new Command();
+program
+    .name('qa360')
+    .description('QA360 Proof Bundle CLI')
+    .version('1.0.1');
+program
+    .command('doctor')
+    .description('Health check and auto-fix issues')
+    .option('--fix', 'Automatically fix detected issues')
+    .option('--json', 'Output results as JSON')
+    .option('--strict', 'Exit with code 1 on any error')
+    .action(async (options) => {
+    await doctorCommand(options);
+});
+program
+    .command('verify [proof]')
+    .description('Verify proof authenticity and integrity')
+    .option('--json', 'Output results as JSON')
+    .option('--verbose', 'Show detailed verification information')
+    .action(async (proof, options) => {
+    await verifyCommand(proof, options);
+});
+// Parse arguments (no banner for clean JSON output)
+program.parse();
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+    program.outputHelp();
+}

package/dist/commands/ai.d.ts

@@ -0,0 +1,41 @@
+/**
+ * QA360 AI Command
+ *
+ * Manage AI provider integration for test generation.
+ * Supports DeepSeek, Ollama, OpenAI, Anthropic with automatic selection.
+ *
+ * DeepSeek is recommended for best value (GPT-4 level at 95% lower cost).
+ */
+import { Command } from 'commander';
+/**
+ * List all available AI providers
+ */
+export declare function aiListCommand(): Promise<void>;
+/**
+ * Use a specific AI provider
+ */
+export declare function aiUseCommand(provider: string, options?: {
+    verify?: boolean;
+}): Promise<void>;
+/**
+ * Benchmark all available providers
+ */
+export declare function aiBenchmarkCommand(options?: {
+    prompt?: string;
+}): Promise<void>;
+/**
+ * Generate tests using the best available provider
+ */
+export declare function aiGenerateCommand(prompt: string, options?: {
+    provider?: string;
+    type?: string;
+    json?: boolean;
+}): Promise<void>;
+/**
+ * Show AI configuration
+ */
+export declare function aiConfigCommand(): Promise<void>;
+/**
+ * Create AI commands
+ */
+export declare function createAICommands(): Command;