@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/bin/lib/package-manager-service.cjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+
+/**
+ * Package Manager Service — Unified package manager operations
+ *
+ * High-level service that integrates detection, execution, and validation:
+ * - Automatic package manager detection with priority-based strategy
+ * - Lockfile validation before operations
+ * - Unified interface for install, add, remove operations
+ * - Configuration-driven defaults from .planning/config.json
+ *
+ * Usage:
+ *   const PackageManagerService = require('./package-manager-service.cjs');
+ *   const service = new PackageManagerService(cwd);
+ *   await service.initialize();
+ *   await service.install({ frozenLockfile: true });
+ *   await service.add(['lodash'], { dev: true });
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Logger = require('./logger.cjs');
+const PackageManagerDetector = require('./package-manager-detector.cjs');
+const PackageManagerExecutor = require('./package-manager-executor.cjs');
+const LockfileValidator = require('./lockfile-validator.cjs');
+
+/**
+ * Package Manager Service class
+ * Provides unified interface for package manager operations
+ */
+class PackageManagerService {
+  /**
+   * Create a PackageManagerService instance
+   * @param {string} cwd - Working directory (default: process.cwd())
+   */
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+    this.logger = new Logger();
+    this.detector = new PackageManagerDetector(cwd);
+    this.validator = new LockfileValidator(cwd);
+    this.executor = null;
+    this.currentManager = null;
+    this.detectionSource = null;
+    this.initialized = false;
+    this.config = this._loadConfig();
+  }
+
+  /**
+   * Initialize the package manager service
+   * @param {Object} options - Initialization options
+   * @param {string} [options.forceManager] - Force specific package manager
+   * @returns {Promise<void>}
+   */
+  async initialize(options = {}) {
+    const { forceManager } = options;
+
+    this.logger.info('Initializing package manager service', {
+      cwd: this.cwd,
+      forceManager
+    });
+
+    // Detect package manager
+    let detection;
+    if (forceManager) {
+      detection = {
+        manager: forceManager,
+        source: 'override',
+        confidence: 'high'
+      };
+      this.logger.info('Using forced package manager', { manager: forceManager });
+    } else {
+      detection = this.detector.detect();
+      this.logger.info('Package manager detected', {
+        manager: detection.manager,
+        source: detection.source,
+        confidence: detection.confidence
+      });
+    }
+
+    // Validate detection
+    if (!detection.manager) {
+      throw new Error('No package manager detected or available');
+    }
+
+    // Create executor
+    this.executor = new PackageManagerExecutor(detection.manager, this.cwd);
+    this.currentManager = detection.manager;
+    this.detectionSource = detection.source;
+
+    // Validate lockfile if present
+    const lockfileValidation = this.validator.validate(detection.manager);
+    if (!lockfileValidation.valid) {
+      this.logger.warn('Lockfile validation failed', {
+        manager: detection.manager,
+        reason: lockfileValidation.reason,
+        message: lockfileValidation.message
+      });
+    } else {
+      this.logger.debug('Lockfile validated', {
+        manager: detection.manager,
+        lockfileVersion: lockfileValidation.lockfileVersion,
+        packageCount: lockfileValidation.packageCount || lockfileValidation.entryCount
+      });
+    }
+
+    this.initialized = true;
+  }
+
+  /**
+   * Ensure service is initialized
+   * @private
+   * @returns {Promise<void>}
+   */
+  async _ensureInitialized() {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+  }
+
+  /**
+   * Install dependencies
+   * @param {Object} options - Install options
+   * @param {boolean} [options.production] - Production install (exclude devDependencies)
+   * @param {boolean} [options.frozenLockfile] - Use frozen lockfile (CI/CD safe)
+   * @param {boolean} [options.preferOffline] - Prefer offline cache
+   * @returns {Promise<string>} Command output
+   */
+  async install(options = {}) {
+    await this._ensureInitialized();
+
+    this.logger.info('Installing dependencies', {
+      manager: this.currentManager,
+      options
+    });
+
+    return await this.executor.install(options);
+  }
+
+  /**
+   * Add package(s) to project
+   * @param {string|string[]} packages - Package name(s) to add
+   * @param {Object} options - Add options
+   * @param {boolean} [options.dev] - Add as devDependency
+   * @param {boolean} [options.peer] - Add as peerDependency
+   * @param {boolean} [options.optional] - Add as optionalDependency
+   * @param {boolean} [options.global] - Install globally
+   * @returns {Promise<string>} Command output
+   */
+  async add(packages, options = {}) {
+    await this._ensureInitialized();
+
+    const packageArray = Array.isArray(packages) ? packages : [packages];
+
+    this.logger.info('Adding packages', {
+      manager: this.currentManager,
+      packages: packageArray,
+      options
+    });
+
+    return await this.executor.add(packageArray, options);
+  }
+
+  /**
+   * Remove package(s) from project
+   * @param {string|string[]} packages - Package name(s) to remove
+   * @param {Object} options - Remove options
+   * @param {boolean} [options.global] - Remove from global install
+   * @returns {Promise<string>} Command output
+   */
+  async remove(packages, options = {}) {
+    await this._ensureInitialized();
+
+    const packageArray = Array.isArray(packages) ? packages : [packages];
+
+    this.logger.info('Removing packages', {
+      manager: this.currentManager,
+      packages: packageArray,
+      options
+    });
+
+    return await this.executor.remove(packageArray, options);
+  }
+
+  /**
+   * Get current package manager information
+   * @returns {Object} Package manager info
+   */
+  getInfo() {
+    return {
+      manager: this.currentManager,
+      source: this.detectionSource,
+      cwd: this.cwd,
+      lockfile: this.detector.getLockfilePath(this.currentManager)
+    };
+  }
+
+  /**
+   * Load configuration from .planning/config.json
+   * @private
+   * @returns {Object} Configuration object
+   */
+  _loadConfig() {
+    const configPath = path.join(this.cwd, '.planning', 'config.json');
+    try {
+      if (fs.existsSync(configPath)) {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        return JSON.parse(content);
+      }
+    } catch (err) {
+      this.logger.warn('Failed to load config', { path: configPath, error: err.message });
+    }
+    return {};
+  }
+}
+
+module.exports = PackageManagerService;

package/ez-agents/bin/lib/perf/api-monitor.cjs

@@ -0,0 +1,88 @@
+/**
+ * API Monitor — Endpoint latency tracking with baseline storage
+ * Tracks p50, p95, p99 percentiles
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class ApiMonitor {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.latenciesPath = path.join(this.cwd, '.planning', 'perf', 'api-latencies.json');
+  }
+
+  /**
+   * Track endpoint latency
+   * @param {string} baseUrl - Base URL of API
+   * @param {Array} endpoints - Array of endpoint paths to track
+   * @returns {Array} Latency results
+   */
+  async trackEndpoint(baseUrl, endpoints) {
+    const results = [];
+
+    for (const endpoint of endpoints) {
+      const start = Date.now();
+      try {
+        // Placeholder - would make actual HTTP request in real implementation
+        const latency = Date.now() - start;
+        results.push({
+          endpoint: endpoint.path || endpoint,
+          method: endpoint.method || 'GET',
+          latency,
+          status: 200,
+          timestamp: new Date().toISOString()
+        });
+      } catch (e) {
+        results.push({
+          endpoint: endpoint.path || endpoint,
+          method: endpoint.method || 'GET',
+          latency: -1,
+          error: e.message,
+          timestamp: new Date().toISOString()
+        });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Calculate percentiles from latency array
+   * @param {Array} latencies - Array of latency values
+   * @returns {Object} Percentile values
+   */
+  calculatePercentiles(latencies) {
+    const sorted = latencies.filter(l => l > 0).sort((a, b) => a - b);
+    if (sorted.length === 0) return { p50: 0, p95: 0, p99: 0 };
+
+    return {
+      p50: sorted[Math.floor(sorted.length * 0.50)],
+      p95: sorted[Math.floor(sorted.length * 0.95)],
+      p99: sorted[Math.floor(sorted.length * 0.99)]
+    };
+  }
+}
+
+/**
+ * Track endpoint latency
+ * @param {string} baseUrl - Base URL of API
+ * @param {Array} endpoints - Array of endpoint paths to track
+ * @returns {Array} Latency results
+ */
+async function trackEndpoint(baseUrl, endpoints) {
+  const monitor = new ApiMonitor();
+  return monitor.trackEndpoint(baseUrl, endpoints);
+}
+
+/**
+ * Calculate percentiles from latency array
+ * @param {Array} latencies - Array of latency values
+ * @returns {Object} Percentile values
+ */
+function calculatePercentiles(latencies) {
+  const monitor = new ApiMonitor();
+  return monitor.calculatePercentiles(latencies);
+}
+
+module.exports = { ApiMonitor, trackEndpoint, calculatePercentiles };

package/ez-agents/bin/lib/perf/db-optimizer.cjs

@@ -0,0 +1,78 @@
+/**
+ * DB Optimizer — Query analysis and index recommendations
+ * Analyzes slow queries, suggests indexes, detects N+1 patterns
+ */
+
+const { execSync } = require('child_process');
+
+class DbOptimizer {
+  constructor(dbUrl) {
+    this.dbUrl = dbUrl;
+  }
+
+  /**
+   * Analyze queries and provide optimization recommendations
+   * @param {string} dbUrl - Database connection URL
+   * @param {Array} queries - Array of queries to analyze
+   * @returns {Array} Analysis results with suggestions
+   */
+  async analyzeQueries(dbUrl, queries) {
+    const results = [];
+
+    for (const query of queries) {
+      const explain = await this.explainQuery(dbUrl, query);
+      const suggestions = [];
+
+      // Detect sequential scans
+      if (explain.scanType === 'Seq Scan' || explain.scanType === 'Sequential Scan') {
+        suggestions.push({
+          type: 'index',
+          reason: 'Sequential scan detected',
+          recommendation: `CREATE INDEX ON ${explain.table} (${explain.filterColumn || 'column'})`
+        });
+      }
+
+      // Detect N+1 patterns
+      if (explain.nestedLoops > 5) {
+        suggestions.push({
+          type: 'n-plus-one',
+          reason: 'N+1 query pattern detected',
+          recommendation: 'Use JOIN or batch loading'
+        });
+      }
+
+      results.push({ query, explain, suggestions });
+    }
+
+    return results;
+  }
+
+  /**
+   * Get EXPLAIN plan for a query
+   * @param {string} dbUrl - Database connection URL
+   * @param {string} query - Query to explain
+   * @returns {Object} Explain plan
+   */
+  async explainQuery(dbUrl, query) {
+    // Placeholder - would execute EXPLAIN QUERY in real implementation
+    return {
+      scanType: 'Unknown',
+      table: 'unknown',
+      filterColumn: null,
+      nestedLoops: 0
+    };
+  }
+}
+
+/**
+ * Analyze queries and provide optimization recommendations
+ * @param {string} dbUrl - Database connection URL
+ * @param {Array} queries - Array of queries to analyze
+ * @returns {Array} Analysis results with suggestions
+ */
+async function analyzeQueries(dbUrl, queries) {
+  const optimizer = new DbOptimizer(dbUrl);
+  return optimizer.analyzeQueries(dbUrl, queries);
+}
+
+module.exports = { DbOptimizer, analyzeQueries };

package/ez-agents/bin/lib/perf/frontend-performance.cjs

@@ -0,0 +1,56 @@
+/**
+ * Frontend Performance — Lighthouse integration for bundle/render analysis
+ * Measures Core Web Vitals: FCP, LCP, CLS, TTI
+ */
+
+class FrontendPerformance {
+  constructor() {
+    this.lighthouse = null;
+    this.chromeLauncher = null;
+  }
+
+  /**
+   * Run Lighthouse analysis on a URL
+   * @param {string} url - URL to analyze
+   * @returns {Object} Lighthouse results
+   */
+  async runLighthouse(url) {
+    // Placeholder - would run actual Lighthouse in real implementation
+    // Requires: npm install lighthouse chrome-launcher
+    return {
+      performance: 0,
+      metrics: {
+        fcp: 0,
+        lcp: 0,
+        cls: 0,
+        tti: 0
+      },
+      opportunities: []
+    };
+  }
+
+  /**
+   * Analyze bundle size
+   * @param {string} buildPath - Path to build directory
+   * @returns {Object} Bundle analysis
+   */
+  async analyzeBundle(buildPath) {
+    // Placeholder - would use webpack-bundle-analyzer in real implementation
+    return {
+      totalSize: 0,
+      chunks: []
+    };
+  }
+}
+
+/**
+ * Run Lighthouse analysis on a URL
+ * @param {string} url - URL to analyze
+ * @returns {Object} Lighthouse results
+ */
+async function runLighthouse(url) {
+  const perf = new FrontendPerformance();
+  return perf.runLighthouse(url);
+}
+
+module.exports = { FrontendPerformance, runLighthouse };

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

@@ -0,0 +1,77 @@
+/**
+ * Perf Analyzer — Core performance analysis coordinator
+ * Orchestrates all analyzers and aggregates results
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class PerfAnalyzer {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+  }
+
+  /**
+   * Run all performance analyzers and aggregate results
+   * @param {Object} options - Analysis options
+   * @returns {Object} Aggregated performance results
+   */
+  async analyze(options = {}) {
+    const results = {
+      timestamp: new Date().toISOString(),
+      db: null,
+      frontend: null,
+      api: null,
+      errors: []
+    };
+
+    try {
+      // Run DB analysis if DB URL provided
+      if (options.dbUrl) {
+        const { analyzeQueries } = require('./db-optimizer.cjs');
+        results.db = await analyzeQueries(options.dbUrl, options.queries || []);
+      }
+    } catch (e) {
+      results.errors.push(`DB analysis failed: ${e.message}`);
+    }
+
+    try {
+      // Run frontend analysis if URL provided
+      if (options.url) {
+        const { runLighthouse } = require('./frontend-performance.cjs');
+        results.frontend = await runLighthouse(options.url);
+      }
+    } catch (e) {
+      results.errors.push(`Frontend analysis failed: ${e.message}`);
+    }
+
+    try {
+      // Run API analysis if API URL provided
+      if (options.apiUrl) {
+        const { trackEndpoint } = require('./api-monitor.cjs');
+        results.api = await trackEndpoint(options.apiUrl, options.endpoints || []);
+      }
+    } catch (e) {
+      results.errors.push(`API analysis failed: ${e.message}`);
+    }
+
+    return results;
+  }
+
+  /**
+   * Aggregate results from multiple analyzers
+   * @param {Array} results - Array of analysis results
+   * @returns {Object} Aggregated results
+   */
+  aggregate(results) {
+    return results.reduce((acc, r) => {
+      if (r.db) acc.db.push(r.db);
+      if (r.frontend) acc.frontend.push(r.frontend);
+      if (r.api) acc.api.push(r.api);
+      acc.errors.push(...(r.errors || []));
+      return acc;
+    }, { db: [], frontend: [], api: [], errors: [] });
+  }
+}
+
+module.exports = { PerfAnalyzer, analyze: PerfAnalyzer.prototype.analyze };

package/ez-agents/bin/lib/perf/perf-baseline.cjs

@@ -0,0 +1,102 @@
+/**
+ * Perf Baseline — Save and load performance baselines
+ * Stores baselines in .planning/perf-baselines/
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class PerfBaseline {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.baselinesDir = path.join(this.cwd, '.planning', 'perf-baselines');
+  }
+
+  /**
+   * Save baseline metrics
+   * @param {Object} metrics - Metrics to save
+   * @param {string} name - Baseline name
+   * @returns {string} Path to saved baseline
+   */
+  saveBaseline(metrics, name = 'default') {
+    // Ensure directory exists
+    if (!fs.existsSync(this.baselinesDir)) {
+      fs.mkdirSync(this.baselinesDir, { recursive: true });
+    }
+
+    const baselinePath = path.join(this.baselinesDir, `${name}.json`);
+    const baseline = {
+      ...metrics,
+      metadata: {
+        name,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString()
+      }
+    };
+
+    fs.writeFileSync(baselinePath, JSON.stringify(baseline, null, 2), 'utf8');
+    return baselinePath;
+  }
+
+  /**
+   * Load baseline metrics
+   * @param {string} name - Baseline name
+   * @returns {Object|null} Baseline metrics or null
+   */
+  loadBaseline(name = 'default') {
+    const baselinePath = path.join(this.baselinesDir, `${name}.json`);
+
+    if (!fs.existsSync(baselinePath)) return null;
+
+    return JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+  }
+
+  /**
+   * List all available baselines
+   * @returns {Array} Array of baseline names
+   */
+  listBaselines() {
+    if (!fs.existsSync(this.baselinesDir)) return [];
+
+    return fs.readdirSync(this.baselinesDir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => f.replace('.json', ''));
+  }
+
+  /**
+   * Delete a baseline
+   * @param {string} name - Baseline name
+   * @returns {boolean} Success
+   */
+  deleteBaseline(name) {
+    const baselinePath = path.join(this.baselinesDir, `${name}.json`);
+
+    if (!fs.existsSync(baselinePath)) return false;
+
+    fs.unlinkSync(baselinePath);
+    return true;
+  }
+}
+
+/**
+ * Save baseline metrics
+ * @param {Object} metrics - Metrics to save
+ * @param {string} name - Baseline name
+ * @returns {string} Path to saved baseline
+ */
+function saveBaseline(metrics, name = 'default') {
+  const baseline = new PerfBaseline();
+  return baseline.saveBaseline(metrics, name);
+}
+
+/**
+ * Load baseline metrics
+ * @param {string} name - Baseline name
+ * @returns {Object|null} Baseline metrics or null
+ */
+function loadBaseline(name = 'default') {
+  const baseline = new PerfBaseline();
+  return baseline.loadBaseline(name);
+}
+
+module.exports = { PerfBaseline, saveBaseline, loadBaseline };