@devran-ai/kit 4.1.0

package/lib/circuit-breaker.js

@@ -0,0 +1,195 @@
+/**
+ * Devran AI Kit — Circuit Breaker
+ *
+ * Implements the circuit breaker pattern for protecting external
+ * operations (git clones, network requests) from cascading failures.
+ *
+ * States: CLOSED (normal) → OPEN (failing) → HALF_OPEN (testing recovery)
+ *
+ * @module lib/circuit-breaker
+ * @author Emre Dursun
+ * @since v3.2.0
+ */
+
+'use strict';
+
+/** @typedef {'CLOSED' | 'OPEN' | 'HALF_OPEN'} CircuitState */
+
+/**
+ * @typedef {object} CircuitBreakerOptions
+ * @property {number} [failureThreshold=3] - Failures before opening circuit
+ * @property {number} [resetTimeoutMs=60000] - Time before attempting recovery (ms)
+ * @property {number} [halfOpenMaxAttempts=1] - Max attempts in half-open state
+ */
+
+/**
+ * @typedef {object} CircuitBreakerState
+ * @property {CircuitState} state - Current circuit state
+ * @property {number} failureCount - Consecutive failure count
+ * @property {number} successCount - Consecutive success count in half-open
+ * @property {number | null} lastFailureTime - Timestamp of last failure
+ * @property {number} totalFailures - Lifetime failure count
+ * @property {number} totalSuccesses - Lifetime success count
+ */
+
+/**
+ * Creates a new circuit breaker instance.
+ *
+ * @param {string} name - Circuit breaker name for identification
+ * @param {CircuitBreakerOptions} [options] - Configuration options
+ * @returns {{ execute: Function, getState: Function, reset: Function }}
+ */
+function createCircuitBreaker(name, options = {}) {
+  const failureThreshold = options.failureThreshold || 3;
+  const resetTimeoutMs = options.resetTimeoutMs || 60000;
+  const halfOpenMaxAttempts = options.halfOpenMaxAttempts || 1;
+
+  /** @type {CircuitBreakerState} */
+  const state = {
+    state: 'CLOSED',
+    failureCount: 0,
+    successCount: 0,
+    lastFailureTime: null,
+    totalFailures: 0,
+    totalSuccesses: 0,
+  };
+
+  /**
+   * Checks if the circuit should transition from OPEN to HALF_OPEN.
+   *
+   * @returns {boolean}
+   */
+  function shouldAttemptReset() {
+    if (state.state !== 'OPEN' || state.lastFailureTime === null) {
+      return false;
+    }
+    return (Date.now() - state.lastFailureTime) >= resetTimeoutMs;
+  }
+
+  /**
+   * Records a successful operation.
+   *
+   * @returns {void}
+   */
+  function onSuccess() {
+    state.totalSuccesses += 1;
+
+    if (state.state === 'HALF_OPEN') {
+      state.successCount += 1;
+      if (state.successCount >= halfOpenMaxAttempts) {
+        state.state = 'CLOSED';
+        state.failureCount = 0;
+        state.successCount = 0;
+        state.lastFailureTime = null;
+      }
+    } else {
+      state.failureCount = 0;
+    }
+  }
+
+  /**
+   * Records a failed operation.
+   *
+   * @returns {void}
+   */
+  function onFailure() {
+    state.totalFailures += 1;
+    state.failureCount += 1;
+    state.lastFailureTime = Date.now();
+
+    if (state.state === 'HALF_OPEN') {
+      state.state = 'OPEN';
+      state.successCount = 0;
+    } else if (state.failureCount >= failureThreshold) {
+      state.state = 'OPEN';
+    }
+  }
+
+  /**
+   * Executes an operation through the circuit breaker.
+   *
+   * @param {Function} operation - Async or sync operation to execute
+   * @returns {*} Result of the operation
+   * @throws {Error} If circuit is open or operation fails
+   */
+  function execute(operation) {
+    if (state.state === 'OPEN') {
+      if (shouldAttemptReset()) {
+        state.state = 'HALF_OPEN';
+        state.successCount = 0;
+      } else {
+        throw new Error(
+          `Circuit breaker "${name}" is OPEN — operation rejected. ` +
+          `${state.failureCount} consecutive failures. ` +
+          `Will retry after ${Math.ceil((resetTimeoutMs - (Date.now() - state.lastFailureTime)) / 1000)}s.`
+        );
+      }
+    }
+
+    try {
+      const result = operation();
+      onSuccess();
+      return result;
+    } catch (error) {
+      onFailure();
+      throw error;
+    }
+  }
+
+  /**
+   * Executes an asynchronous operation through the circuit breaker.
+   * Properly tracks Promise resolution/rejection for state management.
+   *
+   * @param {Function} operation - Async operation to execute (must return a Promise)
+   * @returns {Promise<*>} Result of the operation
+   * @throws {Error} If circuit is open or operation fails
+   */
+  async function executeAsync(operation) {
+    if (state.state === 'OPEN') {
+      if (shouldAttemptReset()) {
+        state.state = 'HALF_OPEN';
+        state.successCount = 0;
+      } else {
+        throw new Error(
+          `Circuit breaker "${name}" is OPEN — operation rejected. ` +
+          `${state.failureCount} consecutive failures. ` +
+          `Will retry after ${Math.ceil((resetTimeoutMs - (Date.now() - state.lastFailureTime)) / 1000)}s.`
+        );
+      }
+    }
+
+    try {
+      const result = await operation();
+      onSuccess();
+      return result;
+    } catch (error) {
+      onFailure();
+      throw error;
+    }
+  }
+
+  /**
+   * Returns a snapshot of the circuit breaker state.
+   *
+   * @returns {CircuitBreakerState & { name: string }}
+   */
+  function getState() {
+    return { name, ...state };
+  }
+
+  /**
+   * Resets the circuit breaker to CLOSED state.
+   *
+   * @returns {void}
+   */
+  function reset() {
+    state.state = 'CLOSED';
+    state.failureCount = 0;
+    state.successCount = 0;
+    state.lastFailureTime = null;
+  }
+
+  return { execute, executeAsync, getState, reset };
+}
+
+module.exports = { createCircuitBreaker };

package/lib/cli-commands.js

@@ -0,0 +1,322 @@
+/**
+ * Devran AI Kit — CLI Command Handlers (Phase 4)
+ *
+ * Extracted command handlers to keep bin/kit.js under 800 lines.
+ * Handles: `market`, `heal`, and dashboard sections.
+ *
+ * @module lib/cli-commands
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+
+// ANSI colors (shared with kit.js)
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+};
+
+/**
+ * Marketplace CLI handler.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {string} subCommand - Sub-command: search, info, install, update
+ * @param {string} [argument] - Argument for the sub-command
+ * @param {object} [options] - CLI options
+ * @returns {void}
+ */
+function marketCommand(projectRoot, subCommand, argument, options = {}) {
+  const marketplace = require('./marketplace');
+
+  switch (subCommand) {
+    case 'search': {
+      if (!argument) {
+        console.log(`${colors.yellow}Usage: kit market search <query>${colors.reset}`);
+        return;
+      }
+      const results = marketplace.searchMarket(projectRoot, argument);
+      console.log(`\n${colors.bright}${colors.blue}═══ Marketplace Search: "${argument}" ═══${colors.reset}\n`);
+      if (results.length === 0) {
+        console.log(`   No plugins found matching "${argument}"`);
+      } else {
+        for (const entry of results) {
+          console.log(`   ${colors.green}${entry.name}${colors.reset} v${entry.version}`);
+          console.log(`   ${entry.description}`);
+          console.log(`   Tags: ${(entry.tags || []).join(', ')}`);
+          console.log('');
+        }
+      }
+      console.log(`   ${results.length} result(s)\n`);
+      break;
+    }
+
+    case 'info': {
+      if (!argument) {
+        console.log(`${colors.yellow}Usage: kit market info <plugin-name>${colors.reset}`);
+        return;
+      }
+      const info = marketplace.getMarketInfo(projectRoot, argument);
+      if (!info) {
+        console.log(`${colors.red}Plugin not found: ${argument}${colors.reset}`);
+        return;
+      }
+      console.log(`\n${colors.bright}${colors.blue}═══ Plugin: ${info.name} ═══${colors.reset}\n`);
+      console.log(`   Version:     ${info.version}`);
+      console.log(`   Author:      ${info.author}`);
+      console.log(`   Description: ${info.description}`);
+      console.log(`   Repository:  ${info.repository}`);
+      console.log(`   Tags:        ${(info.tags || []).join(', ')}\n`);
+      break;
+    }
+
+    case 'install': {
+      if (!argument) {
+        console.log(`${colors.yellow}Usage: kit market install <plugin-name>${colors.reset}`);
+        return;
+      }
+      console.log(`${colors.cyan}Installing ${argument}...${colors.reset}`);
+      const result = marketplace.installFromMarket(projectRoot, argument);
+      if (result.success) {
+        console.log(`${colors.green}✓ ${result.message}${colors.reset}`);
+      } else {
+        console.log(`${colors.red}✗ ${result.message}${colors.reset}`);
+      }
+      break;
+    }
+
+    case 'update': {
+      const force = options.force || false;
+      const result = marketplace.updateRegistryIndex(projectRoot, { force });
+      if (result.updated) {
+        console.log(`${colors.green}✓ Registry updated (${result.entryCount} entries)${colors.reset}`);
+      } else {
+        console.log(`${colors.yellow}Registry is fresh (${result.entryCount} entries). Use --force to update.${colors.reset}`);
+      }
+      break;
+    }
+
+    default:
+      console.log(`${colors.yellow}Usage: kit market <search|info|install|update> [arg]${colors.reset}`);
+      break;
+  }
+}
+
+/**
+ * Self-healing CLI handler.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {object} [options] - CLI options
+ * @param {string} [options.file] - Path to CI log file
+ * @param {boolean} [options.apply] - Apply patches (default: dry-run)
+ * @returns {void}
+ */
+function healCommand(projectRoot, options = {}) {
+  const selfHealing = require('./self-healing');
+  let ciOutput = '';
+
+  // Input source (E-3): file > stdin > last-saved
+  if (options.file) {
+    const filePath = path.resolve(options.file);
+    if (!fs.existsSync(filePath)) {
+      console.log(`${colors.red}✗ CI log file not found: ${filePath}${colors.reset}`);
+      process.exit(1);
+    }
+    ciOutput = fs.readFileSync(filePath, 'utf-8');
+  } else {
+    // Try last-saved CI output
+    const lastCiPath = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, 'last-ci-output.txt');
+    if (fs.existsSync(lastCiPath)) {
+      ciOutput = fs.readFileSync(lastCiPath, 'utf-8');
+    } else {
+      console.log(`${colors.yellow}No CI output found. Use: kit heal --file <path>${colors.reset}`);
+      return;
+    }
+  }
+
+  console.log(`\n${colors.bright}${colors.blue}═══ Self-Healing Pipeline ═══${colors.reset}\n`);
+
+  // Detect failures
+  const failures = selfHealing.detectFailure(ciOutput);
+
+  if (failures.length === 0) {
+    console.log(`   ${colors.green}✓ No failures detected — pipeline is healthy${colors.reset}\n`);
+    return;
+  }
+
+  console.log(`   ${colors.red}${failures.length} failure(s) detected${colors.reset}\n`);
+
+  // Diagnose and generate patches
+  for (const failure of failures) {
+    const diagnosis = selfHealing.diagnoseFailure(failure);
+    console.log(`   ${colors.yellow}[${failure.type.toUpperCase()}]${colors.reset} ${failure.message}`);
+    console.log(`   Diagnosis: ${diagnosis.category} — ${diagnosis.explanation}`);
+
+    if (diagnosis.autoFixable) {
+      const patch = selfHealing.generateFixPatch(failure, diagnosis);
+      if (patch) {
+        const dryRun = !options.apply;
+        const result = selfHealing.applyFixWithConfirmation(projectRoot, patch, { dryRun });
+        console.log(`   Patch ${patch.patchId}: ${dryRun ? 'DRY RUN' : result.applied ? 'APPLIED' : 'FAILED'}`);
+      }
+    } else {
+      console.log(`   ${colors.cyan}→ Manual review required${colors.reset}`);
+    }
+    console.log('');
+  }
+}
+
+/**
+ * Dashboard sections for Phase 4 features.
+ * Called by statusCommand() in kit.js.
+ *
+ * @param {string} projectRoot - Root directory
+ * @returns {void}
+ */
+function renderDashboardSections(projectRoot) {
+  // ═══ Reputation ═══
+  try {
+    const reputation = require('./agent-reputation');
+    const rankings = reputation.getRankings(projectRoot);
+
+    console.log(`\n${colors.bright}${colors.cyan}═══ Reputation ═══${colors.reset}`);
+
+    if (rankings.length === 0) {
+      console.log('   No reputation data yet');
+    } else {
+      for (const agent of rankings.slice(0, 5)) {
+        const trend = agent.trend;
+        console.log(`   ${colors.green}${agent.agent}${colors.reset} — Score: ${agent.score} ${trend} | Reliability: ${agent.reliability}%`);
+      }
+    }
+  } catch {
+    // Reputation module not available — silently skip
+  }
+
+  // ═══ Sprint ═══
+  try {
+    const engMgr = require('./engineering-manager');
+    const metrics = engMgr.getSprintMetrics(projectRoot);
+
+    console.log(`\n${colors.bright}${colors.cyan}═══ Sprint ═══${colors.reset}`);
+    console.log(`   Total Sprints: ${metrics.totalSprints}`);
+    console.log(`   Active Sprint: ${metrics.activeSprint ? metrics.activeSprint.name : 'none'}`);
+    console.log(`   Velocity:      ${metrics.velocity} tasks/sprint`);
+  } catch {
+    // Module not available — silently skip
+  }
+
+  // ═══ Health ═══
+  try {
+    const selfHealing = require('./self-healing');
+    const report = selfHealing.getHealingReport(projectRoot);
+
+    console.log(`\n${colors.bright}${colors.cyan}═══ Health ═══${colors.reset}`);
+    console.log(`   Total Heals:    ${report.totalHeals}`);
+    console.log(`   Success Rate:   ${report.successRate}%`);
+    console.log(`   Pending Patches: ${report.pendingPatches}`);
+  } catch {
+    // Module not available — silently skip
+  }
+}
+
+/**
+ * Health check CLI handler.
+ * Aggregates error budget, plugin integrity, config validation, and healing status.
+ *
+ * @param {string} projectRoot - Root directory
+ * @returns {{ healthy: boolean, checks: object[] }}
+ */
+function healthCommand(projectRoot) {
+  const checks = [];
+
+  // Error budget health
+  try {
+    const errorBudget = require('./error-budget');
+    const report = errorBudget.getBudgetReport(projectRoot);
+    checks.push({
+      name: 'Error Budget',
+      status: report.status,
+      healthy: report.status !== 'EXHAUSTED',
+      detail: report.violations.length > 0 ? `Violations: ${report.violations.join(', ')}` : 'All rates within thresholds',
+    });
+  } catch {
+    checks.push({ name: 'Error Budget', status: 'SKIPPED', healthy: true, detail: 'No reliability config found' });
+  }
+
+  // Plugin integrity
+  try {
+    const pluginVerifier = require('./plugin-verifier');
+    const result = pluginVerifier.verifyAllPlugins(projectRoot);
+    const pluginHealthy = result.invalid.length === 0;
+    checks.push({
+      name: 'Plugin Integrity',
+      status: pluginHealthy ? 'PASS' : 'FAIL',
+      healthy: pluginHealthy,
+      detail: `${result.valid} valid, ${result.invalid.length} invalid, ${result.unverified.length} unverified`,
+    });
+  } catch {
+    checks.push({ name: 'Plugin Integrity', status: 'SKIPPED', healthy: true, detail: 'Verifier not available' });
+  }
+
+  // Config validation
+  try {
+    const configValidator = require('./config-validator');
+    const result = configValidator.validateAllConfigs(projectRoot);
+    const invalidCount = result.totalConfigs - result.validConfigs;
+    const configHealthy = invalidCount === 0;
+    checks.push({
+      name: 'Config Validation',
+      status: configHealthy ? 'PASS' : 'FAIL',
+      healthy: configHealthy,
+      detail: `${result.validConfigs} valid, ${invalidCount} invalid of ${result.totalConfigs} configs`,
+    });
+  } catch {
+    checks.push({ name: 'Config Validation', status: 'SKIPPED', healthy: true, detail: 'Validator not available' });
+  }
+
+  // Self-healing status
+  try {
+    const selfHealing = require('./self-healing');
+    const report = selfHealing.getHealingReport(projectRoot);
+    checks.push({
+      name: 'Self-Healing',
+      status: report.pendingPatches > 0 ? 'WARNING' : 'PASS',
+      healthy: true,
+      detail: `${report.totalHeals} heals, ${report.successRate}% success, ${report.pendingPatches} pending`,
+    });
+  } catch {
+    checks.push({ name: 'Self-Healing', status: 'SKIPPED', healthy: true, detail: 'Healer not available' });
+  }
+
+  const healthy = checks.every((c) => c.healthy);
+
+  // Render output
+  console.log(`\n${colors.bright}${colors.blue}═══ Health Check ═══${colors.reset}\n`);
+  for (const check of checks) {
+    const icon = check.status === 'PASS' || check.status === 'HEALTHY' ? '✓' : check.status === 'FAIL' || check.status === 'EXHAUSTED' ? '✗' : '⚠';
+    const color = check.healthy ? 'green' : 'red';
+    console.log(`   ${colors[color]}${icon} ${check.name}: ${check.status}${colors.reset}`);
+    console.log(`     ${check.detail}`);
+  }
+  console.log('');
+  console.log(`   ${healthy ? `${colors.green}✅ All health checks passed` : `${colors.red}❌ Some health checks failed`}${colors.reset}\n`);
+
+  return { healthy, checks };
+}
+
+module.exports = {
+  marketCommand,
+  healCommand,
+  healthCommand,
+  renderDashboardSections,
+};