@howlil/ez-agents 3.5.0 → 4.0.0

package/ez-agents/bin/lib/file-access.cjs

@@ -1,207 +1,207 @@
-#!/usr/bin/env node
-
-/**
- * File Access Service
- *
- * Provides file reading capabilities with glob pattern support.
- * Uses micromatch for glob matching with support for negation and brace expansion.
- */
-
-const fs = require('fs');
-const path = require('path');
-const micromatch = require('micromatch');
-const { FileAccessError } = require('./context-errors.cjs');
-
-const MAX_FILE_COUNT = 1000;
-
-class FileAccessService {
-  /**
-   * Create a new FileAccessService instance
-   * @param {string} cwd - Current working directory (defaults to process.cwd())
-   */
-  constructor(cwd) {
-    this.cwd = cwd || process.cwd();
-  }
-
-  /**
-   * Read files matching patterns
-   * @param {string|string[]} patterns - File patterns (glob or single path)
-   * @returns {Array<{path: string, content: string}>} - Array of file objects
-   * @throws {FileAccessError} - On file access errors
-   */
-  readFiles(patterns) {
-    const patternArray = Array.isArray(patterns) ? patterns : [patterns];
-    
-    // Get all files recursively
-    const allFiles = this._getAllFiles(this.cwd);
-    
-    // Convert paths to relative paths from cwd
-    const relativeFiles = allFiles.map(f => {
-      const relPath = path.relative(this.cwd, f);
-      // Convert to POSIX style paths for glob matching
-      return relPath.replace(/\\/g, '/');
-    });
-    
-    // Filter with micromatch
-    const matchedFiles = micromatch.match(relativeFiles, patternArray, {
-      dot: false, // Don't match hidden files/directories by default
-      nocase: false
-    });
-    
-    // Check max file count
-    if (matchedFiles.length > MAX_FILE_COUNT) {
-      throw new FileAccessError(
-        matchedFiles[0],
-        `Max file count exceeded: ${matchedFiles.length} > ${MAX_FILE_COUNT}`
-      );
-    }
-    
-    // Read file contents
-    const results = matchedFiles.map(filePath => {
-      const fullPath = path.join(this.cwd, filePath);
-      
-      if (!fs.existsSync(fullPath)) {
-        throw new FileAccessError(filePath, 'File not found');
-      }
-      
-      try {
-        const content = fs.readFileSync(fullPath, 'utf-8');
-        return {
-          path: filePath,
-          content
-        };
-      } catch (err) {
-        if (err.code === 'EACCES') {
-          throw new FileAccessError(filePath, 'Permission denied');
-        }
-        throw new FileAccessError(filePath, err.message);
-      }
-    });
-    
-    return results;
-  }
-
-  /**
-   * Get all files recursively from a directory
-   * @param {string} dir - Directory to scan
-   * @returns {string[]} - Array of file paths
-   * @private
-   */
-  _getAllFiles(dir) {
-    const files = [];
-    
-    try {
-      const entries = fs.readdirSync(dir, { withFileTypes: true });
-      
-      for (const entry of entries) {
-        const fullPath = path.join(dir, entry.name);
-        
-        // Skip hidden directories (starting with .)
-        if (entry.isDirectory() && !entry.name.startsWith('.')) {
-          const subFiles = this._getAllFiles(fullPath);
-          files.push(...subFiles);
-        } else if (entry.isFile()) {
-          files.push(fullPath);
-        }
-      }
-    } catch (err) {
-      // Ignore permission errors during directory traversal
-      if (err.code !== 'EACCES') {
-        throw err;
-      }
-    }
-    
-    return files;
-  }
-
-  /**
-   * Normalize a file path (convert Windows paths to Unix style)
-   * @param {string} filePath - The path to normalize
-   * @returns {string} - Normalized path
-   * @throws {FileAccessError} - On path traversal attempts
-   */
-  normalizePath(filePath) {
-    // Convert Windows backslashes to forward slashes
-    const normalized = filePath.replace(/\\/g, '/');
-    
-    // Check for path traversal attempts
-    if (normalized.includes('..')) {
-      throw new FileAccessError(filePath, 'Path traversal not allowed');
-    }
-    
-    return normalized;
-  }
-
-  /**
-   * Validate a file path
-   * @param {string} filePath - The path to validate
-   * @returns {boolean} - True if valid
-   */
-  validatePath(filePath) {
-    // Reject paths with null bytes
-    if (filePath.includes('\x00')) {
-      return false;
-    }
-    
-    // Resolve the path
-    const resolvedPath = path.resolve(this.cwd, filePath);
-    
-    // Check if path is within cwd (prevent access outside project)
-    const normalizedCwd = path.resolve(this.cwd).replace(/\\/g, '/');
-    const normalizedResolved = resolvedPath.replace(/\\/g, '/');
-    
-    // Path must be within or equal to cwd
-    if (!normalizedResolved.startsWith(normalizedCwd)) {
-      return false;
-    }
-    
-    return true;
-  }
-
-  /**
-   * Check if a file exists
-   * @param {string} filePath - Path to check
-   * @returns {boolean} - True if file exists
-   */
-  fileExists(filePath) {
-    const fullPath = path.join(this.cwd, filePath);
-    return fs.existsSync(fullPath);
-  }
-
-  /**
-   * Read a single file
-   * @param {string} filePath - Path to the file
-   * @returns {{path: string, content: string}} - File object
-   * @throws {FileAccessError} - On file access errors
-   */
-  readFile(filePath) {
-    const results = this.readFiles([filePath]);
-    return results[0] || null;
-  }
-
-  /**
-   * Get file info (size, modified time, etc.)
-   * @param {string} filePath - Path to the file
-   * @returns {{path: string, size: number, mtime: Date}} - File info
-   * @throws {FileAccessError} - On file access errors
-   */
-  getFileInfo(filePath) {
-    const fullPath = path.join(this.cwd, filePath);
-    
-    if (!fs.existsSync(fullPath)) {
-      throw new FileAccessError(filePath, 'File not found');
-    }
-    
-    const stats = fs.statSync(fullPath);
-    
-    return {
-      path: filePath,
-      size: stats.size,
-      mtime: stats.mtime,
-      isDirectory: stats.isDirectory(),
-      isFile: stats.isFile()
-    };
-  }
-}
-
-module.exports = FileAccessService;
+#!/usr/bin/env node
+
+/**
+ * File Access Service
+ *
+ * Provides file reading capabilities with glob pattern support.
+ * Uses micromatch for glob matching with support for negation and brace expansion.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const micromatch = require('micromatch');
+const { FileAccessError } = require('./context-errors.cjs');
+
+const MAX_FILE_COUNT = 1000;
+
+class FileAccessService {
+  /**
+   * Create a new FileAccessService instance
+   * @param {string} cwd - Current working directory (defaults to process.cwd())
+   */
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+  }
+
+  /**
+   * Read files matching patterns
+   * @param {string|string[]} patterns - File patterns (glob or single path)
+   * @returns {Array<{path: string, content: string}>} - Array of file objects
+   * @throws {FileAccessError} - On file access errors
+   */
+  readFiles(patterns) {
+    const patternArray = Array.isArray(patterns) ? patterns : [patterns];
+    
+    // Get all files recursively
+    const allFiles = this._getAllFiles(this.cwd);
+    
+    // Convert paths to relative paths from cwd
+    const relativeFiles = allFiles.map(f => {
+      const relPath = path.relative(this.cwd, f);
+      // Convert to POSIX style paths for glob matching
+      return relPath.replace(/\\/g, '/');
+    });
+    
+    // Filter with micromatch
+    const matchedFiles = micromatch.match(relativeFiles, patternArray, {
+      dot: false, // Don't match hidden files/directories by default
+      nocase: false
+    });
+    
+    // Check max file count
+    if (matchedFiles.length > MAX_FILE_COUNT) {
+      throw new FileAccessError(
+        matchedFiles[0],
+        `Max file count exceeded: ${matchedFiles.length} > ${MAX_FILE_COUNT}`
+      );
+    }
+    
+    // Read file contents
+    const results = matchedFiles.map(filePath => {
+      const fullPath = path.join(this.cwd, filePath);
+      
+      if (!fs.existsSync(fullPath)) {
+        throw new FileAccessError(filePath, 'File not found');
+      }
+      
+      try {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        return {
+          path: filePath,
+          content
+        };
+      } catch (err) {
+        if (err.code === 'EACCES') {
+          throw new FileAccessError(filePath, 'Permission denied');
+        }
+        throw new FileAccessError(filePath, err.message);
+      }
+    });
+    
+    return results;
+  }
+
+  /**
+   * Get all files recursively from a directory
+   * @param {string} dir - Directory to scan
+   * @returns {string[]} - Array of file paths
+   * @private
+   */
+  _getAllFiles(dir) {
+    const files = [];
+    
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        
+        // Skip hidden directories (starting with .)
+        if (entry.isDirectory() && !entry.name.startsWith('.')) {
+          const subFiles = this._getAllFiles(fullPath);
+          files.push(...subFiles);
+        } else if (entry.isFile()) {
+          files.push(fullPath);
+        }
+      }
+    } catch (err) {
+      // Ignore permission errors during directory traversal
+      if (err.code !== 'EACCES') {
+        throw err;
+      }
+    }
+    
+    return files;
+  }
+
+  /**
+   * Normalize a file path (convert Windows paths to Unix style)
+   * @param {string} filePath - The path to normalize
+   * @returns {string} - Normalized path
+   * @throws {FileAccessError} - On path traversal attempts
+   */
+  normalizePath(filePath) {
+    // Convert Windows backslashes to forward slashes
+    const normalized = filePath.replace(/\\/g, '/');
+    
+    // Check for path traversal attempts
+    if (normalized.includes('..')) {
+      throw new FileAccessError(filePath, 'Path traversal not allowed');
+    }
+    
+    return normalized;
+  }
+
+  /**
+   * Validate a file path
+   * @param {string} filePath - The path to validate
+   * @returns {boolean} - True if valid
+   */
+  validatePath(filePath) {
+    // Reject paths with null bytes
+    if (filePath.includes('\x00')) {
+      return false;
+    }
+    
+    // Resolve the path
+    const resolvedPath = path.resolve(this.cwd, filePath);
+    
+    // Check if path is within cwd (prevent access outside project)
+    const normalizedCwd = path.resolve(this.cwd).replace(/\\/g, '/');
+    const normalizedResolved = resolvedPath.replace(/\\/g, '/');
+    
+    // Path must be within or equal to cwd
+    if (!normalizedResolved.startsWith(normalizedCwd)) {
+      return false;
+    }
+    
+    return true;
+  }
+
+  /**
+   * Check if a file exists
+   * @param {string} filePath - Path to check
+   * @returns {boolean} - True if file exists
+   */
+  fileExists(filePath) {
+    const fullPath = path.join(this.cwd, filePath);
+    return fs.existsSync(fullPath);
+  }
+
+  /**
+   * Read a single file
+   * @param {string} filePath - Path to the file
+   * @returns {{path: string, content: string}} - File object
+   * @throws {FileAccessError} - On file access errors
+   */
+  readFile(filePath) {
+    const results = this.readFiles([filePath]);
+    return results[0] || null;
+  }
+
+  /**
+   * Get file info (size, modified time, etc.)
+   * @param {string} filePath - Path to the file
+   * @returns {{path: string, size: number, mtime: Date}} - File info
+   * @throws {FileAccessError} - On file access errors
+   */
+  getFileInfo(filePath) {
+    const fullPath = path.join(this.cwd, filePath);
+    
+    if (!fs.existsSync(fullPath)) {
+      throw new FileAccessError(filePath, 'File not found');
+    }
+    
+    const stats = fs.statSync(fullPath);
+    
+    return {
+      path: filePath,
+      size: stats.size,
+      mtime: stats.mtime,
+      isDirectory: stats.isDirectory(),
+      isFile: stats.isFile()
+    };
+  }
+}
+
+module.exports = FileAccessService;

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 };