claude-flow-novice 1.5.4 → 1.5.6

package/scripts/monitor-migration.js

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+
+/**
+ * SDK Migration Monitoring Script
+ * Provides real-time monitoring and alerting during migration
+ */
+
+const { MetricsCollector, SDKDashboard } = require('../src/sdk/dashboard');
+const { defaultConfig } = require('../src/sdk/performance-config');
+const fs = require('fs').promises;
+const path = require('path');
+
+class MigrationMonitor {
+  constructor(config = {}) {
+    this.config = {
+      checkInterval: config.checkInterval || 60000, // 1 minute
+      alertThresholds: {
+        errorRate: 0.05,
+        validationFailureRate: 0.2,
+        responseTimeP95: 10000,
+        cacheHitRate: 0.3
+      },
+      ...config
+    };
+
+    this.collector = new MetricsCollector();
+    this.dashboard = new SDKDashboard(this.collector, {
+      port: config.dashboardPort || 3000,
+      updateInterval: 5000,
+      authentication: false
+    });
+
+    this.alerts = [];
+    this.metricsHistory = [];
+    this.isMonitoring = false;
+  }
+
+  async start() {
+    console.log('🚀 Starting SDK Migration Monitor...\n');
+
+    // Start dashboard
+    this.dashboard.start(() => {
+      console.log('✅ Dashboard started successfully\n');
+    });
+
+    // Start metrics collection
+    this.isMonitoring = true;
+    this.startMetricsCollection();
+
+    // Set up graceful shutdown
+    process.on('SIGINT', () => this.stop());
+    process.on('SIGTERM', () => this.stop());
+  }
+
+  async stop() {
+    console.log('\n🛑 Stopping migration monitor...');
+    this.isMonitoring = false;
+
+    // Save final metrics
+    await this.saveMetricsSnapshot();
+
+    // Stop dashboard
+    this.dashboard.stop();
+
+    console.log('✅ Monitor stopped');
+    process.exit(0);
+  }
+
+  startMetricsCollection() {
+    // Simulate metrics collection (replace with actual implementation)
+    const collectMetrics = async () => {
+      if (!this.isMonitoring) return;
+
+      try {
+        // Collect system metrics
+        const systemMetrics = await this.collectSystemMetrics();
+        this.recordSystemMetrics(systemMetrics);
+
+        // Collect application metrics
+        const appMetrics = await this.collectApplicationMetrics();
+        this.recordApplicationMetrics(appMetrics);
+
+        // Check thresholds and trigger alerts
+        await this.checkThresholds();
+
+        // Store metrics history
+        this.metricsHistory.push({
+          timestamp: Date.now(),
+          system: systemMetrics,
+          application: appMetrics
+        });
+
+        // Keep only last 1000 entries
+        if (this.metricsHistory.length > 1000) {
+          this.metricsHistory = this.metricsHistory.slice(-1000);
+        }
+
+        // Save snapshot periodically
+        if (this.metricsHistory.length % 10 === 0) {
+          await this.saveMetricsSnapshot();
+        }
+      } catch (error) {
+        console.error('Error collecting metrics:', error);
+      }
+
+      // Schedule next collection
+      setTimeout(collectMetrics, this.config.checkInterval);
+    };
+
+    collectMetrics();
+  }
+
+  async collectSystemMetrics() {
+    const os = require('os');
+
+    return {
+      cpu: this.getCPUUsage(),
+      memory: (1 - os.freemem() / os.totalmem()) * 100,
+      loadAverage: os.loadavg()[0],
+      uptime: os.uptime()
+    };
+  }
+
+  getCPUUsage() {
+    const cpus = require('os').cpus();
+    const totalIdle = cpus.reduce((acc, cpu) => acc + cpu.times.idle, 0);
+    const totalTick = cpus.reduce(
+      (acc, cpu) => acc + Object.values(cpu.times).reduce((a, b) => a + b, 0),
+      0
+    );
+    return ((1 - totalIdle / totalTick) * 100);
+  }
+
+  async collectApplicationMetrics() {
+    // In real implementation, collect from actual application
+    // For now, generate simulated metrics
+    return {
+      responseTime: Math.random() * 1000 + 200,
+      throughput: Math.floor(Math.random() * 100) + 50,
+      errorRate: Math.random() * 0.02,
+      cacheHitRate: 0.6 + Math.random() * 0.3,
+      validationSuccess: 0.9 + Math.random() * 0.09,
+      testPassRate: 0.95 + Math.random() * 0.04,
+      coverage: 80 + Math.random() * 15,
+      activeAgents: Math.floor(Math.random() * 5) + 2,
+      queuedTasks: Math.floor(Math.random() * 10)
+    };
+  }
+
+  recordSystemMetrics(metrics) {
+    this.collector.recordMetric('system', 'cpuUsage', metrics.cpu);
+    this.collector.recordMetric('system', 'memoryUsage', metrics.memory);
+    this.collector.recordMetric('system', 'activeAgents', metrics.activeAgents || 0);
+    this.collector.recordMetric('system', 'queuedTasks', metrics.queuedTasks || 0);
+  }
+
+  recordApplicationMetrics(metrics) {
+    this.collector.recordMetric('performance', 'responseTime', metrics.responseTime);
+    this.collector.recordMetric('performance', 'throughput', metrics.throughput);
+    this.collector.recordMetric('performance', 'errorRate', metrics.errorRate);
+    this.collector.recordMetric('performance', 'cacheHitRate', metrics.cacheHitRate);
+
+    this.collector.recordMetric('quality', 'validationSuccess', metrics.validationSuccess);
+    this.collector.recordMetric('quality', 'testPassRate', metrics.testPassRate);
+    this.collector.recordMetric('quality', 'coverageMetrics', metrics.coverage);
+
+    // Estimate token usage and cost
+    const estimatedTokens = metrics.throughput * 1000; // ~1k tokens per request
+    this.collector.recordMetric('cost', 'tokenUsage', estimatedTokens);
+    this.collector.metrics.cost.estimatedCost += estimatedTokens * 0.000003; // $3 per 1M tokens
+  }
+
+  async checkThresholds() {
+    const summary = this.collector.getSummary();
+
+    // Check error rate
+    if (summary.performance.errorRate > this.config.alertThresholds.errorRate) {
+      this.triggerAlert({
+        id: `error-rate-${Date.now()}`,
+        name: 'high-error-rate',
+        severity: 'critical',
+        message: `Error rate ${(summary.performance.errorRate * 100).toFixed(2)}% exceeds threshold ${(this.config.alertThresholds.errorRate * 100).toFixed(2)}%`,
+        metric: 'errorRate',
+        currentValue: summary.performance.errorRate,
+        threshold: this.config.alertThresholds.errorRate,
+        recommendation: 'Consider rolling back migration'
+      });
+    }
+
+    // Check validation failure rate
+    const validationFailureRate = 1 - summary.quality.validationSuccessRate;
+    if (validationFailureRate > this.config.alertThresholds.validationFailureRate) {
+      this.triggerAlert({
+        id: `validation-failure-${Date.now()}`,
+        name: 'validation-failure-spike',
+        severity: 'high',
+        message: `Validation failure rate ${(validationFailureRate * 100).toFixed(2)}% exceeds threshold`,
+        metric: 'validationFailureRate',
+        currentValue: validationFailureRate,
+        threshold: this.config.alertThresholds.validationFailureRate,
+        recommendation: 'Review validation configuration'
+      });
+    }
+
+    // Check response time
+    if (summary.performance.responseTime.p95 > this.config.alertThresholds.responseTimeP95) {
+      this.triggerAlert({
+        id: `slow-response-${Date.now()}`,
+        name: 'slow-response-time',
+        severity: 'warning',
+        message: `P95 response time ${summary.performance.responseTime.p95.toFixed(0)}ms exceeds threshold`,
+        metric: 'responseTimeP95',
+        currentValue: summary.performance.responseTime.p95,
+        threshold: this.config.alertThresholds.responseTimeP95,
+        recommendation: 'Check for performance bottlenecks'
+      });
+    }
+
+    // Check cache hit rate
+    if (summary.performance.cacheHitRate < this.config.alertThresholds.cacheHitRate) {
+      this.triggerAlert({
+        id: `low-cache-${Date.now()}`,
+        name: 'low-cache-hit-rate',
+        severity: 'warning',
+        message: `Cache hit rate ${(summary.performance.cacheHitRate * 100).toFixed(1)}% below threshold`,
+        metric: 'cacheHitRate',
+        currentValue: summary.performance.cacheHitRate,
+        threshold: this.config.alertThresholds.cacheHitRate,
+        recommendation: 'Review cache configuration'
+      });
+    }
+  }
+
+  triggerAlert(alert) {
+    // Deduplicate alerts (don't trigger same alert multiple times)
+    const existingAlert = this.alerts.find(
+      a => a.name === alert.name && !a.resolved && Date.now() - a.timestamp < 300000
+    );
+
+    if (existingAlert) return;
+
+    // Add to collector
+    this.collector.addAlert(alert);
+    this.alerts.push(alert);
+
+    // Print to console
+    const icon = alert.severity === 'critical' ? '🚨' : alert.severity === 'high' ? '⚠️' : '⚡';
+    console.log(`\n${icon} ALERT: ${alert.name}`);
+    console.log(`   ${alert.message}`);
+    console.log(`   Recommendation: ${alert.recommendation}\n`);
+
+    // Write to file
+    this.saveAlert(alert);
+  }
+
+  async saveAlert(alert) {
+    const alertsFile = path.join(__dirname, '../logs/alerts.json');
+
+    try {
+      let alerts = [];
+      try {
+        const content = await fs.readFile(alertsFile, 'utf8');
+        alerts = JSON.parse(content);
+      } catch (err) {
+        // File doesn't exist yet
+      }
+
+      alerts.push(alert);
+
+      await fs.writeFile(alertsFile, JSON.stringify(alerts, null, 2));
+    } catch (error) {
+      console.error('Error saving alert:', error);
+    }
+  }
+
+  async saveMetricsSnapshot() {
+    const summary = this.collector.getSummary();
+    const snapshotFile = path.join(__dirname, '../.metrics-snapshot');
+
+    try {
+      await fs.writeFile(snapshotFile, JSON.stringify(summary, null, 2));
+    } catch (error) {
+      console.error('Error saving metrics snapshot:', error);
+    }
+  }
+
+  generateReport() {
+    const summary = this.collector.getSummary();
+
+    console.log('\n' + '='.repeat(80));
+    console.log('SDK MIGRATION MONITORING REPORT');
+    console.log('='.repeat(80));
+
+    console.log('\n📊 Performance Metrics:');
+    console.log(`   Response Time (Avg): ${summary.performance.responseTime.avg.toFixed(0)}ms`);
+    console.log(`   Response Time (P95): ${summary.performance.responseTime.p95.toFixed(0)}ms`);
+    console.log(`   Error Rate: ${(summary.performance.errorRate * 100).toFixed(2)}%`);
+    console.log(`   Cache Hit Rate: ${(summary.performance.cacheHitRate * 100).toFixed(1)}%`);
+
+    console.log('\n💰 Cost Metrics:');
+    console.log(`   Total Tokens: ${summary.cost.totalTokens.toLocaleString()}`);
+    console.log(`   Estimated Cost: $${summary.cost.estimatedCost.toFixed(2)}`);
+    console.log(`   Cache Savings: $${summary.cost.savingsFromCache.toFixed(2)}`);
+
+    console.log('\n✅ Quality Metrics:');
+    console.log(`   Validation Success: ${(summary.quality.validationSuccessRate * 100).toFixed(1)}%`);
+    console.log(`   Test Pass Rate: ${summary.quality.averageTestPassRate.toFixed(1)}%`);
+    console.log(`   Coverage: ${summary.quality.averageCoverage.toFixed(1)}%`);
+
+    console.log('\n🔔 Alerts:');
+    console.log(`   Active: ${summary.alerts.active}`);
+    console.log(`   Total: ${summary.alerts.total}`);
+
+    console.log('\n' + '='.repeat(80));
+    console.log(`Uptime: ${summary.uptime.formatted}`);
+    console.log(`Dashboard: http://localhost:${this.dashboard.config.port}`);
+    console.log('='.repeat(80) + '\n');
+  }
+}
+
+// CLI
+if (require.main === module) {
+  const monitor = new MigrationMonitor({
+    checkInterval: process.env.CHECK_INTERVAL || 60000,
+    dashboardPort: process.env.DASHBOARD_PORT || 3000
+  });
+
+  monitor.start().catch(err => {
+    console.error('Failed to start monitor:', err);
+    process.exit(1);
+  });
+
+  // Generate report every 5 minutes
+  setInterval(() => {
+    monitor.generateReport();
+  }, 300000);
+}
+
+module.exports = MigrationMonitor;

package/scripts/rollback-sdk.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+
+# Claude Agent SDK - Rollback Script
+# Instant rollback of SDK integration
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+BACKUP_DIR="$PROJECT_ROOT/.sdk-backup"
+LOG_FILE="$PROJECT_ROOT/sdk-rollback.log"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log() {
+    echo -e "${BLUE}[$(date +'%Y-%m-%d %H:%M:%S')]${NC} $1" | tee -a "$LOG_FILE"
+}
+
+error() {
+    echo -e "${RED}[ERROR]${NC} $1" | tee -a "$LOG_FILE"
+}
+
+success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1" | tee -a "$LOG_FILE"
+}
+
+echo "=== SDK Rollback Log ===" > "$LOG_FILE"
+log "Starting SDK rollback..."
+
+# Disable SDK in environment
+log "Disabling SDK integration..."
+if [ -f "$PROJECT_ROOT/.env" ]; then
+    sed -i.bak '/^# Claude Agent SDK Configuration/,/^$/d' "$PROJECT_ROOT/.env"
+    sed -i.bak '/^ENABLE_SDK/d' "$PROJECT_ROOT/.env"
+    sed -i.bak '/^SDK_/d' "$PROJECT_ROOT/.env"
+    success "SDK environment variables removed"
+fi
+
+# Restore backup if needed
+if [ -f "$BACKUP_DIR/.env.backup" ]; then
+    log "Restoring environment from backup..."
+    cp "$BACKUP_DIR/.env.backup" "$PROJECT_ROOT/.env"
+    success "Environment restored"
+fi
+
+success "Rollback complete!"
+
+cat <<EOF
+
+╔══════════════════════════════════════════════════════════════╗
+║            SDK Rollback Successful                           ║
+╚══════════════════════════════════════════════════════════════╝
+
+✅ SDK Integration: DISABLED
+✅ System: Restored to pre-SDK state
+
+📁 Rollback log: $LOG_FILE
+
+EOF
+
+log "Rollback complete. System restored."

package/scripts/verify-sdk-phase1.cjs

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+
+/**
+ * SDK Phase 1 Verification Script
+ *
+ * Verifies that Phase 1 implementation is complete and functional
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+console.log('\n' + '='.repeat(70));
+console.log('🔍 CLAUDE AGENT SDK - PHASE 1 VERIFICATION');
+console.log('='.repeat(70) + '\n');
+
+let allPassed = true;
+const results = [];
+
+function check(name, condition, details = '') {
+  const passed = condition;
+  results.push({ name, passed, details });
+
+  if (passed) {
+    console.log(`✅ ${name}`);
+    if (details) console.log(`   ${details}`);
+  } else {
+    console.log(`❌ ${name}`);
+    if (details) console.log(`   ${details}`);
+    allPassed = false;
+  }
+}
+
+// 1. Check package installation
+console.log('\n📦 CHECKING PACKAGE INSTALLATION\n');
+
+try {
+  const packageJson = require('../package.json');
+  check(
+    'Package.json exists',
+    true,
+    'Located at root directory'
+  );
+
+  check(
+    '@anthropic-ai/claude-agent-sdk installed',
+    packageJson.dependencies['@anthropic-ai/claude-agent-sdk'] !== undefined,
+    `Version: ${packageJson.dependencies['@anthropic-ai/claude-agent-sdk']}`
+  );
+} catch (error) {
+  check('Package.json readable', false, error.message);
+}
+
+// 2. Check SDK files
+console.log('\n📂 CHECKING SDK FILES\n');
+
+const requiredFiles = [
+  { path: 'src/sdk/config.cjs', desc: 'SDK configuration' },
+  { path: 'src/sdk/monitor.cjs', desc: 'Token usage monitoring' },
+  { path: 'src/sdk/index.cjs', desc: 'Main integration layer' }
+];
+
+requiredFiles.forEach(({ path: filePath, desc }) => {
+  const fullPath = path.join(__dirname, '..', filePath);
+  const exists = fs.existsSync(fullPath);
+  const size = exists ? fs.statSync(fullPath).size : 0;
+
+  check(
+    `${filePath} exists`,
+    exists,
+    `${desc} - ${(size / 1024).toFixed(1)} KB`
+  );
+});
+
+// 3. Check test files
+console.log('\n🧪 CHECKING TEST FILES\n');
+
+const testFile = path.join(__dirname, '../tests/sdk-integration.test.js');
+check(
+  'tests/sdk-integration.test.js exists',
+  fs.existsSync(testFile),
+  'Phase 1 test suite'
+);
+
+// 4. Check documentation
+console.log('\n📚 CHECKING DOCUMENTATION\n');
+
+const docFiles = [
+  'docs/sdk-integration-phase1.md',
+  'docs/sdk-phase1-summary.md'
+];
+
+docFiles.forEach((docFile) => {
+  const fullPath = path.join(__dirname, '..', docFile);
+  const exists = fs.existsSync(fullPath);
+
+  check(
+    `${docFile} exists`,
+    exists,
+    exists ? `${(fs.statSync(fullPath).size / 1024).toFixed(1)} KB` : ''
+  );
+});
+
+// 5. Check environment configuration
+console.log('\n⚙️  CHECKING ENVIRONMENT CONFIGURATION\n');
+
+const envFile = path.join(__dirname, '../.env');
+if (fs.existsSync(envFile)) {
+  const envContent = fs.readFileSync(envFile, 'utf-8');
+
+  const envVars = [
+    'ENABLE_SDK_CACHING',
+    'ENABLE_CONTEXT_EDITING',
+    'SDK_INTEGRATION_MODE',
+    'ENABLE_SDK_INTEGRATION'
+  ];
+
+  envVars.forEach((varName) => {
+    check(
+      `${varName} in .env`,
+      envContent.includes(varName),
+      `Environment variable configured`
+    );
+  });
+} else {
+  check('.env file exists', false, 'Environment file not found');
+}
+
+// 6. Test SDK loading
+console.log('\n🔧 TESTING SDK LOADING\n');
+
+try {
+  const sdk = require('../src/sdk/index.cjs');
+
+  check(
+    'SDK module loads',
+    true,
+    'No syntax errors'
+  );
+
+  check(
+    'SDK exports initialize',
+    typeof sdk.initialize === 'function',
+    'Initialize function available'
+  );
+
+  check(
+    'SDK exports monitoring',
+    typeof sdk.getMonitor === 'function',
+    'Monitoring functions available'
+  );
+
+  check(
+    'SDK exports config',
+    typeof sdk.getSDKConfig === 'function',
+    'Configuration functions available'
+  );
+
+  check(
+    'TOKEN_COSTS defined',
+    sdk.TOKEN_COSTS !== undefined,
+    `Input: $${sdk.TOKEN_COSTS.input}, Cached: $${sdk.TOKEN_COSTS.cached}`
+  );
+} catch (error) {
+  check('SDK module loads', false, error.message);
+}
+
+// 7. Test monitor functionality
+console.log('\n📊 TESTING MONITOR FUNCTIONALITY\n');
+
+try {
+  const { SDKMonitor } = require('../src/sdk/index.cjs');
+
+  const monitor = new SDKMonitor({ persistMetrics: false });
+
+  check(
+    'Monitor instantiates',
+    monitor !== null,
+    'Monitor object created'
+  );
+
+  check(
+    'Monitor tracks metrics',
+    monitor.metrics !== undefined,
+    'Metrics object exists'
+  );
+
+  check(
+    'Monitor calculates savings',
+    typeof monitor.calculateSavings === 'function',
+    'Savings calculation available'
+  );
+
+  // Test savings calculation
+  const savings = monitor.calculateSavings(1000);
+  check(
+    'Savings calculation works',
+    savings > 0,
+    `1000 tokens → ${savings.toFixed(0)} saved`
+  );
+
+  // Test report generation
+  monitor.metrics.tokensBefore = 10000;
+  monitor.metrics.tokensAfter = 1000;
+  monitor.metrics.totalCostSaved = 0.027;
+  monitor.metrics.operations = 5;
+
+  const report = monitor.getSavingsReport();
+  check(
+    'Report generation works',
+    report.summary !== undefined,
+    `Operations: ${report.summary.operations}, Savings: ${report.summary.costSaved}`
+  );
+} catch (error) {
+  check('Monitor functionality', false, error.message);
+}
+
+// 8. Test configuration
+console.log('\n⚙️  TESTING CONFIGURATION\n');
+
+try {
+  const { getSDKConfig, isSDKEnabled } = require('../src/sdk/index.cjs');
+
+  const config = getSDKConfig();
+
+  check(
+    'Config loads',
+    config !== null,
+    'Configuration object returned'
+  );
+
+  check(
+    'Config has required fields',
+    config.caching !== undefined && config.contextEditing !== undefined,
+    `Caching: ${config.caching}, Context: ${config.contextEditing}`
+  );
+
+  // Test enable/disable
+  const originalMode = process.env.SDK_INTEGRATION_MODE;
+
+  process.env.SDK_INTEGRATION_MODE = 'parallel';
+  const enabledParallel = isSDKEnabled();
+
+  process.env.SDK_INTEGRATION_MODE = 'disabled';
+  const disabledMode = isSDKEnabled();
+
+  process.env.SDK_INTEGRATION_MODE = originalMode;
+
+  check(
+    'Enable/disable works',
+    enabledParallel === true && disabledMode === false,
+    'Integration mode control functional'
+  );
+} catch (error) {
+  check('Configuration', false, error.message);
+}
+
+// Summary
+console.log('\n' + '='.repeat(70));
+console.log('📋 VERIFICATION SUMMARY');
+console.log('='.repeat(70) + '\n');
+
+const passed = results.filter(r => r.passed).length;
+const total = results.length;
+const percentage = ((passed / total) * 100).toFixed(1);
+
+console.log(`Tests Passed: ${passed}/${total} (${percentage}%)`);
+
+if (allPassed) {
+  console.log('\n✅ PHASE 1 IMPLEMENTATION VERIFIED SUCCESSFULLY\n');
+  console.log('All components are in place and functional:');
+  console.log('  • SDK configuration with extended caching and context editing');
+  console.log('  • Token usage monitoring and cost tracking');
+  console.log('  • Integration layer with easy-to-use API');
+  console.log('  • Test suite for validation');
+  console.log('  • Comprehensive documentation');
+  console.log('  • Environment configuration');
+  console.log('\nNext steps:');
+  console.log('  1. Set CLAUDE_API_KEY in .env');
+  console.log('  2. Run: node src/sdk/index.cjs');
+  console.log('  3. Start using SDK with executeWithTracking()');
+  console.log('  4. Monitor savings with getSavingsReport()');
+} else {
+  console.log('\n⚠️  SOME VERIFICATIONS FAILED\n');
+  console.log('Please review the failed checks above and ensure:');
+  console.log('  • All files are created in correct locations');
+  console.log('  • Package dependencies are installed');
+  console.log('  • Environment variables are configured');
+  console.log('  • No syntax errors in SDK modules');
+}
+
+console.log('\n' + '='.repeat(70) + '\n');
+
+process.exit(allPassed ? 0 : 1);