qa360 2.1.7 → 2.2.0

package/docs/archive/PHASE3_STATUS.md

@@ -0,0 +1,255 @@
+# 🚧 Phase 3: CLI Integration - IN PROGRESS
+
+**Date**: 2025-10-26 01:15 UTC  
+**Status**: ⚠️ **PARTIAL - Needs Monorepo Config**
+
+---
+
+## ✅ Completed
+
+### 1. Core Exports ✅
+- Added `export * from './proof/index.js'` to `core/src/index.ts`
+- All proof types and functions now exported from `@qa360/core`
+
+### 2. CLI verify.ts ✅
+- **File**: `cli/src/commands/verify.ts` (rewritten)
+- **Features**:
+  - `qa360 verify <proof.json>` - Single file verification
+  - `qa360 verify <directory>` - Batch verification
+  - `--json` flag for machine-readable output
+  - Human-friendly colored output
+  - Error codes 0-5
+  - Auto-detect proof bundles in directory
+
+**Output Format**:
+```
+✅ Proof verified: OK
+
+🔏 Signer: local@qa360
+🔐 Hash: sha256-abc123...
+📦 Artifacts: 7 (all verified)
+⏱️  Run: 2025-10-26T12:34:56Z → 2025-10-26T12:35:42Z
+🎯 Trust Score: 87/100
+```
+
+---
+
+## ⚠️ Blockers
+
+### TypeScript Configuration Issue
+
+**Problem**: CLI cannot import from `@qa360/core` due to monorepo tsconfig
+
+**Error**:
+```
+Le fichier '/Users/bassiroudiop/QA360/core/src/index.ts' ne se trouve pas 
+sous 'rootDir' '/Users/bassiroudiop/QA360/cli/src'.
+```
+
+**Root Cause**: 
+- `cli/tsconfig.json` has `rootDir: "./src"`
+- Cannot import from `../core/src/` (outside rootDir)
+
+**Solutions**:
+
+#### Option A: TypeScript Project References (Recommended)
+```json
+// cli/tsconfig.json
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "references": [
+    { "path": "../core" }
+  ]
+}
+
+// core/tsconfig.json
+{
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true
+  }
+}
+```
+
+#### Option B: Path Mapping
+```json
+// cli/tsconfig.json
+{
+  "compilerOptions": {
+    "paths": {
+      "@qa360/core": ["../core/src/index.ts"],
+      "@qa360/core/*": ["../core/src/*"]
+    }
+  }
+}
+```
+
+#### Option C: Build core first, import from dist
+```typescript
+// cli/src/commands/verify.ts
+import { verifyProofFile } from '../../../core/dist/proof/index.js';
+```
+
+---
+
+## 📋 Remaining Work
+
+### 1. Fix Monorepo Imports ⏳
+- Choose solution (A, B, or C)
+- Update tsconfig files
+- Verify compilation
+
+### 2. Update doctor.ts ⏳
+```typescript
+// Add proof system check
+✅ Proof system ready
+  ✅ Ed25519 keys generated
+  ✅ Proofs directory exists
+  ✅ Sign/verify roundtrip OK
+```
+
+### 3. CLI Integration Tests ⏳
+```bash
+# Test verify command
+qa360 verify examples/proofs/httpbin-proof.json
+qa360 verify examples/proofs/
+qa360 verify --json
+
+# Test doctor
+qa360 doctor
+```
+
+---
+
+## 🎯 Next Steps (Immediate)
+
+### Step 1: Fix TypeScript Config (15 min)
+
+**Recommended**: Option A (Project References)
+
+```bash
+# 1. Update core/tsconfig.json
+{
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true
+  }
+}
+
+# 2. Update cli/tsconfig.json
+{
+  "references": [
+    { "path": "../core" }
+  ]
+}
+
+# 3. Build with references
+cd core && pnpm run build
+cd ../cli && pnpm run build
+```
+
+### Step 2: Complete doctor.ts (30 min)
+
+```typescript
+import { keysExist, initializeKeys, testRoundtrip } from '@qa360/core';
+
+// Add to doctor checks
+const proofSystemCheck = async () => {
+  const hasKeys = await keysExist();
+  if (!hasKeys) {
+    // Auto-fix: generate keys
+    await initializeKeys();
+  }
+  
+  // Test roundtrip
+  const keyPair = await loadKeys();
+  const testData = 'test';
+  const roundtripOK = testRoundtrip(testData, keyPair);
+  
+  return {
+    name: 'Proof System',
+    status: roundtripOK ? 'ok' : 'error',
+    details: {
+      keysGenerated: hasKeys,
+      roundtripOK,
+    },
+  };
+};
+```
+
+### Step 3: E2E Tests (1h)
+
+```bash
+# Create test script
+tests/e2e/cli-verify.test.ts
+
+# Test matrix
+- Windows × Node 18/20/22
+- macOS × Node 18/20/22
+- Linux × Node 18/20/22
+```
+
+---
+
+## 📊 Progress
+
+| Task | Status | Time |
+|------|--------|------|
+| Core exports | ✅ | 5 min |
+| verify.ts rewrite | ✅ | 30 min |
+| **Fix tsconfig** | ⏳ | **15 min** |
+| **Update doctor.ts** | ⏳ | **30 min** |
+| **E2E tests** | ⏳ | **1h** |
+
+**Total**: 35/120 min (29%)
+
+---
+
+## 💡 Recommendations
+
+### Immediate Action
+1. **Fix TypeScript config** (Option A - Project References)
+2. **Build core** (`cd core && pnpm run build`)
+3. **Test imports** in CLI
+4. **Complete doctor.ts**
+5. **Run E2E tests**
+
+### Quality Gates
+- ✅ CLI compiles without errors
+- ✅ `qa360 verify` works on example proofs
+- ✅ `qa360 doctor` shows proof system status
+- ✅ Exit codes correct (0 = OK, 1-5 = errors)
+- ✅ JSON output valid
+- ✅ Cross-OS tested
+
+---
+
+## 🎓 Lessons Learned
+
+### What Worked ✅
+- RFC-first approach made implementation straightforward
+- Core proof system is solid and ready
+- CLI UX design is clear
+
+### Challenges ⚠️
+- Monorepo TypeScript configuration
+- Import resolution between packages
+- Need project references or path mapping
+
+### Next Time 📋
+- Set up TypeScript project references from start
+- Test cross-package imports early
+- Use `pnpm build --filter` for monorepo builds
+
+---
+
+**Phase 3 Status**: ⚠️ **BLOCKED ON TSCONFIG**  
+**Blocker**: Monorepo import resolution  
+**ETA to Complete**: 2 hours (after tsconfig fix)
+
+**🎯 Once tsconfig is fixed, Phase 3 can be completed in ~2 hours.**

package/docs/archive/PRE-WEEK2-AUDIT.md

@@ -0,0 +1,364 @@
+# 🔍 PRE-WEEK 2 BUILD AUDIT
+
+**Date:** December 23, 2024  
+**Status:** ⚠️ ISSUES FOUND - NOT CRITICAL  
+**Summary:** MCP package clean, CLI needs fixes, 8 test failures, ESLint config broken
+
+---
+
+## Build Status
+
+**TypeScript Compilation:** 🚨 ERRORS  
+**Error Count:** 15 errors (all in CLI package)  
+**Exit Code:** 1 (failed)
+
+### Details
+
+**Critical Errors (CLI Package):**
+
+1. **Missing Core Exports (4 errors):**
+   - `cli/src/commands/history.ts:11` - Module `@qa360/core` has no exported member `RunRecord`
+   - `cli/src/commands/history.ts:11` - Module `@qa360/core` has no exported member `GateRecord`
+   - `cli/src/commands/history.ts:11` - Module `@qa360/core` has no exported member `FindingRecord`
+   - `cli/src/commands/serve.ts:7` - Module `@qa360/core` has no exported member `QA360Server`
+   - `cli/src/commands/serve.ts:7` - Module `@qa360/core` has no exported member `ServeConfig`
+
+2. **Missing Module Paths (3 errors):**
+   - `cli/src/commands/pack.ts:11` - Cannot find module `@qa360/core/pack/validator`
+   - `cli/src/commands/pack.ts:12` - Cannot find module `@qa360/core/pack/migrator`
+   - `cli/src/commands/pack.ts:13` - Cannot find module `@qa360/core/types/pack-v1`
+
+3. **Inquirer Type Issues (5 errors):**
+   - `cli/src/commands/secrets.ts:52,68,155,165,268` - Property `prompt` does not exist on type `inquirer`
+
+4. **Import Assignment Issue (1 error):**
+   - `cli/src/commands/history.ts:10` - Import assignment cannot be used with ECMAScript modules
+
+5. **Vitest Test File (1 error):**
+   - `cli/src/commands/__tests__/doctor-qa360-home.test.ts:7` - Cannot find module `vitest`
+
+6. **TypeScript Output File Errors (11 errors):**
+   - TS6305: Output files not built from source (cli-minimal, commands/*, index)
+   - These are secondary errors caused by the above failures
+
+**Core Package:** ✅ No errors detected  
+**MCP Package:** ✅ No errors detected
+
+---
+
+## Type Check Status
+
+**Type Errors:** 15 (same as build)  
+**Exit Code:** 1 (failed)
+
+**Critical Issues:**
+- All errors are in CLI package
+- Primarily missing exports from Core package
+- Inquirer type definition mismatch
+
+---
+
+## Lint Status
+
+**Status:** 🚨 CRASHED  
+**Errors:** ESLint configuration error  
+**Warnings:** N/A (could not run)
+
+### Details
+
+```
+TypeError: Cannot set properties of undefined (setting 'defaultMeta')
+at ajvOrig (@eslint/eslintrc@2.1.4)
+```
+
+**Root Cause:** ESLint + ajv compatibility issue  
+**Impact:** Cannot run linting until fixed  
+**Severity:** MEDIUM (blocks code quality checks but not functionality)
+
+---
+
+## Test Status
+
+**Status:** ⚠️ 8 FAILURES  
+**Total:** 184 tests  
+**Passed:** 176 (95.7%)  
+**Failed:** 8 (4.3%)  
+**Test Suites:** 18 failed, 13 passed, 31 total  
+**Duration:** 10.995s
+
+### Failed Tests
+
+**All failures in:** `core/src/__tests__/integration/phase3.test.ts`
+
+**Missing Files (Phase 3 Web-Lite Example):**
+1. ❌ `pack.yml` - Expected but not found
+2. ❌ `services.yml` - Expected but not found  
+3. ❌ `web-content/index.html` - Expected but not found
+4. ❌ `web-content/healthz` - Expected but not found
+5. ❌ `api-mock/server.js` - Expected but not found
+
+**Test Failures:**
+```
+● should have valid pack.yml structure
+● should have required service files
+● should have proper Docker Compose structure
+```
+
+**Root Cause:** Phase 3 example files not yet implemented  
+**Impact:** Integration tests fail, but unit tests pass  
+**Severity:** LOW (Phase 3 is future work)
+
+---
+
+## CLI Status
+
+**Status:** 🚨 CANNOT EXECUTE  
+**Doctor Check:** N/A (CLI not built)
+
+### Error
+
+```
+ReferenceError: require is not defined in ES module scope
+at file:///Users/bassiroudiop/QA360/cli/bin/qa360.js:8:1
+```
+
+**Root Cause:** CLI package uses `"type": "module"` but binary uses `require()`  
+**Impact:** CLI commands cannot be executed  
+**Severity:** HIGH (blocks CLI usage)
+
+**Affected File:** `cli/bin/qa360.js`
+
+---
+
+## MCP Package Status
+
+**Status:** ✅ CLEAN BUILD  
+**TypeScript Compilation:** SUCCESS  
+**Exit Code:** 0  
+**Duration:** ~2s
+
+**Package:** `@qa360/mcp v1.2.0`  
+**Build Output:** No errors, no warnings
+
+---
+
+## SUMMARY
+
+**Overall Status:** ⚠️ NEEDS FIXES BEFORE WEEK 2
+
+### Critical Blockers (MUST FIX) 🚨
+
+1. **CLI Build Failures** - 15 TypeScript errors prevent CLI from building
+2. **CLI Binary Broken** - Cannot execute `qa360 doctor` or any CLI command
+3. **ESLint Config Broken** - Cannot run code quality checks
+
+### Non-Critical (CAN DEFER) ⚠️
+
+4. **8 Test Failures** - Phase 3 integration tests (future work, not blocking)
+5. **Missing Example Files** - Phase 3 web-lite example incomplete
+
+### Working Components ✅
+
+- ✅ Core package builds successfully
+- ✅ MCP package builds successfully (v1.2.0 unified)
+- ✅ 176/184 tests passing (95.7%)
+- ✅ Monorepo structure clean (Week 1 cleanup complete)
+
+---
+
+## ISSUES FOUND
+
+### 1. CLI Missing Core Exports
+
+**Severity:** 🚨 CRITICAL  
+**Affected Files:**
+- `cli/src/commands/history.ts`
+- `cli/src/commands/serve.ts`
+- `cli/src/commands/pack.ts`
+
+**Missing Exports from `@qa360/core`:**
+- `RunRecord`, `GateRecord`, `FindingRecord` (history types)
+- `QA360Server`, `ServeConfig` (server)
+- `@qa360/core/pack/validator` (module path)
+- `@qa360/core/pack/migrator` (module path)
+- `@qa360/core/types/pack-v1` (module path)
+
+**Solution Required:**
+- Update `/core/src/index.ts` to export missing types/classes
+- Add proper module path exports or fix import statements in CLI
+
+---
+
+### 2. Inquirer Type Mismatch
+
+**Severity:** ⚠️ MEDIUM  
+**Affected File:** `cli/src/commands/secrets.ts`
+
+**Issue:** Property `prompt` does not exist on type `inquirer`
+
+**Possible Causes:**
+- Inquirer version mismatch
+- Type definition outdated
+- Import pattern incorrect (should be `inquirer.default.prompt`?)
+
+**Solution Required:**
+- Check `@types/inquirer` version
+- Update import pattern: `import inquirer from 'inquirer'` → `inquirer.prompt()`
+- Or use: `import { createPromptModule } from 'inquirer'`
+
+---
+
+### 3. ESLint Configuration Broken
+
+**Severity:** ⚠️ MEDIUM  
+**Issue:** `ajv` compatibility error with ESLint
+
+**Error:**
+```
+TypeError: Cannot set properties of undefined (setting 'defaultMeta')
+```
+
+**Solution Required:**
+- Update ESLint configuration
+- Check ajv version compatibility
+- May need to update `@eslint/eslintrc` dependency
+
+---
+
+### 4. CLI Binary ES Module Issue
+
+**Severity:** 🚨 CRITICAL  
+**Affected File:** `cli/bin/qa360.js`
+
+**Issue:** Using `require()` in ES module context
+
+**Current Code:**
+```javascript
+#!/usr/bin/env node
+require('../dist/index.js');
+```
+
+**Solution Required:**
+```javascript
+#!/usr/bin/env node
+import('../dist/index.js');
+```
+
+OR rename to `qa360.cjs` and use CommonJS
+
+---
+
+### 5. Phase 3 Integration Test Failures
+
+**Severity:** 🟡 LOW (DEFERRABLE)  
+**Affected:** `core/src/__tests__/integration/phase3.test.ts`
+
+**Missing Files:**
+- `core/examples/web-lite/pack.yml`
+- `core/examples/web-lite/services.yml`
+- `core/examples/web-lite/web-content/*`
+- `core/examples/web-lite/api-mock/*`
+
+**Solution Required:**
+- Create Phase 3 example files
+- OR skip tests until Phase 3 implementation
+- OR delete test file if premature
+
+---
+
+### 6. Vitest in CLI Tests
+
+**Severity:** 🟡 LOW  
+**Affected:** `cli/src/commands/__tests__/doctor-qa360-home.test.ts`
+
+**Issue:** Test imports `vitest` but package uses Jest
+
+**Solution Required:**
+- Change import from `vitest` to `@jest/globals`
+- OR add vitest to CLI package (inconsistent)
+- OR remove test file if not used
+
+---
+
+## RECOMMENDATION
+
+**🚨 DO NOT PROCEED TO WEEK 2 YET**
+
+### Fix Priority (Recommended Order)
+
+**Day 0 (Pre-Week 2 Fixes):**
+
+1. **Fix Core Exports (30 min)**
+   - Update `/core/src/index.ts`
+   - Export missing types and classes
+   - Fix module path exports
+
+2. **Fix CLI Binary (5 min)**
+   - Change `require` to `import` in `cli/bin/qa360.js`
+   - Test: `node cli/bin/qa360.js doctor`
+
+3. **Fix Inquirer Imports (15 min)**
+   - Update import pattern in `cli/src/commands/secrets.ts`
+   - Test secrets command
+
+4. **Fix ESLint Config (20 min)**
+   - Update ESLint/ajv dependencies
+   - OR disable lint check temporarily
+
+5. **Rebuild & Verify (10 min)**
+   - Run `pnpm run build` → expect 0 errors
+   - Run `pnpm test` → expect 176 passing (8 Phase 3 failures acceptable)
+   - Run `node cli/bin/qa360.js doctor` → expect X/10 checks
+
+**Total Estimated Fix Time:** ~1.5 hours
+
+### Week 2 Readiness Criteria
+
+**MUST HAVE (Blockers):**
+- ✅ CLI builds successfully (0 TypeScript errors)
+- ✅ CLI binary executes (`qa360 doctor` works)
+- ✅ Core package exports complete
+
+**SHOULD HAVE (Important):**
+- ✅ ESLint working (code quality checks)
+- ✅ 176+ tests passing
+
+**CAN DEFER (Nice to Have):**
+- ⏳ Phase 3 integration tests (8 failures acceptable)
+- ⏳ 100% test coverage
+- ⏳ Vitest test migration
+
+---
+
+## Next Steps
+
+1. **OPTION A: Fix Now (Recommended)**
+   - Spend 1.5 hours fixing critical issues
+   - Re-run audit
+   - Proceed to Week 2 with clean baseline
+
+2. **OPTION B: Handoff to TEST-01 As-Is**
+   - TEST-01 will spend Day 1-2 fixing these issues
+   - Week 2 timeline may slip
+   - Not recommended - better to fix before handoff
+
+3. **OPTION C: Document & Defer**
+   - Update HANDOFF_TEST-01.md with these specific issues
+   - TEST-01 aware of exact fixes needed
+   - Moderate risk - TEST-01 may need architecture knowledge
+
+---
+
+## Audit Conclusion
+
+**Week 1 Achievements:** ✅ ARCHITECTURE CLEANUP SUCCESSFUL  
+**Week 2 Readiness:** ⚠️ CRITICAL FIXES REQUIRED  
+**Estimated Fix Time:** 1.5 hours  
+**Recommendation:** Fix critical issues before activating TEST-01
+
+**Quality Gate:** 🔴 RED (cannot proceed without fixes)
+
+---
+
+*Audit performed: December 23, 2024*  
+*Next audit: After critical fixes applied*

package/docs/archive/README.md

@@ -0,0 +1,16 @@
+# Archived Documents
+
+This directory contains obsolete or historical documents that are kept for reference but are no longer part of the active documentation.
+
+## Contents
+
+### obsolete-proposals/
+
+Early proposals and planning documents that have been superseded by actual implementation:
+
+- `dom-element-discovery-mode.md` - DOM discovery strategy (implemented in `core/src/crawler/`)
+- `qa360-comprehensive-test-plan.md` - Initial test plan (superseded by `docs/QA_TEST_PLAN.md`)
+- `qa360-quick-start-guide.md` - Old quick start (superseded by main README)
+- `technical-plan-dom-discovery.md` - Technical plan for DOM discovery (implemented)
+
+**Note**: These documents represent historical planning discussions. For current implementation, see the source code in `core/src/` and active documentation in `docs/`.