@howlil/ez-agents 3.4.2 → 3.5.0

package/ez-agents/bin/lib/safe-exec.cjs

@@ -1,214 +1,128 @@
-#!/usr/bin/env node
-
-/**
- * EZ Safe Exec — Secure command execution with allowlist and validation
- *
- * Prevents command injection by:
- * - Using execFile instead of execSync with string concatenation
- * - Validating commands against allowlist
- * - Blocking dangerous shell metacharacters in arguments
- * - Logging all commands for audit
- * - Cross-platform shell detection (Windows: powershell/cmd, Unix: bash)
- *
- * Usage:
- *   const { safeExec, safeExecJSON, getShellConfig } = require('./safe-exec.cjs');
- *   const result = await safeExec('git', ['status']);
- */
-
-const { execFile, spawn } = require('child_process');
-const { promisify } = require('util');
-const os = require('os');
-const execFileAsync = promisify(execFile);
-const Logger = require('./logger.cjs');
-const logger = new Logger();
-
-// Allowlist of safe commands
-const ALLOWED_COMMANDS = new Set([
-  'git', 'node', 'npm', 'npx', 'find', 'grep', 'head', 'tail', 'wc',
-  'mkdir', 'cp', 'mv', 'rm', 'cat', 'echo', 'test', 'ls', 'dir',
-  'pwd', 'cd', 'type', 'where', 'which', 'chmod', 'touch'
-]);
-
-// Dangerous shell metacharacters that could enable injection
-const DANGEROUS_PATTERN = /[;&|`$(){}\\<>]/;
-
-/**
- * Get shell configuration for current platform
- * Returns shell executable and any platform-specific flags
- * @returns {{shell: string, shellFlag: string}} - Shell config object
- */
-function getShellConfig() {
-  const platform = process.platform;
-  
-  if (platform === 'win32') {
-    // Windows: prefer PowerShell if available, fallback to cmd.exe
-    // Check if PowerShell is available
-    try {
-      // PowerShell Core (pwsh) or Windows PowerShell (powershell)
-      const pwshPath = require('path').join(
-        process.env.ProgramFiles || 'C:\\Program Files',
-        'PowerShell', '7', 'pwsh.exe'
-      );
-      if (require('fs').existsSync(pwshPath)) {
-        return { shell: 'pwsh', shellFlag: '-Command' };
-      }
-      return { shell: 'powershell', shellFlag: '-Command' };
-    } catch {
-      return { shell: 'cmd', shellFlag: '/C' };
-    }
-  }
-  
-  // Unix-like platforms (macOS, Linux): use bash or sh
-  return { shell: 'bash', shellFlag: '-c' };
-}
-
-/**
- * Execute a shell command with platform-appropriate shell
- * @param {string} command - Full command string to execute
- * @param {Object} options - Execution options
- * @returns {Promise<string>} - Command stdout
- */
-async function safeShellExec(command, options = {}) {
-  const { timeout = 30000, log = true } = options;
-  const { shell, shellFlag } = getShellConfig();
-  
-  const startTime = Date.now();
-  
-  try {
-    if (log) {
-      logger.info('Executing shell command', {
-        command,
-        shell,
-        platform: process.platform,
-        timestamp: new Date().toISOString()
-      });
-    }
-    
-    const result = await execFileAsync(shell, [shellFlag, command], {
-      timeout,
-      maxBuffer: 10 * 1024 * 1024, // 10MB buffer
-      windowsHide: true // Prevent console flash on Windows
-    });
-    
-    const duration = Date.now() - startTime;
-    if (log) {
-      logger.debug('Shell command completed', {
-        command,
-        shell,
-        duration,
-        stdout_length: result.stdout?.length || 0
-      });
-    }
-    
-    return result.stdout.trim();
-  } catch (err) {
-    const duration = Date.now() - startTime;
-    logger.error('Shell command failed', {
-      command,
-      shell,
-      error: err.message,
-      duration,
-      code: err.code,
-      signal: err.signal,
-      platform: process.platform
-    });
-    throw err;
-  }
-}
-
-/**
- * Validate command is in allowlist
- * @param {string} cmd - Command to validate
- * @throws {Error} If command not allowed
- */
-function validateCommand(cmd) {
-  const baseCmd = cmd.split(' ')[0].toLowerCase();
-  if (!ALLOWED_COMMANDS.has(baseCmd)) {
-    throw new Error(`Command not allowed: ${cmd}. Allowed: ${Array.from(ALLOWED_COMMANDS).join(', ')}`);
-  }
-}
-
-/**
- * Validate arguments don't contain injection patterns
- * @param {string[]} args - Arguments to validate
- * @throws {Error} If dangerous pattern found
- */
-function validateArgs(args) {
-  for (const arg of args) {
-    if (DANGEROUS_PATTERN.test(arg)) {
-      throw new Error(`Dangerous argument rejected: ${arg}`);
-    }
-  }
-}
-
-/**
- * Execute command safely with validation and logging
- * @param {string} cmd - Command to execute
- * @param {string[]} args - Command arguments
- * @param {Object} options - Execution options
- * @returns {Promise<string>} - Command stdout
- */
-async function safeExec(cmd, args = [], options = {}) {
-  const { timeout = 30000, log = true } = options;
-  
-  // Validate command and arguments
-  validateCommand(cmd);
-  validateArgs(args);
-  
-  const startTime = Date.now();
-  
-  try {
-    if (log) {
-      logger.info('Executing command', { 
-        cmd, 
-        args, 
-        timestamp: new Date().toISOString() 
-      });
-    }
-    
-    const result = await execFileAsync(cmd, args, { 
-      timeout,
-      maxBuffer: 10 * 1024 * 1024 // 10MB buffer
-    });
-    
-    const duration = Date.now() - startTime;
-    if (log) {
-      logger.debug('Command completed', { 
-        cmd, 
-        duration,
-        stdout_length: result.stdout?.length || 0 
-      });
-    }
-    
-    return result.stdout.trim();
-  } catch (err) {
-    const duration = Date.now() - startTime;
-    logger.error('Command failed', { 
-      cmd, 
-      args, 
-      error: err.message,
-      duration,
-      code: err.code,
-      signal: err.signal
-    });
-    throw err;
-  }
-}
-
-/**
- * Execute command and return JSON parsed output
- * @param {string} cmd - Command to execute
- * @param {string[]} args - Command arguments
- * @returns {Promise<Object>} - Parsed JSON output
- */
-async function safeExecJSON(cmd, args = []) {
-  const output = await safeExec(cmd, args);
-  try {
-    return JSON.parse(output);
-  } catch (err) {
-    logger.error('Failed to parse JSON output', { cmd, output });
-    throw new Error(`Invalid JSON from ${cmd}: ${err.message}`);
-  }
-}
-
-module.exports = { safeExec, safeExecJSON, ALLOWED_COMMANDS };
+#!/usr/bin/env node
+
+/**
+ * EZ Safe Exec — Secure command execution with allowlist and validation
+ * 
+ * Prevents command injection by:
+ * - Using execFile instead of execSync with string concatenation
+ * - Validating commands against allowlist
+ * - Blocking dangerous shell metacharacters in arguments
+ * - Logging all commands for audit
+ * 
+ * Usage:
+ *   const { safeExec, safeExecJSON } = require('./safe-exec.cjs');
+ *   const result = await safeExec('git', ['status']);
+ */
+
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const execFileAsync = promisify(execFile);
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+// Allowlist of safe commands
+const ALLOWED_COMMANDS = new Set([
+  'git', 'node', 'npm', 'npx', 'find', 'grep', 'head', 'tail', 'wc',
+  'mkdir', 'cp', 'mv', 'rm', 'cat', 'echo', 'test', 'ls', 'dir',
+  'pwd', 'cd', 'type', 'where', 'which', 'chmod', 'touch'
+]);
+
+// Dangerous shell metacharacters that could enable injection
+const DANGEROUS_PATTERN = /[;&|`$(){}\\<>]/;
+
+/**
+ * Validate command is in allowlist
+ * @param {string} cmd - Command to validate
+ * @throws {Error} If command not allowed
+ */
+function validateCommand(cmd) {
+  const baseCmd = cmd.split(' ')[0].toLowerCase();
+  if (!ALLOWED_COMMANDS.has(baseCmd)) {
+    throw new Error(`Command not allowed: ${cmd}. Allowed: ${Array.from(ALLOWED_COMMANDS).join(', ')}`);
+  }
+}
+
+/**
+ * Validate arguments don't contain injection patterns
+ * @param {string[]} args - Arguments to validate
+ * @throws {Error} If dangerous pattern found
+ */
+function validateArgs(args) {
+  for (const arg of args) {
+    if (DANGEROUS_PATTERN.test(arg)) {
+      throw new Error(`Dangerous argument rejected: ${arg}`);
+    }
+  }
+}
+
+/**
+ * Execute command safely with validation and logging
+ * @param {string} cmd - Command to execute
+ * @param {string[]} args - Command arguments
+ * @param {Object} options - Execution options
+ * @returns {Promise<string>} - Command stdout
+ */
+async function safeExec(cmd, args = [], options = {}) {
+  const { timeout = 30000, log = true } = options;
+  
+  // Validate command and arguments
+  validateCommand(cmd);
+  validateArgs(args);
+  
+  const startTime = Date.now();
+  
+  try {
+    if (log) {
+      logger.info('Executing command', { 
+        cmd, 
+        args, 
+        timestamp: new Date().toISOString() 
+      });
+    }
+    
+    const result = await execFileAsync(cmd, args, { 
+      timeout,
+      maxBuffer: 10 * 1024 * 1024 // 10MB buffer
+    });
+    
+    const duration = Date.now() - startTime;
+    if (log) {
+      logger.debug('Command completed', { 
+        cmd, 
+        duration,
+        stdout_length: result.stdout?.length || 0 
+      });
+    }
+    
+    return result.stdout.trim();
+  } catch (err) {
+    const duration = Date.now() - startTime;
+    logger.error('Command failed', { 
+      cmd, 
+      args, 
+      error: err.message,
+      duration,
+      code: err.code,
+      signal: err.signal
+    });
+    throw err;
+  }
+}
+
+/**
+ * Execute command and return JSON parsed output
+ * @param {string} cmd - Command to execute
+ * @param {string[]} args - Command arguments
+ * @returns {Promise<Object>} - Parsed JSON output
+ */
+async function safeExecJSON(cmd, args = []) {
+  const output = await safeExec(cmd, args);
+  try {
+    return JSON.parse(output);
+  } catch (err) {
+    logger.error('Failed to parse JSON output', { cmd, output });
+    throw new Error(`Invalid JSON from ${cmd}: ${err.message}`);
+  }
+}
+
+module.exports = { safeExec, safeExecJSON, ALLOWED_COMMANDS };

package/ez-agents/bin/lib/session-chain.cjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+
+/**
+ * Session Chain — Navigate linked sessions
+ *
+ * Provides chain navigation, visualization, and repair capabilities
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { SessionChainError } = require('./session-errors.cjs');
+const { defaultLogger: logger } = require('./logger.cjs');
+
+class SessionChain {
+  /**
+   * Create a SessionChain instance
+   * @param {Object} sessionManager - SessionManager instance
+   */
+  constructor(sessionManager) {
+    this.sessionManager = sessionManager;
+  }
+
+  /**
+   * Navigate to adjacent session in chain
+   * @param {string} sessionId - Current session ID
+   * @param {string} direction - Navigation direction ('previous' or 'next')
+   * @returns {Object|null} Adjacent session or null
+   */
+  navigate(sessionId, direction) {
+    const session = this.sessionManager.loadSession(sessionId);
+    if (!session) {
+      return null;
+    }
+
+    const chain = session.metadata?.session_chain || [];
+    const currentIndex = chain.indexOf(sessionId);
+
+    if (currentIndex === -1) {
+      // Session not in chain, check if it's the last one
+      logger.warn('Session not in chain', { sessionId });
+      return null;
+    }
+
+    if (direction === 'previous') {
+      if (currentIndex > 0) {
+        const previousId = chain[currentIndex - 1];
+        return this.sessionManager.loadSession(previousId);
+      }
+      return null;
+    }
+
+    if (direction === 'next') {
+      if (currentIndex < chain.length - 1) {
+        const nextId = chain[currentIndex + 1];
+        return this.sessionManager.loadSession(nextId);
+      }
+      return null;
+    }
+
+    throw new SessionChainError(`Invalid direction: ${direction}`, chain);
+  }
+
+  /**
+   * Get full chain as array of session objects
+   * @param {string} sessionId - Session ID in the chain
+   * @returns {Array} Array of session objects
+   */
+  getChain(sessionId) {
+    const session = this.sessionManager.loadSession(sessionId);
+    if (!session) {
+      return [];
+    }
+
+    const chain = session.metadata?.session_chain || [];
+    const chainSessions = [];
+
+    for (const id of chain) {
+      const chainSession = this.sessionManager.loadSession(id);
+      if (chainSession) {
+        chainSessions.push(chainSession);
+      } else {
+        logger.warn('Missing session in chain', { id });
+      }
+    }
+
+    // Include current session if not already in chain
+    if (!chain.includes(sessionId)) {
+      chainSessions.push(session);
+    }
+
+    return chainSessions;
+  }
+
+  /**
+   * Get chain visualization string
+   * @param {string} sessionId - Session ID
+   * @returns {string} Formatted chain visualization
+   */
+  getChainVisualization(sessionId) {
+    const session = this.sessionManager.loadSession(sessionId);
+    if (!session) {
+      return `Session not found: ${sessionId}`;
+    }
+
+    const chain = session.metadata?.session_chain || [];
+    const currentIndex = chain.indexOf(sessionId);
+
+    let viz = `Session Chain for ${sessionId}:\n\n`;
+
+    chain.forEach((id, index) => {
+      const chainSession = this.sessionManager.loadSession(id);
+      const startedAt = chainSession?.metadata?.started_at || 'Unknown';
+      const status = chainSession?.metadata?.status || 'unknown';
+      const marker = index === currentIndex ? ' <-- Current' : '';
+      viz += `[${index + 1}] ${id} (${startedAt}) - ${status}${marker}\n`;
+    });
+
+    if (!chain.includes(sessionId)) {
+      const startedAt = session.metadata?.started_at || 'Unknown';
+      const status = session.metadata?.status || 'unknown';
+      viz += `[${chain.length + 1}] ${sessionId} (${startedAt}) - ${status} <-- Current\n`;
+    }
+
+    viz += `\nNavigation:\n`;
+    if (currentIndex > 0) {
+      viz += `- Previous: ${chain[currentIndex - 1]}\n`;
+    } else {
+      viz += `- Previous: none\n`;
+    }
+
+    if (currentIndex < chain.length - 1) {
+      viz += `- Next: ${chain[currentIndex + 1]}\n`;
+    } else {
+      viz += `- Next: none\n`;
+    }
+
+    return viz;
+  }
+
+  /**
+   * Repair broken chain links
+   * @param {string} sessionId - Session ID
+   * @returns {Object} Repair result with warnings
+   */
+  repairChain(sessionId) {
+    const session = this.sessionManager.loadSession(sessionId);
+    if (!session) {
+      throw new SessionChainError(`Session not found: ${sessionId}`, []);
+    }
+
+    const chain = session.metadata?.session_chain || [];
+    const warnings = [];
+    const repaired = [];
+
+    // Get all available sessions
+    const allSessions = this.sessionManager.listSessions();
+    const availableIds = new Set(allSessions.map(s => s.session_id));
+
+    // Find missing links
+    const missingLinks = [];
+    for (const id of chain) {
+      if (!availableIds.has(id)) {
+        missingLinks.push(id);
+      }
+    }
+
+    if (missingLinks.length === 0) {
+      return { repaired: false, warnings: ['Chain is intact'] };
+    }
+
+    // Attempt to repair by finding closest timestamp match
+    for (const missingId of missingLinks) {
+      const match = this._findClosestSessionMatch(missingId, allSessions);
+      if (match) {
+        logger.info('Auto-repaired chain link', { missing: missingId, found: match.session_id });
+        repaired.push({ missing: missingId, found: match.session_id });
+      } else {
+        warnings.push(`Unrecoverable link: ${missingId}`);
+      }
+    }
+
+    // Update chain with repaired links
+    if (repaired.length > 0) {
+      const newChain = chain.map(id => {
+        const repair = repaired.find(r => r.missing === id);
+        return repair ? repair.found : id;
+      });
+
+      this.sessionManager.updateSession(sessionId, {
+        metadata: { session_chain: newChain }
+      });
+    }
+
+    return {
+      repaired: repaired.length > 0,
+      repairs: repaired,
+      warnings
+    };
+  }
+
+  /**
+   * Find closest session match by timestamp
+   * @private
+   */
+  _findClosestSessionMatch(missingId, allSessions) {
+    // Extract timestamp from missing ID
+    const timestampMatch = missingId.match(/session-(.+)/);
+    if (!timestampMatch) {
+      return null;
+    }
+
+    const missingTimestamp = timestampMatch[1];
+
+    // Find session with closest timestamp
+    let closestMatch = null;
+    let minDiff = Infinity;
+
+    for (const session of allSessions) {
+      const sessionTimestamp = session.session_id.replace('session-', '');
+      const diff = this._compareTimestamps(missingTimestamp, sessionTimestamp);
+
+      if (diff < minDiff) {
+        minDiff = diff;
+        closestMatch = session;
+      }
+    }
+
+    // Only return match if within reasonable threshold (1 hour)
+    if (minDiff < 3600000) {
+      return closestMatch;
+    }
+
+    return null;
+  }
+
+  /**
+   * Compare timestamps and return difference in ms
+   * @private
+   */
+  _compareTimestamps(ts1, ts2) {
+    try {
+      const date1 = new Date(ts1.replace(/-/g, ':').replace('T', ' '));
+      const date2 = new Date(ts2.replace(/-/g, ':').replace('T', ' '));
+      return Math.abs(date1 - date2);
+    } catch {
+      return Infinity;
+    }
+  }
+
+  /**
+   * Add session to chain
+   * @param {string} sessionId - Session ID to add to
+   * @param {string} linkedSessionId - Session ID to link
+   * @param {string} position - Position ('before' or 'after')
+   * @returns {boolean} Success
+   */
+  addToChain(sessionId, linkedSessionId, position = 'after') {
+    const session = this.sessionManager.loadSession(sessionId);
+    if (!session) {
+      return false;
+    }
+
+    const linkedSession = this.sessionManager.loadSession(linkedSessionId);
+    if (!linkedSession) {
+      return false;
+    }
+
+    let chain = session.metadata?.session_chain || [];
+
+    // Ensure current session is in chain
+    if (!chain.includes(sessionId)) {
+      chain.push(sessionId);
+    }
+
+    const currentIndex = chain.indexOf(sessionId);
+
+    if (position === 'after') {
+      // Insert after current
+      chain.splice(currentIndex + 1, 0, linkedSessionId);
+    } else if (position === 'before') {
+      // Insert before current
+      chain.splice(currentIndex, 0, linkedSessionId);
+    }
+
+    // Update both sessions
+    this.sessionManager.updateSession(sessionId, {
+      metadata: { session_chain: chain }
+    });
+
+    // Also update linked session's chain
+    const linkedChain = linkedSession.metadata?.session_chain || [];
+    if (!linkedChain.includes(sessionId)) {
+      linkedChain.push(sessionId);
+      this.sessionManager.updateSession(linkedSessionId, {
+        metadata: { session_chain: linkedChain }
+      });
+    }
+
+    logger.info('Session added to chain', { sessionId, linkedSessionId, position });
+    return true;
+  }
+}
+
+module.exports = SessionChain;