@howlil/ez-agents 3.5.0 → 4.0.0

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

@@ -1,216 +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;
+#!/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 };