qa360 2.2.1 → 2.2.13

package/docs/archive/ARCH-01_MCP_MERGE_ANALYSIS.md

@@ -1,644 +0,0 @@
-# ARCH-01 - MCP PACKAGES MERGE ANALYSIS
-**Date:** 2024-12-23  
-**Mission:** Day 2 - Deep Analysis of MCP Packages  
-**Analyst:** ARCH-01 Architecture Cleaner  
-
----
-
-## 📊 EXECUTIVE SUMMARY
-
-**Analysis Scope:** 2 MCP packages with different purposes and overlapping functionality  
-**Merge Complexity:** MEDIUM-HIGH (significant overlap but different design goals)  
-**Recommendation:** **STRATEGIC MERGE** with phased approach  
-
-### Key Findings
-- **23 tools duplication** (full server vs minimal server)
-- **2 different bin entries** pointing to different servers
-- **Complementary functionality** (DX setup vs MCP protocol)
-- **Dependency overlap** (Commander, Chalk, MCP SDK)
-- **Version mismatch** (0.9.0-mcp vs 1.1.0)
-
----
-
-## 1️⃣ PACKAGE COMPARISON
-
-### Package 1: `@qa360/mcp-server` (v0.9.0-mcp)
-
-**Purpose:** Full-featured MCP Protocol Server exposing QA360 tools to LLMs/IDEs
-
-**Location:** `packages/mcp-server-qa360/`
-
-**Package.json Key Info:**
-```json
-{
-  "name": "@qa360/mcp-server",
-  "version": "0.9.0-mcp",
-  "main": "dist/index.js",
-  "bin": {
-    "qa360-mcp": "dist/index.js"
-  }
-}
-```
-
-**Dependencies (Production):**
-- `ajv` ^8.12.0
-- `chalk` ^5.3.0
-- `commander` ^11.1.0
-- `@qa360/core` workspace:*
-
-**Dev Dependencies:**
-- `@modelcontextprotocol/sdk` ^0.4.0 (devDep)
-- TypeScript, Jest, ESLint
-
-**Scripts:**
-- `build`, `dev`, `test`, `test:watch`, `test:coverage`, `test:integration`, `lint`
-
----
-
-### Package 2: `@qa360/mcp` (v1.1.0)
-
-**Purpose:** Zero-friction CLI for setup/configuration + Minimal MCP Server
-
-**Location:** `packages/qa360-mcp-cli/`
-
-**Package.json Key Info:**
-```json
-{
-  "name": "@qa360/mcp",
-  "version": "1.1.0",
-  "main": "dist/index.js",
-  "bin": {
-    "qa360-mcp": "dist/cli/cli.js",
-    "qa360-mcp-server": "dist/server/minimal-server.js"
-  }
-}
-```
-
-**Dependencies (Production):**
-- `@modelcontextprotocol/sdk` ^0.4.0 (prodDep)
-- `chalk` ^5.3.0
-- `commander` ^11.1.0
-- `execa` ^8.0.1
-- `fs-extra` ^11.2.0
-- `inquirer` ^9.2.12
-- `jsonc-parser` ^3.2.0
-- `ora` ^8.0.1
-- `semver` ^7.5.4
-
-**Dev Dependencies:**
-- `@cyclonedx/cyclonedx-npm`, Vitest, TypeScript, ESLint
-
-**Scripts:**
-- `build`, `check`, `dev`, `start`, `test`, `test:watch`, `test:dx`, `lint`
-- **CI/CD:** `sbom`, `audit:ci`, `ci:all`, `e2e`, `verify:settings`
-- **Publishing:** `prepublishOnly`, `publish:dry`, `publish:real`
-
----
-
-## 2️⃣ SOURCE STRUCTURE ANALYSIS
-
-### mcp-server-qa360 Structure (22 TypeScript files)
-
-```
-src/
-├── index.ts (213 lines)              # Main MCP server + CLI
-├── global.d.ts
-├── __tests__/                        # 5 test files
-│   ├── mcp-basic.test.ts
-│   ├── mcp-protocol.test.ts
-│   ├── security.test.ts
-│   ├── setup.ts
-│   └── tools.test.ts
-├── schemas/                          # JSON schemas
-├── security/                         # 2 files
-│   ├── audit.ts
-│   └── manager.ts
-├── tools/                            # 11 files
-│   ├── registry.ts (639 lines)      # 23 tools registry
-│   ├── history.ts
-│   ├── pack.ts
-│   ├── report.ts
-│   ├── run.ts
-│   ├── secrets.ts
-│   ├── serve.ts
-│   ├── triage.ts
-│   ├── types.ts
-│   ├── vault.ts
-│   └── verify.ts
-└── types/
-    ├── index.ts
-    └── mcp-stubs.ts
-```
-
-**Total Lines:** ~2,000+ lines (est.)
-
----
-
-### qa360-mcp-cli Structure (14 TypeScript files)
-
-```
-src/
-├── index.ts (13 lines)               # Export commands
-├── cli/                              # 10 command files
-│   ├── cli.ts (138 lines)           # Main CLI entry
-│   ├── doctor.ts (287 lines)        # Health checks
-│   ├── fix.ts
-│   ├── init.ts (234 lines)          # VS Code setup
-│   ├── postinstall.ts
-│   ├── reset.ts
-│   ├── telemetry.ts (180 lines)
-│   ├── test-dx.ts
-│   ├── uninstall.ts
-│   └── up.ts (179 lines)            # Server launcher
-├── server/
-│   └── minimal-server.ts (135 lines) # 3 basic tools
-└── scripts/
-    ├── e2e-local.ts
-    └── verify-settings.ts
-```
-
-**Total Lines:** ~1,500+ lines (est.)
-
----
-
-## 3️⃣ FUNCTIONALITY COMPARISON
-
-### mcp-server-qa360 Features
-
-**MCP Protocol Server:**
-- ✅ Full MCP SDK @0.4.0 implementation
-- ✅ JSON-RPC stdio transport
-- ✅ 23 tools in registry
-- ✅ Permission system (--allow-run, --allow-secrets)
-- ✅ Rate limiting + audit logging
-- ✅ Security redaction
-- ✅ Concurrency control
-
-**Tools Registry (23 tools):**
-1. **Core Execution (3):**
-   - `qa360.run` - Execute packs with idempotence
-   - `qa360.report.sign` - Ed25519 signatures
-   - `qa360.verify` - Verify signatures
-
-2. **History & Analytics (8):**
-   - `qa360.history.list|get|diff|trend|export|gc|pin|unpin`
-
-3. **Pack Management (4):**
-   - `qa360.pack.ask|validate|lint|migrate`
-
-4. **Secrets Management (2):** *(--allow-secrets)*
-   - `qa360.secrets.add|list`
-
-5. **Server & Diagnostics (6):**
-   - `qa360.serve.health|diag|metrics`
-   - `qa360.vault.get_run|get_artifacts`
-   - `qa360.triage.explain_code`
-
-**CLI Options:**
-- `--allow-run`, `--allow-secrets`
-- `--max-concurrency <number>`
-- `--rate-limit <number>`
-- `--audit-path <path>`
-- `--dry-run`, `--help-tools`
-
-**Integration:**
-- Direct `@qa360/core` import (EvidenceVault, etc.)
-- Real implementation (not stubs)
-
----
-
-### qa360-mcp-cli Features
-
-**Zero-Friction DX CLI:**
-- ✅ 9 commands (init, up, doctor, fix, reset, uninstall, telemetry, test:dx)
-- ✅ VS Code auto-configuration
-- ✅  extension detection
-- ✅ Backup & restore settings.json
-- ✅ Auto-recovery (max 3 restarts)
-- ✅ Multi-platform support (macOS, Linux, Windows)
-- ✅ JSON output for CI (`--json`)
-- ✅ Non-interactive mode (`--non-interactive`)
-- ✅ Telemetry opt-in (GDPR compliant)
-- ✅ SBOM generation (CycloneDX)
-- ✅ npm audit integration
-
-**CLI Commands:**
-1. **init** - Configure VS Code + 
-2. **up** - Start MCP server (stdio/http)
-3. **serve** - Alias for up
-4. **doctor** - Health checks (7 checks)
-5. **fix** - Auto-repair issues
-6. **reset** - Clean configs
-7. **uninstall** - Complete removal
-8. **telemetry** - Privacy-first analytics
-9. **test:dx** - DX compliance tests
-
-**Minimal MCP Server:**
-- ✅ 3 basic tools only:
-  - `qa360.health`
-  - `qa360.pack.validate`
-  - `qa360.history.list`
-- ❌ No @qa360/core integration
-- ❌ Stub implementations
-
-**Doctor Checks (7):**
-1. Node.js version (≥18.0.0)
-2. Package manager (npm/pnpm/yarn)
-3. VS Code installation
-4.  extension
-5. MCP Server presence
-6. QA360 home directory
-7. Permissions
-
-**CI/CD Features:**
-- GitHub Actions workflow ready
-- JSON structured output
-- Exit codes (0=success, 1=fail)
-- Matrix testing (3 OS × 3 Node)
-- SBOM + Security audit
-
----
-
-## 4️⃣ DUPLICATION ANALYSIS
-
-### 🔴 CRITICAL DUPLICATIONS
-
-#### 1. **MCP Server Implementation** ⚠️
-**Location:**
-- `mcp-server-qa360/src/index.ts` (213 lines)
-- `qa360-mcp-cli/src/server/minimal-server.ts` (135 lines)
-
-**Overlap:**
-- Both use `@modelcontextprotocol/sdk`
-- Both implement Server + StdioServerTransport
-- Both have tools registry
-- Both handle CallToolRequestSchema
-
-**Difference:**
-- Full: 23 tools + permissions + audit + rate limit
-- Minimal: 3 stub tools + basic health only
-
-**Merge Strategy:** Keep full server, remove minimal
-
----
-
-#### 2. **Binary Entry Points** ⚠️
-**Conflict:**
-- Both packages export `qa360-mcp` binary
-- `mcp-server`: Points to full server
-- `mcp-cli`: Points to CLI (up command → launches server)
-
-**Risk:** NPM package conflict if both installed globally
-
-**Merge Strategy:** Single binary with subcommands
-
----
-
-#### 3. **Dependencies Overlap**
-**Shared:**
-- `@modelcontextprotocol/sdk` ^0.4.0
-- `chalk` ^5.3.0
-- `commander` ^11.1.0
-
-**Unique to mcp-cli:**
-- `execa`, `fs-extra`, `inquirer`, `jsonc-parser`, `ora`, `semver`
-
-**Merge Strategy:** Keep all, consolidate versions
-
----
-
-#### 4. **Health Check Tool** 🔄
-**Both implement:**
-- `qa360.serve.health` (full server)
-- `qa360.health` (minimal server)
-
-**Merge Strategy:** Single implementation
-
----
-
-### 🟡 PARTIAL DUPLICATIONS
-
-#### 5. **Command System**
-- `mcp-server`: Commander CLI for server options
-- `mcp-cli`: Commander CLI for setup commands
-
-**Overlap:** Same library, different purposes
-
-**Merge Strategy:** Unified CLI with subcommands
-
----
-
-#### 6. **Testing Infrastructure**
-- `mcp-server`: Jest + integration tests
-- `mcp-cli`: Vitest + DX tests
-
-**Merge Strategy:** Consolidate on Jest or Vitest
-
----
-
-## 5️⃣ UNIQUE FEATURES ANALYSIS
-
-### ✅ Unique to mcp-server-qa360
-
-**Cannot be removed:**
-1. **23 Full Tools Implementation** - Core value
-2. **@qa360/core Integration** - Real EvidenceVault access
-3. **Permission System** - Security critical
-4. **Audit Logging** - Enterprise requirement
-5. **Rate Limiting** - Production readiness
-6. **Security Redaction** - Data protection
-7. **Tool Registry Architecture** - Extensibility
-8. **Concurrency Control** - Resource management
-9. **Test Coverage** - Protocol + security + tools
-
-**Technical Debt:**
-- ❌ No setup/installation tooling
-- ❌ No DX features
-- ❌ No CI/CD helpers
-
----
-
-### ✅ Unique to qa360-mcp-cli
-
-**Cannot be removed:**
-1. **init Command** - VS Code auto-configuration
-2. **doctor Command** - 7-check health system
-3. **fix Command** - Auto-repair logic
-4. **Telemetry System** - Privacy-first analytics
-5. **SBOM Generation** - Supply chain security
-6. **CI/CD Integration** - JSON output, non-interactive
-7. **Multi-platform Support** - Windows PowerShell, etc.
-8. **Auto-recovery** - Max 3 restarts
-9. **Backup/Restore** - Settings.json safety
-10. **DX Tests** - Compliance validation
-
-**Technical Debt:**
-- ❌ Minimal server with stub tools (not production-ready)
-- ❌ No real @qa360/core integration
-- ❌ Duplicate server implementation
-
----
-
-## 6️⃣ MERGE RECOMMENDATION
-
-### 🎯 Strategy: **PHASED STRATEGIC MERGE**
-
-**Goal:** Unified package combining full MCP server + DX CLI
-
-**Target Package Name:** `@qa360/mcp` (reuse mcp-cli name for better DX branding)
-
-**Target Version:** `1.2.0` (major DX + server consolidation)
-
----
-
-### Phase 1: Foundation (Week 1)
-
-**Objective:** Merge codebases without breaking changes
-
-**Actions:**
-1. ✅ Copy `mcp-server-qa360/src/tools/` → `mcp-cli/src/tools/`
-2. ✅ Copy `mcp-server-qa360/src/security/` → `mcp-cli/src/security/`
-3. ✅ Replace `minimal-server.ts` with full `index.ts` implementation
-4. ✅ Update dependencies (add `@qa360/core`, `ajv`)
-5. ✅ Merge test suites (Jest + Vitest → Jest only)
-6. ✅ Update bin entries:
-   ```json
-   "bin": {
-     "qa360-mcp": "dist/cli/cli.js"
-   }
-   ```
-7. ✅ Ensure `up` command launches full server (not minimal)
-
-**Validation:**
-- [ ] `npm run build` succeeds
-- [ ] All tests pass (100% coverage maintained)
-- [ ] `qa360-mcp up` launches full server with 23 tools
-- [ ] `qa360-mcp init` still works
-
----
-
-### Phase 2: CLI Integration (Week 2)
-
-**Objective:** Unified CLI with all commands
-
-**New Command Structure:**
-```bash
-qa360-mcp init         # Setup VS Code
-qa360-mcp up           # Start full MCP server
-qa360-mcp doctor       # Health checks
-qa360-mcp fix          # Auto-repair
-qa360-mcp list-tools   # Show 23 tools (replaces --help-tools)
-qa360-mcp reset        # Clean configs
-qa360-mcp uninstall    # Remove
-qa360-mcp telemetry    # Opt-in analytics
-qa360-mcp test:dx      # DX compliance
-```
-
-**Server Options** (via `up` command):
-```bash
-qa360-mcp up --allow-run --allow-secrets --rate-limit 10
-```
-
-**Actions:**
-1. ✅ Merge `cli.ts` from both packages
-2. ✅ Add `list-tools` command (from `--help-tools`)
-3. ✅ Integrate doctor checks for MCP server health
-4. ✅ Update docs with unified commands
-
----
-
-### Phase 3: Testing & Documentation (Week 3)
-
-**Objective:** Comprehensive validation
-
-**Actions:**
-1. ✅ Run conformance suite (6 packs)
-2. ✅ Test matrix (3 OS × 3 Node)
-3. ✅ Update README.md (merge both)
-4. ✅ Update CHANGELOG.md
-5. ✅ Create migration guide
-6. ✅ E2E tests (init → up → tools → uninstall)
-
-**Documentation Structure:**
-```
-README.md                 # Main (merge both)
-QUICK_START.md           # From mcp-cli
-docs/mcp-server.md       # Technical reference
-docs/mcp-tools.md        # 23 tools reference
-docs/migration.md        # v0.9 → v1.2
-```
-
----
-
-### Phase 4: Deprecation (Week 4)
-
-**Objective:** Clean legacy package
-
-**Actions:**
-1. ✅ Archive `packages/mcp-server-qa360/`
-2. ✅ Add deprecation notice to `@qa360/mcp-server` on npm
-3. ✅ Update `pnpm-workspace.yaml` (remove old package)
-4. ✅ Publish `@qa360/mcp@1.2.0` to npm
-5. ✅ Update GitHub Actions workflows
-6. ✅ Update main README.md
-
-**Deprecation Notice:**
-```
-⚠️ @qa360/mcp-server is deprecated
-→ Use @qa360/mcp@1.2.0 instead
-→ Migration guide: https://qa360.ai/docs/migration
-```
-
----
-
-## 7️⃣ RISK ANALYSIS
-
-### 🔴 HIGH RISKS
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| **Breaking changes for users** | Users upgrade → tools missing | Semantic versioning + migration guide |
-| **Binary name conflict** | Both export `qa360-mcp` | Phase 1: Remove old package first |
-| **Core integration missing** | mcp-cli has no @qa360/core | Phase 1: Add dependency |
-| **Test suite merge** | Jest + Vitest conflict | Phase 2: Consolidate on Jest |
-
-### 🟡 MEDIUM RISKS
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| **Version mismatch** | 0.9.0 vs 1.1.0 | Use 1.2.0 (clear upgrade) |
-| **MCP SDK location** | devDep vs prodDep | Move to prodDep (correct) |
-| **SBOM generation** | Only in mcp-cli | Keep in merged package |
-| **Telemetry system** | New feature, privacy concerns | Keep opt-in, document clearly |
-
-### 🟢 LOW RISKS
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| **Documentation split** | 2 READMEs to merge | Phase 3: Consolidate |
-| **Example configs** | Claude vs VSCode | Keep both examples |
-
----
-
-## 8️⃣ ACTION PLAN SUMMARY
-
-### Week 1: Foundation ✅ Ready to Execute
-```bash
-cd packages/qa360-mcp-cli
-mkdir -p src/tools src/security
-cp -r ../mcp-server-qa360/src/tools/* src/tools/
-cp -r ../mcp-server-qa360/src/security/* src/security/
-rm src/server/minimal-server.ts
-cp ../mcp-server-qa360/src/index.ts src/server/full-server.ts
-# Update imports + build
-pnpm install @qa360/core ajv
-pnpm build
-pnpm test
-```
-
-### Week 2: CLI Integration ✅ Ready to Execute
-```bash
-# Update cli/cli.ts with merged commands
-# Update cli/up.ts to launch full-server.ts
-# Add list-tools command
-# Test full workflow
-qa360-mcp init
-qa360-mcp up
-qa360-mcp list-tools
-qa360-mcp doctor
-```
-
-### Week 3: Validation ✅ Ready to Execute
-```bash
-# Run test suite
-pnpm test
-pnpm test:dx
-pnpm test:e2e
-# Generate docs
-# Update README
-```
-
-### Week 4: Publish ✅ Ready to Execute
-```bash
-# Deprecate old package
-npm deprecate @qa360/mcp-server "Use @qa360/mcp@1.2.0"
-# Publish new package
-cd packages/qa360-mcp-cli
-npm version 1.2.0
-npm run prepublishOnly
-npm publish --access public --provenance
-```
-
----
-
-## 9️⃣ SUCCESS METRICS
-
-### Pre-Merge (Current State)
-- ❌ 2 packages with overlap
-- ❌ Duplicate MCP server implementations
-- ❌ Binary name conflict
-- ❌ Fragmented documentation
-- ❌ Inconsistent versions (0.9.0 vs 1.1.0)
-
-### Post-Merge (Target State)
-- ✅ 1 unified package (`@qa360/mcp@1.2.0`)
-- ✅ 23 production tools + 9 DX commands
-- ✅ Single binary entry point
-- ✅ Consolidated docs
-- ✅ Full CI/CD + SBOM
-- ✅ Zero breaking changes (migration guide)
-
-### KPIs
-| Metric | Current | Target | Status |
-|--------|---------|--------|--------|
-| Packages | 2 | 1 | ⏳ Pending |
-| Tools | 23 + 3 stubs | 23 real | ⏳ Pending |
-| Commands | 0 + 9 | 9 unified | ⏳ Pending |
-| Dependencies | 4 + 9 | 13 | ⏳ Pending |
-| Test Coverage | 71% + 90% | 85%+ | ⏳ Pending |
-| SBOM | 0 + 1 | 1 | ✅ Keep |
-| Binary Conflicts | 1 | 0 | ⏳ Pending |
-
----
-
-## 🔟 CONCLUSION
-
-### Recommendation: **GO - STRATEGIC MERGE**
-
-**Why Merge:**
-1. ✅ Eliminates duplication (2 servers → 1)
-2. ✅ Better DX (setup + full server in one package)
-3. ✅ Cleaner dependency graph
-4. ✅ Single maintenance burden
-5. ✅ No binary conflicts
-6. ✅ Better for users (one npm install)
-
-**Why NOT Merge:**
-- ❌ Risk of breaking changes
-- ❌ Complex migration (4 weeks)
-- ❌ Testing overhead (matrix 3×3)
-
-**Verdict:** Benefits >> Risks
-
-**Timeline:** 4 weeks (1 week per phase)  
-**Effort:** ~40 hours total  
-**Risk Level:** MEDIUM (manageable with phased approach)
-
----
-
-## 📋 NEXT STEPS
-
-1. ✅ **Approval** - Get PO sign-off on merge plan
-2. ⏳ **Branch** - Create `feature/mcp-merge` branch
-3. ⏳ **Phase 1** - Execute foundation merge (Week 1)
-4. ⏳ **Phase 2** - CLI integration (Week 2)
-5. ⏳ **Phase 3** - Testing + docs (Week 3)
-6. ⏳ **Phase 4** - Deprecation + publish (Week 4)
-
-**Ready to Execute:** Phase 1 foundation merge ready immediately
-
----
-
-**Report Generated:** 2024-12-23 by ARCH-01  
-**Status:** ANALYSIS COMPLETE ✅  
-**Decision Required:** MERGE APPROVAL from Product Owner

package/docs/archive/ARCH-01_NEXT_STEPS.md

@@ -1,60 +0,0 @@
-# 
-
-## Situation
-
-J'ai créé le backup directory et les scripts, mais mes outils Filesystem ne peuvent pas supprimer directement les dossiers.
-
-## CE QUI A ÉTÉ FAIT ✅
-
-1. ✅ Backup directory créé: `/Users/bassiroudiop/QA360/.cleanup-backup-20241223/`
-2. ✅ Script de cleanup créé: `/Users/bassiroudiop/QA360/cleanup-step1.sh`
-3. ✅ Log de backup créé
-
-## CE QUE TU DOIS FAIRE MAINTENANT
-
-### Option 1: Exécuter le script (RECOMMANDÉ)
-
-```bash
-cd /Users/bassiroudiop/QA360
-chmod +x cleanup-step1.sh
-./cleanup-step1.sh
-```
-
-### Option 2: Commandes manuelles
-
-```bash
-cd /Users/bassiroudiop/QA360
-
-# Delete empty packages
-rm -rf packages/cli
-rm -rf packages/sdk  
-rm -rf packages/shared
-rm -rf packages/types
-
-# Verify
-ls -la packages/
-
-# Test build
-npm run build
-
-# Test CLI
-./cli/bin/qa360.js doctor
-```
-
-## APRÈS EXÉCUTION
-
-Reviens me dire :
-- ✅ "Done, build works" → Je continue avec Step 2 (MCP merge)
-- ❌ "Error: [message]" → Je t'aide à résoudre
-
-## PROCHAINE ÉTAPE (Step 2)
-
-Une fois Step 1 validé, je vais :
-1. Analyser les 2 packages MCP en profondeur
-2. Créer le plan de fusion
-3. Exécuter la fusion
-4. Tester tout fonctionne
-
----
-
-**ARCH-01 en attente de confirmation Step 1** ⏸️