@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/bin/lib/finops/budget-enforcer.cjs

@@ -0,0 +1,126 @@
+/**
+ * Budget Enforcer — Enforces spending limits and auto-pauses over-budget operations
+ * Integrates with cost-tracker for budget ceiling enforcement
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class BudgetEnforcer {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.configPath = path.join(this.cwd, '.planning', 'config.json');
+  }
+
+  /**
+   * Check if budget is exceeded
+   * @param {number} currentCost - Current total cost
+   * @returns {Object} Budget status { ok, warning, exceeded, action }
+   */
+  checkBudget(currentCost) {
+    const config = this.loadConfig();
+    const ceiling = config.cost_tracking?.budget?.ceiling || null;
+    const warningThreshold = config.cost_tracking?.warning_threshold || 80;
+
+    if (!ceiling) {
+      return { ok: true, warning: false, exceeded: false, action: 'none' };
+    }
+
+    const percentage = (currentCost / ceiling) * 100;
+
+    if (percentage >= 100) {
+      return {
+        ok: false,
+        warning: false,
+        exceeded: true,
+        action: config.cost_tracking?.auto_pause ? 'pause' : 'alert',
+        percentage: Math.round(percentage)
+      };
+    }
+
+    if (percentage >= warningThreshold) {
+      return {
+        ok: true,
+        warning: true,
+        exceeded: false,
+        action: 'warn',
+        percentage: Math.round(percentage)
+      };
+    }
+
+    return { ok: true, warning: false, exceeded: false, action: 'none', percentage: Math.round(percentage) };
+  }
+
+  /**
+   * Enforce budget (exit if exceeded and auto_pause enabled)
+   * @param {number} currentCost - Current total cost
+   */
+  enforce(currentCost) {
+    const status = this.checkBudget(currentCost);
+
+    if (status.exceeded && status.action === 'pause') {
+      console.error(`Budget ceiling exceeded (${status.percentage}%) — operations paused`);
+      process.exit(1);
+    }
+
+    if (status.warning) {
+      console.warn(`Budget warning: ${status.percentage}% of ceiling used`);
+    }
+
+    return status;
+  }
+
+  /**
+   * Set budget ceiling
+   * @param {number} ceiling - Budget ceiling in USD
+   */
+  setCeiling(ceiling) {
+    const config = this.loadConfig();
+    if (!config.cost_tracking) config.cost_tracking = {};
+    if (!config.cost_tracking.budget) config.cost_tracking.budget = {};
+    config.cost_tracking.budget.ceiling = ceiling;
+    this.saveConfig(config);
+  }
+
+  /**
+   * Load config
+   * @returns {Object} Config
+   */
+  loadConfig() {
+    if (!fs.existsSync(this.configPath)) {
+      return { cost_tracking: { budget: {}, warning_threshold: 80 } };
+    }
+    return JSON.parse(fs.readFileSync(this.configPath, 'utf8'));
+  }
+
+  /**
+   * Save config
+   * @param {Object} config - Config to save
+   */
+  saveConfig(config) {
+    fs.writeFileSync(this.configPath, JSON.stringify(config, null, 2), 'utf8');
+  }
+}
+
+/**
+ * Check budget status
+ * @param {number} currentCost - Current cost
+ * @param {string} cwd - Working directory
+ * @returns {Object} Budget status
+ */
+function checkBudget(currentCost, cwd) {
+  const enforcer = new BudgetEnforcer(cwd);
+  return enforcer.checkBudget(currentCost);
+}
+
+/**
+ * Enforce budget
+ * @param {number} currentCost - Current cost
+ * @param {string} cwd - Working directory
+ */
+function enforce(currentCost, cwd) {
+  const enforcer = new BudgetEnforcer(cwd);
+  return enforcer.enforce(currentCost);
+}
+
+module.exports = { BudgetEnforcer, checkBudget, enforce };

package/ez-agents/bin/lib/finops/cost-reporter.cjs

@@ -0,0 +1,132 @@
+/**
+ * Cost Reporter — Cost breakdown by phase/operation/provider with trend analysis
+ * Generates detailed cost reports from cost-tracker data
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class CostReporter {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.metricsPath = path.join(this.cwd, '.planning', 'metrics.json');
+    this.reportsDir = path.join(this.cwd, '.planning', 'finops', 'reports');
+    this.ensureDir();
+  }
+
+  /**
+   * Generate cost breakdown report
+   * @param {Object} options - Report options
+   * @returns {Object} Cost report
+   */
+  generateReport(options = {}) {
+    const { CostTracker } = require('../cost-tracker.cjs');
+    const tracker = new CostTracker(this.cwd);
+    const data = tracker.aggregate();
+
+    const report = {
+      timestamp: new Date().toISOString(),
+      total: data.total,
+      byPhase: data.by_phase || {},
+      byProvider: data.by_provider || {},
+      trend: this.calculateTrend(data),
+      recommendations: this.generateRecommendations(data)
+    };
+
+    return report;
+  }
+
+  /**
+   * Save report to file
+   * @param {Object} report - Report to save
+   * @param {string} filename - Optional filename
+   * @returns {string} Path to saved report
+   */
+  saveReport(report, filename) {
+    const reportFilename = filename || `cost-${Date.now()}.json`;
+    const reportPath = path.join(this.reportsDir, reportFilename);
+
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf8');
+    return reportPath;
+  }
+
+  /**
+   * Calculate cost trend
+   * @param {Object} data - Aggregated cost data
+   * @returns {Array} Trend data
+   */
+  calculateTrend(data) {
+    // Placeholder - would track historical trend
+    return [{
+      timestamp: new Date().toISOString(),
+      total: data.total.cost || 0
+    }];
+  }
+
+  /**
+   * Generate cost optimization recommendations
+   * @param {Object} data - Cost data
+   * @returns {Array} Recommendations
+   */
+  generateRecommendations(data) {
+    const recommendations = [];
+
+    // Check for high-cost phases
+    for (const [phase, costs] of Object.entries(data.by_phase || {})) {
+      if (costs.cost > 10) {
+        recommendations.push({
+          category: 'phase',
+          phase,
+          suggestion: `High cost phase ($${costs.cost}) — review operation efficiency`
+        });
+      }
+    }
+
+    // Check for expensive providers
+    for (const [provider, costs] of Object.entries(data.by_provider || {})) {
+      if (costs.cost > 5) {
+        recommendations.push({
+          category: 'provider',
+          provider,
+          suggestion: `Consider alternative models for ${provider}`
+        });
+      }
+    }
+
+    return recommendations;
+  }
+
+  /**
+   * Ensure reports directory exists
+   */
+  ensureDir() {
+    if (!fs.existsSync(this.reportsDir)) {
+      fs.mkdirSync(this.reportsDir, { recursive: true });
+    }
+  }
+}
+
+/**
+ * Generate cost report
+ * @param {Object} options - Report options
+ * @param {string} cwd - Working directory
+ * @returns {Object} Cost report
+ */
+function generateReport(options = {}, cwd) {
+  const reporter = new CostReporter(cwd);
+  return reporter.generateReport(options);
+}
+
+/**
+ * Save cost report
+ * @param {Object} report - Report to save
+ * @param {string} filename - Filename
+ * @param {string} cwd - Working directory
+ * @returns {string} Path to saved report
+ */
+function saveReport(report, filename, cwd) {
+  const reporter = new CostReporter(cwd);
+  return reporter.saveReport(report, filename);
+}
+
+module.exports = { CostReporter, generateReport, saveReport };

package/ez-agents/bin/lib/finops/finops-analyzer.cjs

@@ -0,0 +1,112 @@
+/**
+ * FinOps Analyzer — Cloud resource cost analysis and rightsizing recommendations
+ * Analyzes resource usage and provides cost optimization recommendations
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class FinopsAnalyzer {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.costsPath = path.join(this.cwd, '.planning', 'finops', 'costs.json');
+    this.ensureFile();
+  }
+
+  /**
+   * Analyze cloud resource costs
+   * @param {Object} resources - Resource usage data
+   * @returns {Object} Cost analysis with recommendations
+   */
+  analyzeCosts(resources = {}) {
+    const analysis = {
+      timestamp: new Date().toISOString(),
+      totalCost: 0,
+      byResource: {},
+      byCategory: {},
+      recommendations: []
+    };
+
+    // Analyze each resource
+    for (const [name, resource] of Object.entries(resources)) {
+      const cost = resource.cost || 0;
+      const category = resource.category || 'other';
+
+      analysis.totalCost += cost;
+      analysis.byResource[name] = cost;
+
+      if (!analysis.byCategory[category]) {
+        analysis.byCategory[category] = 0;
+      }
+      analysis.byCategory[category] += cost;
+
+      // Generate rightsizing recommendations
+      if (resource.utilization < 30) {
+        analysis.recommendations.push({
+          resource: name,
+          type: 'rightsize',
+          reason: `Low utilization (${resource.utilization}%)`,
+          suggestion: 'Downsize instance or consolidate workloads',
+          potentialSavings: Math.round(cost * 0.4)
+        });
+      }
+    }
+
+    return analysis;
+  }
+
+  /**
+   * Get cost trend over time
+   * @returns {Array} Cost trend data
+   */
+  getTrend() {
+    if (!fs.existsSync(this.costsPath)) return [];
+    const costs = JSON.parse(fs.readFileSync(this.costsPath, 'utf8'));
+    return costs.trend || [];
+  }
+
+  /**
+   * Save cost data
+   * @param {Object} costData - Cost data to save
+   */
+  saveCostData(costData) {
+    const data = {
+      timestamp: new Date().toISOString(),
+      ...costData
+    };
+
+    let existing = { trend: [] };
+    if (fs.existsSync(this.costsPath)) {
+      existing = JSON.parse(fs.readFileSync(this.costsPath, 'utf8'));
+    }
+
+    existing.trend.push(data);
+    fs.writeFileSync(this.costsPath, JSON.stringify(existing, null, 2), 'utf8');
+  }
+
+  /**
+   * Ensure costs file exists
+   */
+  ensureFile() {
+    const dir = path.dirname(this.costsPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    if (!fs.existsSync(this.costsPath)) {
+      fs.writeFileSync(this.costsPath, '{"trend":[]}', 'utf8');
+    }
+  }
+}
+
+/**
+ * Analyze cloud resource costs
+ * @param {Object} resources - Resource usage data
+ * @param {string} cwd - Working directory
+ * @returns {Object} Cost analysis
+ */
+function analyzeCosts(resources = {}, cwd) {
+  const analyzer = new FinopsAnalyzer(cwd);
+  return analyzer.analyzeCosts(resources);
+}
+
+module.exports = { FinopsAnalyzer, analyzeCosts };

package/ez-agents/bin/lib/finops/spot-manager.cjs

@@ -0,0 +1,118 @@
+/**
+ * Spot Manager — Spot/preemptible instance management recommendations
+ * Analyzes workload patterns and recommends spot vs on-demand instances
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class SpotManager {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.recommendationsPath = path.join(this.cwd, '.planning', 'finops', 'spot-recommendations.json');
+  }
+
+  /**
+   * Analyze workload for spot instance suitability
+   * @param {Object} workload - Workload characteristics
+   * @returns {Object} Spot recommendations
+   */
+  analyzeWorkload(workload = {}) {
+    const recommendations = {
+      timestamp: new Date().toISOString(),
+      workloads: [],
+      totalPotentialSavings: 0
+    };
+
+    for (const [name, characteristics] of Object.entries(workload)) {
+      const suitability = this.calculateSpotSuitability(characteristics);
+      const savings = this.calculateSavings(characteristics.cost, suitability);
+
+      recommendations.workloads.push({
+        name,
+        spotSuitable: suitability.score >= 70,
+        suitabilityScore: suitability.score,
+        reasons: suitability.reasons,
+        currentCost: characteristics.cost,
+        potentialSavings: savings,
+        recommendation: suitability.score >= 70 ? 'Use spot instances' : 'Use on-demand'
+      });
+
+      recommendations.totalPotentialSavings += savings;
+    }
+
+    return recommendations;
+  }
+
+  /**
+   * Calculate spot suitability score
+   * @param {Object} characteristics - Workload characteristics
+   * @returns {Object} Suitability analysis
+   */
+  calculateSpotSuitability(characteristics) {
+    let score = 50; // Base score
+    const reasons = [];
+
+    // Fault tolerant workloads are good for spot
+    if (characteristics.faultTolerant) {
+      score += 30;
+      reasons.push('Fault tolerant workload');
+    }
+
+    // Batch processing is good for spot
+    if (characteristics.batchProcessing) {
+      score += 20;
+      reasons.push('Batch processing workload');
+    }
+
+    // Stateful workloads are bad for spot
+    if (characteristics.stateful) {
+      score -= 20;
+      reasons.push('Stateful workload (checkpointing recommended)');
+    }
+
+    // Time-sensitive workloads are bad for spot
+    if (characteristics.timeSensitive) {
+      score -= 30;
+      reasons.push('Time-sensitive workload');
+    }
+
+    return {
+      score: Math.min(100, Math.max(0, score)),
+      reasons
+    };
+  }
+
+  /**
+   * Calculate potential savings from spot
+   * @param {number} currentCost - Current on-demand cost
+   * @param {number} suitability - Suitability score
+   * @returns {number} Potential savings
+   */
+  calculateSavings(currentCost, suitability) {
+    // Spot instances typically 60-90% cheaper
+    const savingsRate = 0.7;
+    return Math.round(currentCost * savingsRate * (suitability / 100));
+  }
+
+  /**
+   * Save recommendations
+   * @param {Object} recommendations - Recommendations to save
+   */
+  saveRecommendations(recommendations) {
+    fs.writeFileSync(this.recommendationsPath, JSON.stringify(recommendations, null, 2), 'utf8');
+  }
+}
+
+/**
+ * Analyze workload for spot suitability
+ * @param {Object} workload - Workload characteristics
+ * @param {string} cwd - Working directory
+ * @returns {Object} Spot recommendations
+ */
+function analyzeWorkload(workload = {}, cwd) {
+  const manager = new SpotManager(cwd);
+  return manager.analyzeWorkload(workload);
+}
+
+module.exports = { SpotManager, analyzeWorkload };