qa360 2.1.7 → 2.2.0

package/packages/mcp/src/__tests__/contract.test.ts

@@ -0,0 +1,902 @@
+/**
+ * MCP Server - Contract Tests
+ *
+ * Tests the INPUT/OUTPUT contracts for all MCP tools.
+ * These tests verify that tools accept the expected arguments
+ * and return results matching the declared types.
+ *
+ * This is critical for MCP consumers (Claude Desktop, etc.)
+ * to rely on stable interfaces.
+ *
+ * Strategy: Mock the underlying QA360 execution and only test
+ * the contract layer (input validation, output shape, error handling).
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// Import types
+import type {
+  RunArgs,
+  RunResult,
+  ReportSignArgs,
+  ReportSignResult,
+  VerifyArgs,
+  VerifyResult,
+  HistoryListArgs,
+  HistoryListResult,
+  HistoryGetArgs,
+  HistoryGetResult,
+  HistoryDiffArgs,
+  HistoryDiffResult,
+  HistoryTrendArgs,
+  HistoryTrendResult,
+  HistoryExportArgs,
+  HistoryExportResult,
+  HistoryGCArgs,
+  HistoryGCResult,
+  HistoryPinArgs,
+  PackAskArgs,
+  PackAskResult,
+  PackValidateArgs,
+  PackValidateResult,
+  SecretsAddArgs,
+  SecretsListArgs,
+  SecretsListResult,
+  SecretsRemoveArgs,
+  ServeDiagArgs,
+  ServeDiagResult,
+  VaultGetRunArgs,
+  VaultGetArtifactsArgs,
+  TriageExplainArgs,
+  TriageExplainResult,
+} from '../types/index.js';
+
+describe('MCP Tool Contracts - Type Validation', () => {
+  /**
+   * CONTRACT TEST 1: Run Tool
+   * qa360.run - Execute a QA360 test pack
+   */
+  describe('qa360.run contract', () => {
+    it('should accept valid RunArgs', () => {
+      const validArgs: RunArgs = {
+        packPath: '/path/to/pack.yaml',
+        runKey: 'my-test-run',
+        strict: true,
+        weights: { api: 0.3, ui: 0.4, perf: 0.3 },
+      };
+
+      expect(validArgs.packPath).toBeDefined();
+      expect(validArgs.packPath).toMatch(/\.ya?ml$/);
+    });
+
+    it('should accept minimal RunArgs', () => {
+      const minimalArgs: RunArgs = {
+        packPath: '/path/to/pack.yaml',
+      };
+
+      expect(minimalArgs.packPath).toBeDefined();
+    });
+
+    it('should produce RunResult shape', () => {
+      const validResult: RunResult = {
+        runId: '550e8400-e29b-41d4-a716-446655440000',
+        status: 'passed',
+        trust: {
+          score: 87,
+          weights: { api: 0.3, ui: 0.4, perf: 0.3 },
+        },
+        gates: [
+          {
+            name: 'api_smoke',
+            status: 'passed',
+            duration_ms: 1500,
+            key_metrics: { p95_ms: 142 },
+          },
+        ],
+      };
+
+      expect(validResult.runId).toMatch(/^[0-9a-f-]{36}$/);
+      expect(['passed', 'failed', 'cancelled', 'error']).toContain(validResult.status);
+      expect(validResult.trust.score).toBeGreaterThanOrEqual(0);
+      expect(validResult.trust.score).toBeLessThanOrEqual(100);
+      expect(Array.isArray(validResult.gates)).toBe(true);
+    });
+
+    it('should allow all valid status values', () => {
+      const statuses: Array<'passed' | 'failed' | 'cancelled' | 'error'> = [
+        'passed',
+        'failed',
+        'cancelled',
+        'error',
+      ];
+
+      statuses.forEach((status) => {
+        const result: RunResult = {
+          runId: 'test-id',
+          status,
+          trust: { score: 50 },
+          gates: [],
+        };
+        expect(result.status).toBe(status);
+      });
+    });
+  });
+
+  /**
+   * CONTRACT TEST 2: Report Tool
+   * qa360.report.sign - Sign a test report
+   */
+  describe('qa360.report.sign contract', () => {
+    it('should accept ReportSignArgs', () => {
+      const args: ReportSignArgs = {
+        runId: '550e8400-e29b-41d4-a716-446655440000',
+      };
+
+      expect(args.runId).toMatch(/^[0-9a-f-]{36}$/);
+    });
+
+    it('should produce ReportSignResult', () => {
+      const result: ReportSignResult = {
+        signature: 'ed25519-base64-signature',
+        algorithm: 'ed25519',
+        runId: '550e8400-e29b-41d4-a716-446655440000',
+      };
+
+      expect(result.signature).toBeDefined();
+      expect(result.algorithm).toBe('ed25519');
+      expect(result.runId).toBeDefined();
+    });
+  });
+
+  /**
+   * CONTRACT TEST 3: Verify Tool
+   * qa360.verify - Verify a proof bundle
+   */
+  describe('qa360.verify contract', () => {
+    it('should accept VerifyArgs with runId', () => {
+      const args: VerifyArgs = {
+        runId: '550e8400-e29b-41d4-a716-446655440000',
+      };
+
+      expect(args.runId).toBeDefined();
+    });
+
+    it('should accept VerifyArgs with proofPath', () => {
+      const args: VerifyArgs = {
+        proofPath: '/path/to/proof.json',
+      };
+
+      expect(args.proofPath).toBeDefined();
+    });
+
+    it('should produce VerifyResult', () => {
+      const validResult: VerifyResult = {
+        verified: true,
+        algorithm: 'ed25519',
+        message: 'Proof verified successfully',
+        runId: '550e8400-e29b-41d4-a716-446655440000',
+      };
+
+      const invalidResult: VerifyResult = {
+        verified: false,
+        algorithm: 'ed25519',
+        message: 'Signature verification failed',
+      };
+
+      expect(validResult.verified).toBe(true);
+      expect(invalidResult.verified).toBe(false);
+      expect(validResult.algorithm).toBe('ed25519');
+    });
+  });
+
+  /**
+   * CONTRACT TEST 4: History List
+   * qa360.history.list - List test runs
+   */
+  describe('qa360.history.list contract', () => {
+    it('should accept HistoryListArgs with filters', () => {
+      const args: HistoryListArgs = {
+        limit: 10,
+        status: 'passed',
+        gate: 'api_smoke',
+        since: '2025-01-01T00:00:00Z',
+      };
+
+      expect(args.limit).toBe(10);
+      expect(['passed', 'failed', 'error', 'cancelled', 'any']).toContain(args.status);
+    });
+
+    it('should accept empty HistoryListArgs', () => {
+      const args: HistoryListArgs = {};
+
+      expect(Object.keys(args)).toHaveLength(0);
+    });
+
+    it('should produce HistoryListResult', () => {
+      const result: HistoryListResult = {
+        runs: [
+          {
+            id: 'run-1',
+            started_at: 1704067200000,
+            status: 'passed',
+            trust_score: 87,
+            gates_summary: { api: 'passed', ui: 'passed' },
+          },
+          {
+            id: 'run-2',
+            started_at: 1704067260000,
+            status: 'failed',
+            trust_score: 45,
+          },
+        ],
+      };
+
+      expect(Array.isArray(result.runs)).toBe(true);
+      expect(result.runs[0].id).toBeDefined();
+      expect(typeof result.runs[0].started_at).toBe('number');
+    });
+  });
+
+  /**
+   * CONTRACT TEST 5: History Get
+   * qa360.history.get - Get detailed run info
+   */
+  describe('qa360.history.get contract', () => {
+    it('should accept HistoryGetArgs', () => {
+      const args: HistoryGetArgs = {
+        runId: '550e8400-e29b-41d4-a716-446655440000',
+      };
+
+      expect(args.runId).toBeDefined();
+    });
+
+    it('should produce HistoryGetResult', () => {
+      const result: HistoryGetResult = {
+        run: {
+          id: 'run-1',
+          started_at: 1704067200000,
+          ended_at: 1704067800000,
+          status: 'passed',
+          trust_score: 87,
+          pack_path: '/path/to/pack.yaml',
+          pack_hash: 'sha256-abc123',
+          run_key: 'test-key',
+        },
+        gates: [
+          {
+            name: 'api_smoke',
+            status: 'passed',
+            duration_ms: 1500,
+            metrics: { p95_ms: 142 },
+          },
+        ],
+        findings: [
+          {
+            gate: 'sast',
+            severity: 'high',
+            rule: 'sql-injection',
+            location: 'src/db.ts:45',
+            message: 'Potential SQL injection',
+          },
+        ],
+        artifacts: [
+          {
+            label: 'screenshot.png',
+            sha256: 'sha256-def456',
+            mime_type: 'image/png',
+            size_bytes: 12345,
+          },
+        ],
+      };
+
+      expect(result.run.id).toBeDefined();
+      expect(Array.isArray(result.gates)).toBe(true);
+      expect(Array.isArray(result.findings)).toBe(true);
+      expect(Array.isArray(result.artifacts)).toBe(true);
+    });
+  });
+
+  /**
+   * CONTRACT TEST 6: History Diff
+   * qa360.history.diff - Compare two runs
+   */
+  describe('qa360.history.diff contract', () => {
+    it('should accept HistoryDiffArgs', () => {
+      const args: HistoryDiffArgs = {
+        runA: 'run-1',
+        runB: 'run-2',
+      };
+
+      expect(args.runA).toBeDefined();
+      expect(args.runB).toBeDefined();
+    });
+
+    it('should produce HistoryDiffResult', () => {
+      const result: HistoryDiffResult = {
+        delta: {
+          trust: -5,
+          gates: {
+            api: { duration_change: -100 },
+            ui: { status_change: 'passed -> failed' },
+          },
+          findings: {
+            added: [{ rule: 'new-issue' }],
+            removed: [{ rule: 'fixed-issue' }],
+            regressed: [{ rule: 'reappeared-issue' }],
+          },
+        },
+      };
+
+      expect(typeof result.delta.trust).toBe('number');
+      expect(result.delta.gates).toBeDefined();
+      expect(result.delta.findings).toBeDefined();
+    });
+  });
+
+  /**
+   * CONTRACT TEST 7: History Trend
+   * qa360.history.trend - Analyze trends
+   */
+  describe('qa360.history.trend contract', () => {
+    it('should accept HistoryTrendArgs', () => {
+      const args: HistoryTrendArgs = {
+        gate: 'perf',
+        window: 10,
+      };
+
+      expect(args.gate).toBeDefined();
+      expect(args.window).toBe(10);
+    });
+
+    it('should produce HistoryTrendResult', () => {
+      const result: HistoryTrendResult = {
+        series: [
+          { timestamp: 1704067200000, value: 87 },
+          { timestamp: 1704067260000, value: 89 },
+          { timestamp: 1704067320000, value: 85 },
+        ],
+        summary: {
+          average: 87,
+          trend: 'stable',
+          window_size: 10,
+        },
+      };
+
+      expect(Array.isArray(result.series)).toBe(true);
+      expect(['up', 'down', 'stable']).toContain(result.summary.trend);
+    });
+  });
+
+  /**
+   * CONTRACT TEST 8: History Export
+   * qa360.history.export - Export run data
+   */
+  describe('qa360.history.export contract', () => {
+    it('should accept HistoryExportArgs', () => {
+      const args: HistoryExportArgs = {
+        runId: 'run-1',
+        bundlePath: '/tmp/export-bundle.tar.gz',
+      };
+
+      expect(args.runId).toBeDefined();
+      expect(args.bundlePath).toBeDefined();
+    });
+
+    it('should produce HistoryExportResult', () => {
+      const result: HistoryExportResult = {
+        bundlePath: '/tmp/export-bundle.tar.gz',
+        size_bytes: 12345,
+        contents: ['proof.json', 'screenshot.png', 'logs.txt'],
+      };
+
+      expect(result.bundlePath).toBeDefined();
+      expect(result.size_bytes).toBeGreaterThan(0);
+      expect(Array.isArray(result.contents)).toBe(true);
+    });
+  });
+
+  /**
+   * CONTRACT TEST 9: History GC
+   * qa360.history.gc - Garbage collect old runs
+   */
+  describe('qa360.history.gc contract', () => {
+    it('should accept HistoryGCArgs', () => {
+      const args: HistoryGCArgs = {
+        keepLast: 10,
+        maxBytes: '1GB',
+        dryRun: true,
+      };
+
+      expect(args.keepLast).toBe(10);
+      expect(args.dryRun).toBe(true);
+    });
+
+    it('should produce HistoryGCResult', () => {
+      const result: HistoryGCResult = {
+        removed: {
+          runs: 5,
+          artifacts: 15,
+          bytesFreed: 52428800,
+        },
+        dryRun: false,
+      };
+
+      expect(result.removed.runs).toBeGreaterThanOrEqual(0);
+      expect(result.removed.bytesFreed).toBeGreaterThanOrEqual(0);
+      expect(typeof result.dryRun).toBe('boolean');
+    });
+  });
+
+  /**
+   * CONTRACT TEST 10: History Pin
+   * qa360.history.pin - Pin a run from deletion
+   */
+  describe('qa360.history.pin contract', () => {
+    it('should accept HistoryPinArgs', () => {
+      const args: HistoryPinArgs = {
+        runId: 'run-1',
+      };
+
+      expect(args.runId).toBeDefined();
+    });
+  });
+
+  /**
+   * CONTRACT TEST 11: Pack Ask
+   * qa360.pack.ask - Generate pack from query
+   */
+  describe('qa360.pack.ask contract', () => {
+    it('should accept PackAskArgs', () => {
+      const args: PackAskArgs = {
+        query: 'Test my REST API endpoints',
+        context: {
+          targets: {
+            api: { baseUrl: 'https://api.example.com' },
+          },
+        },
+      };
+
+      expect(args.query).toBeDefined();
+      expect(args.context?.targets).toBeDefined();
+    });
+
+    it('should produce PackAskResult', () => {
+      const result: PackAskResult = {
+        pack: 'version: 1\nname: generated-pack\ngates:\n  - api_smoke',
+        hints: {
+          tools_needed: ['curl', 'node'],
+          estimated_duration: '2-5 minutes',
+          complexity: 'simple',
+        },
+      };
+
+      expect(result.pack).toBeDefined();
+      expect(['simple', 'medium', 'complex']).toContain(result.hints.complexity);
+    });
+  });
+
+  /**
+   * CONTRACT TEST 12: Pack Validate
+   * qa360.pack.validate - Validate pack YAML
+   */
+  describe('qa360.pack.validate contract', () => {
+    it('should accept PackValidateArgs with pack content', () => {
+      const args: PackValidateArgs = {
+        pack: 'version: 1\nname: test',
+      };
+
+      expect(args.pack).toBeDefined();
+    });
+
+    it('should accept PackValidateArgs with path', () => {
+      const args: PackValidateArgs = {
+        path: '/path/to/pack.yaml',
+      };
+
+      expect(args.path).toBeDefined();
+    });
+
+    it('should produce PackValidateResult', () => {
+      const validResult: PackValidateResult = {
+        valid: true,
+        errors: [],
+        warnings: [],
+      };
+
+      const invalidResult: PackValidateResult = {
+        valid: false,
+        errors: [
+          {
+            code: 'MISSING_FIELD',
+            message: 'Field "name" is required',
+            line: 2,
+            column: 1,
+          },
+        ],
+        warnings: [
+          {
+            code: 'DEPRECATED',
+            message: 'Field "old_field" is deprecated',
+          },
+        ],
+        auto_fixes: ['Add "name: <pack-name>"'],
+      };
+
+      expect(validResult.valid).toBe(true);
+      expect(invalidResult.valid).toBe(false);
+      expect(Array.isArray(invalidResult.errors)).toBe(true);
+    });
+  });
+
+  /**
+   * CONTRACT TEST 13: Secrets Add
+   * qa360.secrets.add - Add a secret
+   */
+  describe('qa360.secrets.add contract', () => {
+    it('should accept SecretsAddArgs', () => {
+      const args: SecretsAddArgs = {
+        name: 'API_KEY',
+        value: 'secret-value',
+        description: 'API key for external service',
+      };
+
+      expect(args.name).toBeDefined();
+      expect(args.value).toBeDefined();
+    });
+
+    it('should accept minimal SecretsAddArgs', () => {
+      const args: SecretsAddArgs = {
+        name: 'TOKEN',
+        value: 'token-value',
+      };
+
+      expect(args.name).toBeDefined();
+      expect(args.value).toBeDefined();
+    });
+  });
+
+  /**
+   * CONTRACT TEST 14: Secrets List
+   * qa360.secrets.list - List all secrets
+   */
+  describe('qa360.secrets.list contract', () => {
+    it('should accept empty SecretsListArgs', () => {
+      const args: SecretsListArgs = {};
+
+      expect(Object.keys(args)).toHaveLength(0);
+    });
+
+    it('should produce SecretsListResult', () => {
+      const result: SecretsListResult = {
+        secrets: [
+          {
+            name: 'API_KEY',
+            description: 'External API key',
+            created_at: 1704067200000,
+            last_used: 1704067800000,
+          },
+          {
+            name: 'TOKEN',
+            created_at: 1704067200000,
+          },
+        ],
+      };
+
+      expect(Array.isArray(result.secrets)).toBe(true);
+      expect(typeof result.secrets[0].created_at).toBe('number');
+    });
+  });
+
+  /**
+   * CONTRACT TEST 15: Secrets Remove
+   * qa360.secrets.remove - Remove a secret
+   */
+  describe('qa360.secrets.remove contract', () => {
+    it('should accept SecretsRemoveArgs', () => {
+      const args: SecretsRemoveArgs = {
+        name: 'API_KEY',
+      };
+
+      expect(args.name).toBeDefined();
+    });
+  });
+
+  /**
+   * CONTRACT TEST 16: Serve Diag
+   * qa360.serve.diag - Server health check
+   */
+  describe('qa360.serve.diag contract', () => {
+    it('should accept empty ServeDiagArgs', () => {
+      const args: ServeDiagArgs = {};
+
+      expect(Object.keys(args)).toHaveLength(0);
+    });
+
+    it('should produce ServeDiagResult', () => {
+      const result: ServeDiagResult = {
+        health: 'healthy',
+        version: '1.0.0',
+        uptime_ms: 1234567,
+        metrics: {
+          active_runs: 2,
+          total_runs: 100,
+          success_rate: 0.95,
+        },
+        vault_stats: {
+          total_runs: 100,
+          total_artifacts: 250,
+          vault_size_bytes: 5242880,
+        },
+      };
+
+      expect(['healthy', 'degraded', 'unhealthy']).toContain(result.health);
+      expect(result.uptime_ms).toBeGreaterThan(0);
+      expect(result.metrics).toBeDefined();
+    });
+  });
+
+  /**
+   * CONTRACT TEST 17: Triage Explain
+   * qa360.triage.explain - Explain a finding code
+   */
+  describe('qa360.triage.explain contract', () => {
+    it('should accept TriageExplainArgs', () => {
+      const args: TriageExplainArgs = {
+        code: 'SG001',
+        context: {
+          language: 'typescript',
+          framework: 'react',
+        },
+      };
+
+      expect(args.code).toBeDefined();
+      expect(args.context).toBeDefined();
+    });
+
+    it('should accept valid finding codes', () => {
+      const validCodes = ['SG001', 'ZAP001', 'GL001', 'OSV001', 'PA001', 'PU001', 'K6100'];
+
+      validCodes.forEach((code) => {
+        const args: TriageExplainArgs = { code };
+        expect(args.code).toMatch(/^(SG|ZAP|GL|OSV|PA|PU|K6)\d+$/);
+      });
+    });
+
+    it('should produce TriageExplainResult', () => {
+      const result: TriageExplainResult = {
+        explanation: {
+          cause: 'SQL injection vulnerability detected',
+          severity: 'high',
+          category: 'security',
+        },
+        actions: [
+          {
+            type: 'fix',
+            description: 'Use parameterized queries',
+            command: 'npm install sql-template',
+          },
+          {
+            type: 'investigate',
+            description: 'Review all database queries',
+          },
+        ],
+        references: [
+          {
+            title: 'OWASP SQL Injection',
+            url: 'https://owasp.org/www-community/attacks/SQL_Injection',
+          },
+        ],
+      };
+
+      expect(['low', 'medium', 'high', 'critical']).toContain(result.explanation.severity);
+      expect(Array.isArray(result.actions)).toBe(true);
+      expect(Array.isArray(result.references)).toBe(true);
+    });
+  });
+
+  /**
+   * CONTRACT TEST 18: Vault Get Run
+   * qa360.vault.getRun - Get run from vault
+   */
+  describe('qa360.vault.getRun contract', () => {
+    it('should accept VaultGetRunArgs', () => {
+      const args: VaultGetRunArgs = {
+        runId: 'run-1',
+      };
+
+      expect(args.runId).toBeDefined();
+    });
+  });
+
+  /**
+   * CONTRACT TEST 19: Vault Get Artifacts
+   * qa360.vault.getArtifacts - Get run artifacts
+   */
+  describe('qa360.vault.getArtifacts contract', () => {
+    it('should accept VaultGetArtifactsArgs', () => {
+      const args: VaultGetArtifactsArgs = {
+        runId: 'run-1',
+      };
+
+      expect(args.runId).toBeDefined();
+    });
+  });
+});
+
+describe('MCP Tool Contracts - Error Handling', () => {
+  /**
+   * CONTRACT TEST 20: Error Response Format
+   *
+   * All MCP tools should return errors in a consistent format
+   */
+  it('should use consistent error format', () => {
+    interface QA360Error {
+      code: string;
+      message: string;
+      hint?: string;
+    }
+
+    const error: QA360Error = {
+      code: 'PACK_NOT_FOUND',
+      message: 'Pack file not found: /path/to/pack.yaml',
+      hint: 'Check that the file path is correct and the file exists.',
+    };
+
+    expect(error.code).toBeDefined();
+    expect(error.code).toMatch(/^[A-Z_]+$/);
+    expect(error.message).toBeDefined();
+    expect(error.hint).toBeDefined();
+  });
+
+  it('should include error codes for common failures', () => {
+    const expectedErrorCodes = [
+      'PACK_NOT_FOUND',
+      'PACK_INVALID',
+      'RUN_NOT_FOUND',
+      'VAULT_ERROR',
+      'SIGNATURE_FAILED',
+      'PERMISSION_DENIED',
+      'SECRET_NOT_FOUND',
+    ];
+
+    expectedErrorCodes.forEach((code) => {
+      expect(code).toMatch(/^[A-Z_]+$/);
+    });
+  });
+});
+
+describe('MCP Tool Contracts - Security', () => {
+  /**
+   * CONTRACT TEST 21: Path Traversal Protection
+   *
+   * All file path arguments should be validated
+   */
+  it('should reject path traversal attempts', () => {
+    const maliciousPaths = [
+      '../../../etc/passwd',
+      '~/.ssh/id_rsa',
+      '../../.env',
+      '/etc/passwd',
+      'subfolder/../../../sensitive',
+    ];
+
+    maliciousPaths.forEach((path) => {
+      // In real implementation, this would be validated by SecurityManager
+      // Paths with traversal or sensitive system paths should be blocked
+      const isSuspicious = path.includes('..') || path.includes('~') || path.startsWith('/etc/') || path.includes('.env');
+      expect(isSuspicious).toBe(true);
+    });
+
+    // Absolute paths that are NOT system paths are OK (in some contexts)
+    const acceptablePaths = [
+      '/absolute/path/outside/allowed',
+      '/home/user/project',
+      'C:/Users/user/project',  // Windows absolute path (not system dir)
+    ];
+
+    acceptablePaths.forEach((path) => {
+      const isSuspicious = path.includes('..') || path.includes('~') || path.startsWith('/etc/') || path.includes('.env');
+      expect(isSuspicious).toBe(false);
+    });
+  });
+
+  /**
+   * CONTRACT TEST 22: Secret Value Protection
+   *
+   * Secret values should never be exposed in logs or responses
+   */
+  it('should not expose secret values in list response', () => {
+    const result: SecretsListResult = {
+      secrets: [
+        {
+          name: 'API_KEY',
+          description: 'API key',
+          created_at: 1704067200000,
+          // Note: 'value' field should NOT be present
+        },
+      ],
+    };
+
+    // Secret value should not be exposed
+    expect('value' in result.secrets[0]).toBe(false);
+  });
+});
+
+describe('MCP Tool Registry', () => {
+  /**
+   * CONTRACT TEST 23: Tool Registration
+   *
+   * All tools must be properly registered with schema
+   */
+  it('should have expected tool count', () => {
+    // List of all MCP tools
+    const expectedTools = [
+      'qa360.run',
+      'qa360.report.sign',
+      'qa360.verify',
+      'qa360.history.list',
+      'qa360.history.get',
+      'qa360.history.diff',
+      'qa360.history.trend',
+      'qa360.history.export',
+      'qa360.history.gc',
+      'qa360.history.pin',
+      'qa360.pack.ask',
+      'qa360.pack.validate',
+      'qa360.pack.lint',
+      'qa360.secrets.add',
+      'qa360.secrets.list',
+      'qa360.secrets.remove',
+      'qa360.serve.diag',
+      'qa360.serve.start',
+      'qa360.serve.stop',
+      'qa360.vault.getRun',
+      'qa360.vault.getArtifacts',
+      'qa360.vault.stats',
+      'qa360.triage.explain',
+    ];
+
+    expect(expectedTools.length).toBeGreaterThanOrEqual(20);
+  });
+
+  /**
+   * CONTRACT TEST 24: Tool Schema Format
+   *
+   * Each tool should have a proper schema for MCP discovery
+   */
+  it('should have valid tool schema format', () => {
+    interface ToolSchema {
+      name: string;
+      description: string;
+      inputSchema: {
+        type: 'object';
+        properties: Record<string, any>;
+        required?: string[];
+      };
+    }
+
+    const exampleSchema: ToolSchema = {
+      name: 'qa360.run',
+      description: 'Execute a QA360 test pack',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          packPath: {
+            type: 'string',
+            description: 'Path to the pack YAML file',
+          },
+          runKey: {
+            type: 'string',
+            description: 'Optional run key for idempotence',
+          },
+        },
+        required: ['packPath'],
+      },
+    };
+
+    expect(exampleSchema.name).toBeDefined();
+    expect(exampleSchema.description).toBeDefined();
+    expect(exampleSchema.inputSchema.type).toBe('object');
+    expect(Array.isArray(exampleSchema.inputSchema.required)).toBe(true);
+  });
+});