@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/gate-executor.cjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+
+/**
+ * Gate Executor — Quality gate execution coordinator
+ *
+ * Executes all registered quality gates and reports results.
+ * Supports bypass with audit trail.
+ *
+ * Usage:
+ *   node gate-executor.cjs --pre-commit
+ *   node gate-executor.cjs --status
+ *   node gate-executor.cjs --bypass "reason"
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { QualityGate } = require('./quality-gate.cjs');
+const { z } = require('zod');
+
+const AUDIT_FILE = path.join(process.cwd(), '.planning', 'gate-audit.json');
+const STATUS_FILE = path.join(process.cwd(), '.planning', 'quality-status.json');
+
+// Initialize quality gate coordinator
+const qg = new QualityGate();
+
+// Register standard gates
+
+// Test gate
+qg.registerGate('test', z.object({ passRate: z.number().min(0.9) }), async (context) => {
+  try {
+    execSync('npm test', { stdio: 'pipe', encoding: 'utf8' });
+    return { passRate: 1.0 };
+  } catch (err) {
+    // Try to parse test output for pass rate
+    const output = err.stdout || err.stderr || '';
+    const match = output.match(/(\d+)%\s+pass/);
+    const passRate = match ? parseInt(match[1], 10) / 100 : 0;
+    throw new Error(`Tests failed (pass rate: ${(passRate * 100).toFixed(1)}%)`);
+  }
+});
+
+// Lint gate
+qg.registerGate('lint', z.object({ errorCount: z.number().max(0) }), async () => {
+  try {
+    execSync('npx eslint . --ext .cjs,.js --max-warnings=0', { stdio: 'pipe', encoding: 'utf8' });
+    return { errorCount: 0 };
+  } catch (err) {
+    const output = err.stdout || err.stderr || '';
+    const match = output.match(/(\d+)\s+error/);
+    const errorCount = match ? parseInt(match[1], 10) : 1;
+    throw new Error(`Linting failed (${errorCount} errors)`);
+  }
+});
+
+// Security gate
+qg.registerGate('security', z.object({ vulnerabilities: z.number().max(0) }), async () => {
+  try {
+    execSync('npm audit --production', { stdio: 'pipe', encoding: 'utf8' });
+    return { vulnerabilities: 0 };
+  } catch (err) {
+    const output = err.stdout || err.stderr || '';
+    const match = output.match(/found\s+(\d+)\s+vulnerabilit/);
+    const vulnerabilities = match ? parseInt(match[1], 10) : 1;
+    if (vulnerabilities > 0) {
+      console.warn(`[WARN] Found ${vulnerabilities} vulnerabilities`);
+      // Don't fail - just warn
+    }
+    return { vulnerabilities };
+  }
+});
+
+// Build gate
+qg.registerGate('build', z.object({ success: z.boolean() }), async () => {
+  try {
+    execSync('node scripts/build-hooks.js', { stdio: 'pipe', encoding: 'utf8' });
+    return { success: true };
+  } catch (err) {
+    throw new Error('Build failed');
+  }
+});
+
+// Documentation gate (JSDoc coverage)
+qg.registerGate('docs', z.object({ jsdocCoverage: z.number().min(0.5) }), async () => {
+  // Simple check: count files with JSDoc comments
+  const libDir = path.join(process.cwd(), 'bin', 'lib');
+  if (!fs.existsSync(libDir)) {
+    return { jsdocCoverage: 1.0 };
+  }
+
+  const files = fs.readdirSync(libDir).filter(f => f.endsWith('.cjs'));
+  let withJSDoc = 0;
+
+  for (const file of files) {
+    const content = fs.readFileSync(path.join(libDir, file), 'utf8');
+    if (content.includes('/**')) {
+      withJSDoc++;
+    }
+  }
+
+  const coverage = files.length > 0 ? withJSDoc / files.length : 1.0;
+  return { jsdocCoverage: coverage };
+});
+
+/**
+ * Load gate status from file
+ */
+function loadStatus() {
+  try {
+    if (fs.existsSync(STATUS_FILE)) {
+      return JSON.parse(fs.readFileSync(STATUS_FILE, 'utf8'));
+    }
+  } catch (err) {
+    // Ignore
+  }
+  return { gates: {}, lastRun: null };
+}
+
+/**
+ * Save gate status to file
+ */
+function saveStatus(status) {
+  try {
+    const dir = path.dirname(STATUS_FILE);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(STATUS_FILE, JSON.stringify(status, null, 2), 'utf8');
+  } catch (err) {
+    console.error('Failed to save status:', err.message);
+  }
+}
+
+/**
+ * Record gate bypass to audit trail
+ */
+function recordBypass(gateId, reason) {
+  const audit = {
+    gate: gateId,
+    action: 'bypass',
+    reason,
+    bypassedBy: process.env.USER || process.env.USERNAME || 'unknown',
+    timestamp: new Date().toISOString()
+  };
+
+  let auditTrail = [];
+  try {
+    if (fs.existsSync(AUDIT_FILE)) {
+      auditTrail = JSON.parse(fs.readFileSync(AUDIT_FILE, 'utf8'));
+    }
+  } catch (err) {
+    // Ignore
+  }
+
+  auditTrail.push(audit);
+  fs.writeFileSync(AUDIT_FILE, JSON.stringify(auditTrail, null, 2), 'utf8');
+  console.warn(`[GATE BYPASS] ${gateId} bypassed: ${reason}`);
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  const status = loadStatus();
+
+  // Check for bypass flag
+  const bypassIdx = args.indexOf('--bypass');
+  if (bypassIdx !== -1 && args[bypassIdx + 1]) {
+    const reason = args[bypassIdx + 1];
+    const gateIdx = args.indexOf('--gate');
+    if (gateIdx !== -1 && args[gateIdx + 1]) {
+      recordBypass(args[gateIdx + 1], reason);
+    } else {
+      console.error('Error: --bypass requires --gate <gate-id>');
+      process.exit(1);
+    }
+  }
+
+  // Execute all gates
+  const results = {};
+  const startTime = Date.now();
+
+  console.log('Executing quality gates...');
+  console.log('');
+
+  for (const [gateId] of qg.gates || []) {
+    try {
+      const result = await qg.execute(gateId);
+      results[gateId] = {
+        passed: result.passed,
+        timestamp: new Date().toISOString(),
+        errors: result.errors || [],
+        warnings: result.warnings || []
+      };
+
+      const icon = result.passed ? '✓' : '✗';
+      console.log(`${icon} ${gateId}`);
+
+      if (result.warnings && result.warnings.length > 0) {
+        result.warnings.forEach(w => console.warn(`  ⚠ ${w}`));
+      }
+    } catch (err) {
+      results[gateId] = {
+        passed: false,
+        timestamp: new Date().toISOString(),
+        errors: [err.message],
+        warnings: []
+      };
+      console.log(`✗ ${gateId}: ${err.message}`);
+    }
+  }
+
+  const duration = Date.now() - startTime;
+  status.lastRun = new Date().toISOString();
+  status.gates = results;
+  status.duration = duration;
+  saveStatus(status);
+
+  console.log('');
+  console.log(`Quality gates completed in ${(duration / 1000).toFixed(1)}s`);
+
+  // Check for failures
+  const failed = Object.entries(results).filter(([_, r]) => !r.passed);
+  if (failed.length > 0) {
+    console.log('');
+    console.log('Failed gates:');
+    failed.forEach(([gateId, result]) => {
+      console.log(`  - ${gateId}: ${result.errors.join(', ')}`);
+    });
+    console.log('');
+    console.log('Use --bypass "reason" to bypass a gate (requires audit trail)');
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log('All quality gates passed ✓');
+}
+
+// Handle pre-commit mode
+if (process.argv.includes('--pre-commit')) {
+  main().catch(err => {
+    console.error('Gate execution failed:', err.message);
+    process.exit(1);
+  });
+}
+
+// Handle status mode
+if (process.argv.includes('--status')) {
+  const status = loadStatus();
+  console.log('');
+  console.log('Quality Gate Status');
+  console.log('═══════════════════');
+  console.log('');
+
+  if (!status.lastRun) {
+    console.log('No gate runs recorded');
+  } else {
+    console.log(`Last run: ${new Date(status.lastRun).toLocaleString()}`);
+    console.log(`Duration: ${status.duration || 0}ms`);
+    console.log('');
+
+    const passed = Object.values(status.gates).filter(g => g.passed).length;
+    const failed = Object.values(status.gates).filter(g => !g.passed).length;
+    console.log(`Results: ${passed} passed, ${failed} failed`);
+  }
+  console.log('');
+  process.exit(0);
+}
+
+// Default: don't run, just export
+module.exports = { QualityGate, recordBypass, loadStatus, saveStatus };

package/bin/lib/gates/README.md

@@ -0,0 +1,374 @@
+# Quality Gate Implementation Guide
+
+This guide explains how to implement quality gates using the Quality Gate Coordinator.
+
+## Overview
+
+The Quality Gate Coordinator provides a central registry and execution engine for quality gates. Each gate:
+
+1. **Validates input** using Zod schemas
+2. **Executes checks** via a custom executor function
+3. **Returns structured results** with pass/fail status, errors, and warnings
+4. **Supports bypass** with mandatory audit trail
+
+## API Reference
+
+### `registerGate(id, schema, executor)`
+
+Registers a new quality gate.
+
+**Parameters:**
+- `id` (string): Unique gate identifier (e.g., `"requirement-completeness"`)
+- `schema` (ZodSchema): Zod schema for validating gate context
+- `executor` (Function): Async function that executes the gate logic
+
+**Example:**
+```javascript
+const { QualityGate, z } = require('./quality-gate.cjs');
+
+const gates = new QualityGate();
+
+gates.registerGate(
+  'requirement-completeness',
+  z.object({
+    requirements: z.array(z.object({
+      id: z.string(),
+      description: z.string(),
+      acceptanceCriteria: z.array(z.string()),
+    })),
+  }),
+  async (context) => {
+    const errors = [];
+    const warnings = [];
+
+    for (const req of context.requirements) {
+      if (!req.id || req.id.length === 0) {
+        errors.push({ path: 'requirements[].id', message: 'Requirement ID is required' });
+      }
+      if (req.acceptanceCriteria.length === 0) {
+        warnings.push(`Requirement ${req.id} has no acceptance criteria`);
+      }
+    }
+
+    return {
+      passed: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+);
+```
+
+### `executeGate(id, context)`
+
+Executes a registered gate with the provided context.
+
+**Parameters:**
+- `id` (string): Gate identifier
+- `context` (any): Context data to validate and pass to executor
+
+**Returns:** `Promise<ExecutionResult>`
+```javascript
+{
+  passed: boolean,
+  errors: Array<{ path: string, message: string }>,
+  warnings: Array<string>,
+}
+```
+
+**Example:**
+```javascript
+const result = await gates.executeGate('requirement-completeness', {
+  requirements: [
+    {
+      id: 'REQ-001',
+      description: 'User can log in',
+      acceptanceCriteria: ['Given valid credentials', 'When login form submitted', 'Then user is authenticated'],
+    },
+  ],
+});
+
+if (result.passed) {
+  console.log('Gate passed!');
+} else {
+  console.error('Gate failed:', result.errors);
+}
+```
+
+### `bypassGate(id, reason)`
+
+Bypasses a gate with a mandatory audit reason.
+
+**Parameters:**
+- `id` (string): Gate identifier
+- `reason` (string): Non-empty reason for bypass (logged to audit trail)
+
+**Example:**
+```javascript
+// Bypass with explicit reason (required)
+gates.bypassGate('security-baseline', 'MVP tier - security audit deferred to Phase 40');
+
+// This will throw an error (empty reason not allowed)
+gates.bypassGate('security-baseline', ''); // Error!
+```
+
+### `getGateStatus(id)`
+
+Returns the current status of a gate.
+
+**Parameters:**
+- `id` (string): Gate identifier
+
+**Returns:** `GateStatus`
+```javascript
+{
+  state: 'registered' | 'passed' | 'failed' | 'bypassed',
+  id: string,
+  registeredAt?: Date,
+  executedAt?: Date,
+  bypassedAt?: Date,
+  bypassReason?: string,
+  errors?: Array<{ path: string, message: string }>,
+  warnings?: Array<string>,
+}
+```
+
+**Example:**
+```javascript
+const status = gates.getGateStatus('requirement-completeness');
+console.log(`Gate state: ${status.state}`);
+```
+
+## Gate Implementation Patterns
+
+### Pattern 1: Simple Validation Gate
+
+```javascript
+gates.registerGate(
+  'plan-completeness',
+  z.object({
+    tasks: z.array(z.object({
+      id: z.string(),
+      name: z.string(),
+      action: z.string(),
+    })),
+  }),
+  async (context) => {
+    const errors = [];
+
+    if (context.tasks.length === 0) {
+      errors.push({ path: 'tasks', message: 'At least one task is required' });
+    }
+
+    return {
+      passed: errors.length === 0,
+      errors,
+      warnings: [],
+    };
+  }
+);
+```
+
+### Pattern 2: Multi-Check Gate
+
+```javascript
+gates.registerGate(
+  'code-quality',
+  z.object({
+    files: z.array(z.string()),
+    metrics: z.object({
+      complexity: z.number(),
+      coverage: z.number(),
+    }),
+  }),
+  async (context) => {
+    const errors = [];
+    const warnings = [];
+
+    // Check 1: Complexity threshold
+    if (context.metrics.complexity > 10) {
+      errors.push({ path: 'metrics.complexity', message: 'Cyclomatic complexity exceeds threshold (10)' });
+    }
+
+    // Check 2: Test coverage
+    if (context.metrics.coverage < 80) {
+      warnings.push(`Test coverage is ${context.metrics.coverage}%, recommended: 80%`);
+    }
+
+    // Check 3: File count
+    if (context.files.length > 50) {
+      warnings.push(`Large change set: ${context.files.length} files modified`);
+    }
+
+    return {
+      passed: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+);
+```
+
+### Pattern 3: External Tool Integration Gate
+
+```javascript
+const { exec } = require('child_process');
+const { promisify } = require('util');
+const execAsync = promisify(exec);
+
+gates.registerGate(
+  'security-scan',
+  z.object({
+    projectPath: z.string(),
+  }),
+  async (context) => {
+    const errors = [];
+    const warnings = [];
+
+    try {
+      // Run npm audit
+      const { stdout } = await execAsync('npm audit --json', {
+        cwd: context.projectPath,
+      });
+      const audit = JSON.parse(stdout);
+
+      if (audit.metadata.vulnerabilities.critical > 0) {
+        errors.push({
+          path: 'dependencies',
+          message: `Found ${audit.metadata.vulnerabilities.critical} critical vulnerabilities`,
+        });
+      }
+
+      if (audit.metadata.vulnerabilities.high > 0) {
+        warnings.push(`Found ${audit.metadata.vulnerabilities.high} high severity vulnerabilities`);
+      }
+    } catch (err) {
+      if (err.stdout) {
+        const audit = JSON.parse(err.stdout);
+        if (audit.metadata.vulnerabilities.total > 0) {
+          warnings.push(`npm audit found ${audit.metadata.vulnerabilities.total} vulnerabilities`);
+        }
+      } else {
+        warnings.push('Could not run npm audit');
+      }
+    }
+
+    return {
+      passed: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+);
+```
+
+## Audit Trail
+
+All gate bypasses are logged to `.planning/gate-audit.json`:
+
+```json
+[
+  {
+    "gateId": "security-baseline",
+    "action": "bypass",
+    "reason": "MVP tier - security audit deferred to Phase 40",
+    "timestamp": "2026-03-21T10:30:00.000Z"
+  }
+]
+```
+
+## Error Handling
+
+### Schema Validation Errors
+
+When context fails schema validation, errors include field paths:
+
+```javascript
+const result = await gates.executeGate('requirement-completeness', {
+  requirements: [
+    { id: '', description: 'Test' }, // Missing ID
+  ],
+});
+
+// result.errors:
+// [
+//   { path: 'requirements.0.id', message: 'Required' },
+// ]
+```
+
+### Executor Errors
+
+If the executor throws an exception, it's caught and returned as an error:
+
+```javascript
+gates.registerGate(
+  'flaky-gate',
+  z.object({}),
+  async () => {
+    throw new Error('Something went wrong');
+  }
+);
+
+const result = await gates.executeGate('flaky-gate', {});
+// result.passed: false
+// result.errors: [{ path: 'executor', message: 'Something went wrong' }]
+```
+
+### Unregistered Gate
+
+Executing an unregistered gate throws an error:
+
+```javascript
+await gates.executeGate('nonexistent-gate', {});
+// Throws: Error: Gate not registered: nonexistent-gate
+```
+
+## Best Practices
+
+1. **Use descriptive gate IDs**: `requirement-completeness` not `gate1`
+2. **Define strict schemas**: Validate all required fields with Zod
+3. **Return structured errors**: Include field paths for easy debugging
+4. **Use warnings for non-blocking issues**: Distinguish between errors (block) and warnings (inform)
+5. **Document bypass reasons**: Always provide clear, actionable bypass reasons
+6. **Keep executors focused**: Each gate should check one quality dimension
+7. **Test gates independently**: Write unit tests for each gate executor
+
+## Integration with Phase Execution
+
+```javascript
+const { QualityGate, z } = require('./quality-gate.cjs');
+
+async function executePhase(phasePlan) {
+  const gates = new QualityGate();
+
+  // Register gates
+  gates.registerGate(/* ... */);
+
+  // Execute pre-execution gates
+  const preCheck = await gates.executeGate('plan-completeness', phasePlan);
+  if (!preCheck.passed) {
+    throw new Error(`Pre-check failed: ${JSON.stringify(preCheck.errors)}`);
+  }
+
+  // Execute phase tasks...
+
+  // Execute post-execution gates
+  const postCheck = await gates.executeGate('verification-complete', {
+    tasks: phasePlan.tasks,
+    summaries: taskSummaries,
+  });
+
+  if (!postCheck.passed) {
+    // Trigger gap closure workflow
+    console.error('Post-check failed:', postCheck.errors);
+  }
+
+  return postCheck;
+}
+```
+
+## See Also
+
+- Phase 34-03: Gate 1-2 Implementation (Requirement Completeness, Architecture Review)
+- Phase 34-04: Gate 3-4 Implementation (Code Quality, Security Baseline)
+- Phase 40: Gates 5-7 (Testing, Documentation, Release)