@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/package-manager-executor.cjs

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+
+/**
+ * Package Manager Executor — Execute package manager commands
+ *
+ * Provides unified interface for npm, yarn, and pnpm operations:
+ * - install: Install dependencies from lockfile
+ * - add: Add new package(s) to project
+ * - remove: Remove package(s) from project
+ *
+ * Cross-platform execution using execFile (not exec) for security
+ * and consistent behavior across Windows, macOS, and Linux.
+ *
+ * Usage:
+ *   const PackageManagerExecutor = require('./package-manager-executor.cjs');
+ *   const executor = new PackageManagerExecutor('npm', cwd);
+ *   await executor.install({ production: false, frozenLockfile: true });
+ */
+
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const path = require('path');
+const Logger = require('./logger.cjs');
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Custom error class for package manager operations
+ */
+class PackageManagerError extends Error {
+  constructor({ manager, cmd, args, error, stderr, stdout }) {
+    const message = `[${manager}] ${cmd} ${args.join(' ')} failed: ${error}${stderr ? `\n${stderr}` : ''}`;
+    super(message);
+    this.name = 'PackageManagerError';
+    this.manager = manager;
+    this.cmd = cmd;
+    this.args = args;
+    this.stderr = stderr;
+    this.stdout = stdout;
+  }
+}
+
+/**
+ * Package Manager Executor class
+ * Executes package manager commands with cross-platform compatibility
+ */
+class PackageManagerExecutor {
+  /**
+   * Create a PackageManagerExecutor instance
+   * @param {string} manager - Package manager name ('npm', 'yarn', or 'pnpm')
+   * @param {string} cwd - Working directory (default: process.cwd())
+   */
+  constructor(manager, cwd = process.cwd()) {
+    if (!['npm', 'yarn', 'pnpm'].includes(manager)) {
+      throw new Error(`Unknown package manager: ${manager}. Must be 'npm', 'yarn', or 'pnpm'`);
+    }
+
+    this.manager = manager;
+    this.cwd = cwd;
+    this.logger = new Logger();
+    this.timeout = 300000; // 5 minutes
+    this.maxBuffer = 10 * 1024 * 1024; // 10MB buffer
+  }
+
+  /**
+   * Execute install command
+   * @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 = {}) {
+    const { production, frozenLockfile, preferOffline } = options;
+
+    const args = this._buildInstallArgs({ production, frozenLockfile, preferOffline });
+
+    this.logger.info('Package manager install', {
+      manager: this.manager,
+      args: args.join(' '),
+      cwd: this.cwd
+    });
+
+    return await this._execute(this.manager, args);
+  }
+
+  /**
+   * Add package(s) to project
+   * @param {string[]} packages - Package names 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 = {}) {
+    const { dev, peer, optional, global } = options;
+
+    const args = this._buildAddArgs(packages, { dev, peer, optional, global });
+
+    this.logger.info('Package manager add', {
+      manager: this.manager,
+      packages,
+      args: args.join(' '),
+      cwd: this.cwd
+    });
+
+    return await this._execute(this.manager, args);
+  }
+
+  /**
+   * Remove package(s) from project
+   * @param {string[]} packages - Package names to remove
+   * @param {Object} options - Remove options
+   * @param {boolean} [options.global] - Remove from global install
+   * @returns {Promise<string>} Command output
+   */
+  async remove(packages, options = {}) {
+    const { global } = options;
+
+    const args = this._buildRemoveArgs(packages, { global });
+
+    this.logger.info('Package manager remove', {
+      manager: this.manager,
+      packages,
+      args: args.join(' '),
+      cwd: this.cwd
+    });
+
+    return await this._execute(this.manager, args);
+  }
+
+  /**
+   * Build install arguments for specific package manager
+   * @private
+   * @param {Object} options - Install options
+   * @returns {string[]} Command arguments
+   */
+  _buildInstallArgs(options = {}) {
+    const { production, frozenLockfile, preferOffline } = options;
+
+    switch (this.manager) {
+      case 'npm':
+        return this._buildNpmInstallArgs({ production, frozenLockfile, preferOffline });
+      case 'yarn':
+        return this._buildYarnInstallArgs({ production, frozenLockfile, preferOffline });
+      case 'pnpm':
+        return this._buildPnpmInstallArgs({ production, frozenLockfile, preferOffline });
+      default:
+        throw new Error(`Unknown package manager: ${this.manager}`);
+    }
+  }
+
+  /**
+   * Build npm install arguments
+   * @private
+   */
+  _buildNpmInstallArgs(options = {}) {
+    const { production, frozenLockfile, preferOffline } = options;
+    const args = ['install'];
+
+    if (production) args.push('--production');
+    if (frozenLockfile) args.push('--frozen-lockfile');
+    if (preferOffline) args.push('--prefer-offline');
+
+    return args.filter(Boolean);
+  }
+
+  /**
+   * Build yarn install arguments
+   * @private
+   */
+  _buildYarnInstallArgs(options = {}) {
+    const { production, frozenLockfile, preferOffline } = options;
+    const args = ['install'];
+
+    if (production) args.push('--production');
+    if (frozenLockfile) args.push('--frozen-lockfile');
+    if (preferOffline) args.push('--prefer-offline');
+
+    return args.filter(Boolean);
+  }
+
+  /**
+   * Build pnpm install arguments
+   * @private
+   */
+  _buildPnpmInstallArgs(options = {}) {
+    const { production, frozenLockfile, preferOffline } = options;
+    const args = ['install'];
+
+    if (production) args.push('--prod');
+    if (frozenLockfile) args.push('--frozen-lockfile');
+    if (preferOffline) args.push('--prefer-offline');
+
+    return args.filter(Boolean);
+  }
+
+  /**
+   * Build add arguments for specific package manager
+   * @private
+   * @param {string[]} packages - Package names
+   * @param {Object} options - Add options
+   * @returns {string[]} Command arguments
+   */
+  _buildAddArgs(packages, options = {}) {
+    switch (this.manager) {
+      case 'npm':
+        return this._buildNpmAddArgs(packages, options);
+      case 'yarn':
+        return this._buildYarnAddArgs(packages, options);
+      case 'pnpm':
+        return this._buildPnpmAddArgs(packages, options);
+      default:
+        throw new Error(`Unknown package manager: ${this.manager}`);
+    }
+  }
+
+  /**
+   * Build npm add arguments
+   * @private
+   */
+  _buildNpmAddArgs(packages, options = {}) {
+    const { dev, peer, optional, global } = options;
+    const args = ['install'];
+
+    if (global) args.push('-g');
+    if (dev) args.push('--save-dev');
+    if (peer) args.push('--save-peer');
+    if (optional) args.push('--save-optional');
+
+    return [...args, ...packages];
+  }
+
+  /**
+   * Build yarn add arguments
+   * @private
+   */
+  _buildYarnAddArgs(packages, options = {}) {
+    const { dev, peer, optional, global } = options;
+    const args = ['add'];
+
+    if (global) args.push('global');
+    if (dev) args.push('--dev');
+    if (peer) args.push('--peer');
+    if (optional) args.push('--optional');
+
+    return [...args, ...packages];
+  }
+
+  /**
+   * Build pnpm add arguments
+   * @private
+   */
+  _buildPnpmAddArgs(packages, options = {}) {
+    const { dev, peer, optional, global } = options;
+    const args = ['add'];
+
+    if (global) args.push('-g');
+    if (dev) args.push('--save-dev');
+    if (peer) args.push('--save-peer');
+    if (optional) args.push('--save-optional');
+
+    return [...args, ...packages];
+  }
+
+  /**
+   * Build remove arguments for specific package manager
+   * @private
+   * @param {string[]} packages - Package names
+   * @param {Object} options - Remove options
+   * @returns {string[]} Command arguments
+   */
+  _buildRemoveArgs(packages, options = {}) {
+    switch (this.manager) {
+      case 'npm':
+        return this._buildNpmRemoveArgs(packages, options);
+      case 'yarn':
+        return this._buildYarnRemoveArgs(packages, options);
+      case 'pnpm':
+        return this._buildPnpmRemoveArgs(packages, options);
+      default:
+        throw new Error(`Unknown package manager: ${this.manager}`);
+    }
+  }
+
+  /**
+   * Build npm remove arguments
+   * @private
+   */
+  _buildNpmRemoveArgs(packages, options = {}) {
+    const { global } = options;
+    const args = ['uninstall'];
+
+    if (global) args.push('-g');
+
+    return [...args, ...packages];
+  }
+
+  /**
+   * Build yarn remove arguments
+   * @private
+   */
+  _buildYarnRemoveArgs(packages, options = {}) {
+    const { global } = options;
+    const args = ['remove'];
+
+    if (global) args.push('global');
+
+    return [...args, ...packages];
+  }
+
+  /**
+   * Build pnpm remove arguments
+   * @private
+   */
+  _buildPnpmRemoveArgs(packages, options = {}) {
+    const { global } = options;
+    const args = ['remove'];
+
+    if (global) args.push('-g');
+
+    return [...args, ...packages];
+  }
+
+  /**
+   * Execute command with cross-platform compatibility
+   * @private
+   * @param {string} cmd - Command to execute
+   * @param {string[]} args - Command arguments
+   * @returns {Promise<string>} Command output
+   */
+  async _execute(cmd, args) {
+    const startTime = Date.now();
+
+    this.logger.debug('Package manager command start', {
+      manager: this.manager,
+      cmd,
+      args: args.join(' '),
+      cwd: this.cwd
+    });
+
+    try {
+      const result = await execFileAsync(cmd, args, {
+        cwd: this.cwd,
+        shell: false, // Use execFile for security (no shell injection)
+        maxBuffer: this.maxBuffer,
+        timeout: this.timeout
+      });
+
+      const duration = Date.now() - startTime;
+      this.logger.debug('Package manager command completed', {
+        manager: this.manager,
+        duration,
+        stdout_length: result.stdout?.length || 0
+      });
+
+      return result.stdout.trim();
+    } catch (err) {
+      const duration = Date.now() - startTime;
+      this.logger.error('Package manager command failed', {
+        manager: this.manager,
+        cmd,
+        args: args.join(' '),
+        duration,
+        error: err.message,
+        stderr: err.stderr?.trim(),
+        stdout: err.stdout?.trim()
+      });
+
+      throw new PackageManagerError({
+        manager: this.manager,
+        cmd,
+        args,
+        error: err.message,
+        stderr: err.stderr?.trim(),
+        stdout: err.stdout?.trim()
+      });
+    }
+  }
+}
+
+module.exports = PackageManagerExecutor;
+module.exports.PackageManagerError = PackageManagerError;

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