scripts-orchestrator 2.7.1 → 2.9.0

package/README.md

@@ -26,6 +26,7 @@ npm install --save-dev scripts-orchestrator
 ## Features
 
 - **Parallel Execution**: Runs multiple commands concurrently for faster execution
+- **Sequential Mode**: Option to run all commands sequentially for low CPU machines
 - **Dependency Management**: Handles command dependencies and ensures proper execution order
 - **Background Processes**: Supports running commands in the background with health checks
 - **Retry Mechanism**: Configurable retry attempts for failed commands
@@ -33,6 +34,7 @@ npm install --save-dev scripts-orchestrator
 - **Health Checks**: Verifies service availability before proceeding
 - **Environment Variables**: Pass custom environment variables to commands
 - **Optional Phases**: Mark phases as optional and run them selectively
+- **Git-Based Caching**: Automatically skips execution when git state is unchanged
 - **Comprehensive Logging**: Detailed logging of command execution and results
 
 ## Configuration
@@ -255,6 +257,12 @@ The orchestrator doesn't care what the commands do - it just ensures they run (i
 
    # Run with verbose logging
    npm run scripts-orchestrator -- --verbose
+
+   # Run in sequential mode (for low CPU machines)
+   npm run scripts-orchestrator -- --sequential
+
+   # Specify a custom log folder
+   npm run scripts-orchestrator -- --logFolder ./custom-logs
    ```
 
 ### Starting from a Specific Phase
@@ -337,6 +345,29 @@ npm run scripts-orchestrator -- --phases "build,test,optional-e2e,optional-perfo
 - The orchestrator validates that all specified phases exist
 - Commands in skipped optional phases are marked as "skipped" in the final summary
 
+### Sequential Mode
+
+By default, the orchestrator runs commands within each phase in parallel for optimal performance. However, you can use the `--sequential` flag to run all commands sequentially, which is useful for low CPU machines or when you need to reduce resource consumption.
+
+#### Usage
+```bash
+# Run all commands sequentially instead of in parallel
+npm run scripts-orchestrator -- --sequential
+```
+
+When running in sequential mode:
+- Commands within each phase are executed one at a time
+- Phases still run sequentially (as they always do)
+- If a command fails, the remaining commands in that phase are skipped
+- Lower CPU and memory usage compared to parallel execution
+- Longer total execution time
+
+This is particularly useful for:
+- CI/CD environments with limited resources
+- Development machines with low CPU/memory
+- Debugging individual command failures
+- Avoiding resource contention between commands
+
 ## Error Handling
 
 - The script tracks failed and skipped commands
@@ -347,9 +378,50 @@ npm run scripts-orchestrator -- --phases "build,test,optional-e2e,optional-perfo
 ## Logging
 
 - Each command's output is logged to `scripts-orchestrator-logs/<command>.log` in the current working directory
+- Main orchestrator logs are saved to `scripts-orchestrator-logs/orchestrator-main-<timestamp>.log`
+- Git commit hash is cached in `scripts-orchestrator-logs/.git-hash-cache` for skip detection
 - Provides real-time status updates during execution
 - Summarizes results at the end of execution
 
+### Custom Log Folder
+
+You can customize the log folder location using either the command line or configuration file:
+
+#### Method 1: Command Line Argument
+```bash
+# Use a custom log folder
+npm run scripts-orchestrator -- --logFolder ./my-custom-logs
+```
+
+#### Method 2: Configuration File
+```javascript
+export default {
+  log_folder: './my-custom-logs',  // Custom log folder
+  phases: [
+    // ... your phases
+  ]
+};
+```
+
+**Note**: Command line arguments take precedence over configuration file settings.
+
+All logs (command logs, main orchestrator logs, and git cache) will be stored in the specified folder.
+
+## Git-Based Caching
+
+The orchestrator automatically tracks the git commit hash and repository state to optimize execution:
+
+- **On first run**: Records the current git commit hash in `scripts-orchestrator-logs/.git-hash-cache`
+- **On subsequent runs**: Checks if:
+  - The git commit hash matches the cached hash
+  - There are no staged or unstaged changes in the repository
+- **When conditions are met**: Skips execution entirely with message `✓ Git state unchanged`
+- **When conditions fail**: Runs normally and updates the cache on successful completion
+
+This feature is particularly useful in CI/CD pipelines where the same commit might be processed multiple times, saving time and resources by avoiding redundant executions.
+
+**Note**: The cache is only updated on successful execution. Failed runs will not update the cache, ensuring subsequent runs will retry.
+
 ## Exit Codes
 
 - `0`: All commands executed successfully

package/index.js

@@ -31,6 +31,10 @@ const argv = yargs(hideBin(process.argv))
     type: 'string',
     description: 'Specify the directory for log files',
   })
+  .option('sequential', {
+    type: 'boolean',
+    description: 'Run all commands sequentially instead of in parallel (for low CPU machines)',
+  })
   .help()
   .alias('h', 'help')
   .parse();
@@ -41,6 +45,7 @@ const configPath = args[0] || './scripts-orchestrator.config.js';
 let startPhase = argv.phase;
 let logFolder = argv.logFolder;
 const phases = argv.phases ? argv.phases.split(',').map(p => p.trim()) : null;
+const sequential = argv.sequential || false;
 
 // Validate config file exists
 if (!fs.existsSync(configPath)) {
@@ -64,8 +69,13 @@ if (!logFolder && commandsConfig.log_folder) {
   logFolder = commandsConfig.log_folder;
 }
 
+// Set the log folder for the main orchestrator logs if specified
+if (logFolder) {
+  log.setLogFolder(logFolder);
+}
+
 // Create and run the orchestrator
-const orchestrator = new Orchestrator(commandsConfig, startPhase, logFolder, phases);
+const orchestrator = new Orchestrator(commandsConfig, startPhase, logFolder, phases, sequential);
 
 // Enhanced signal handlers
 const handleSignal = async (signal) => {

package/lib/git-cache.js

@@ -0,0 +1,187 @@
+import { spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { log } from './logger.js';
+
+export class GitCache {
+  constructor(logFolder = 'scripts-orchestrator-logs') {
+    this.logFolder = logFolder;
+    this.cacheFileName = '.git-hash-cache';
+  }
+
+  /**
+   * Execute a git command and return the output
+   * @param {string[]} args - Git command arguments
+   * @returns {Promise<{success: boolean, output: string}>}
+   */
+  async executeGitCommand(args) {
+    return new Promise((resolve) => {
+      const gitProcess = spawn('git', args, {
+        cwd: process.cwd(),
+        shell: false,
+      });
+
+      let output = '';
+      let errorOutput = '';
+
+      gitProcess.stdout.on('data', (data) => {
+        output += data.toString();
+      });
+
+      gitProcess.stderr.on('data', (data) => {
+        errorOutput += data.toString();
+      });
+
+      gitProcess.on('close', (code) => {
+        if (code === 0) {
+          resolve({ success: true, output: output.trim() });
+        } else {
+          resolve({ success: false, output: errorOutput.trim() });
+        }
+      });
+
+      gitProcess.on('error', (error) => {
+        resolve({ success: false, output: error.message });
+      });
+    });
+  }
+
+  /**
+   * Get the current git commit hash
+   * @returns {Promise<string|null>}
+   */
+  async getCurrentCommitHash() {
+    const result = await this.executeGitCommand(['rev-parse', 'HEAD']);
+    if (result.success) {
+      return result.output;
+    }
+    log.verbose(`Failed to get git commit hash: ${result.output}`);
+    return null;
+  }
+
+  /**
+   * Check if there are any staged or unstaged changes
+   * @returns {Promise<boolean>}
+   */
+  async hasGitChanges() {
+    // Check for staged and unstaged changes
+    const statusResult = await this.executeGitCommand(['status', '--porcelain']);
+    
+    if (!statusResult.success) {
+      log.verbose(`Failed to check git status: ${statusResult.output}`);
+      // If we can't check git status, assume there are changes to be safe
+      return true;
+    }
+
+    // If there's any output, there are changes
+    return statusResult.output.length > 0;
+  }
+
+  /**
+   * Get the path to the cache file
+   * @returns {string}
+   */
+  getCacheFilePath() {
+    const baseDir = this.logFolder ? path.resolve(this.logFolder) : process.cwd();
+    const LOGS_DIR = path.join(baseDir, 'scripts-orchestrator-logs');
+    return path.join(LOGS_DIR, this.cacheFileName);
+  }
+
+  /**
+   * Read the cached git hash
+   * @returns {string|null}
+   */
+  readCachedHash() {
+    const cacheFilePath = this.getCacheFilePath();
+    
+    try {
+      if (fs.existsSync(cacheFilePath)) {
+        const cachedHash = fs.readFileSync(cacheFilePath, 'utf8').trim();
+        log.verbose(`Read cached git hash: ${cachedHash}`);
+        return cachedHash;
+      }
+    } catch (error) {
+      log.verbose(`Failed to read cached git hash: ${error.message}`);
+    }
+    
+    return null;
+  }
+
+  /**
+   * Write the current git hash to cache
+   * @param {string} hash
+   * @returns {boolean}
+   */
+  writeCachedHash(hash) {
+    const cacheFilePath = this.getCacheFilePath();
+    
+    try {
+      // Ensure the directory exists
+      const cacheDir = path.dirname(cacheFilePath);
+      if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+      }
+      
+      fs.writeFileSync(cacheFilePath, hash, 'utf8');
+      log.verbose(`Wrote git hash to cache: ${hash}`);
+      return true;
+    } catch (error) {
+      log.error(`Failed to write git hash to cache: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Check if the orchestrator should skip running based on git state
+   * @returns {Promise<boolean>} - true if should skip, false if should run
+   */
+  async shouldSkipExecution() {
+    log.verbose('Checking git state for caching...');
+
+    // Get current commit hash
+    const currentHash = await this.getCurrentCommitHash();
+    if (!currentHash) {
+      log.verbose('Could not get current git hash, will not skip execution');
+      return false;
+    }
+
+    // Get cached hash
+    const cachedHash = this.readCachedHash();
+    if (!cachedHash) {
+      log.verbose('No cached git hash found, will not skip execution');
+      return false;
+    }
+
+    // Check if hashes match
+    if (currentHash !== cachedHash) {
+      log.verbose(`Git hash changed (${cachedHash.substring(0, 7)} -> ${currentHash.substring(0, 7)}), will not skip execution`);
+      return false;
+    }
+
+    // Check for uncommitted changes
+    const hasChanges = await this.hasGitChanges();
+    if (hasChanges) {
+      log.verbose('Git repository has uncommitted changes, will not skip execution');
+      return false;
+    }
+
+    // All conditions met - can skip
+    log.info(`✓ Git state unchanged (${currentHash.substring(0, 7)}), skipping execution`);
+    return true;
+  }
+
+  /**
+   * Update the cached git hash with the current commit
+   * @returns {Promise<void>}
+   */
+  async updateCache() {
+    const currentHash = await this.getCurrentCommitHash();
+    if (currentHash) {
+      this.writeCachedHash(currentHash);
+    }
+  }
+}
+
+// Export a singleton instance
+export const gitCache = new GitCache();
+

package/lib/index.js

@@ -2,6 +2,7 @@ import { Orchestrator } from './orchestrator.js';
 import { ProcessManager } from './process-manager.js';
 import { HealthCheck } from './health-check.js';
 import { Logger } from './logger.js';
+import { GitCache } from './git-cache.js';
 
-export { Orchestrator, ProcessManager, HealthCheck, Logger };
+export { Orchestrator, ProcessManager, HealthCheck, Logger, GitCache };
 export default Orchestrator; 

package/lib/logger.js

@@ -1,6 +1,8 @@
 import chalk from 'chalk';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
+import fs from 'fs';
+import path from 'path';
 
 const argv = yargs(hideBin(process.argv))
   .option('verbose', {
@@ -25,27 +27,91 @@ const argv = yargs(hideBin(process.argv))
 class Logger {
   constructor() {
     this.isVerbose = argv.verbose;
+    this.logFolder = argv.logFolder || 'scripts-orchestrator-logs';
+    this.logFile = null;
+    this.logStream = null;
+    this.initializeLogFile();
+  }
+
+  initializeLogFile() {
+    try {
+      // Create log directory if it doesn't exist
+      if (!fs.existsSync(this.logFolder)) {
+        fs.mkdirSync(this.logFolder, { recursive: true });
+      }
+
+      // Create main log file with timestamp
+      const timestamp = new Date().toISOString().replace(/:/g, '-').replace(/\..+/, '');
+      this.logFile = path.join(this.logFolder, `orchestrator-main-${timestamp}.log`);
+      
+      // Create write stream
+      this.logStream = fs.createWriteStream(this.logFile, { flags: 'a' });
+      
+      // Handle stream errors
+      this.logStream.on('error', (err) => {
+        console.error(`Error writing to log file: ${err.message}`);
+      });
+
+      // Ensure the stream is closed on process exit
+      process.on('exit', () => {
+        if (this.logStream) {
+          this.logStream.end();
+        }
+      });
+
+      // Write initial log entry
+      this.writeToFile(`[START] Orchestrator started at ${new Date().toISOString()}\n`);
+    } catch (error) {
+      console.error(`Failed to initialize log file: ${error.message}`);
+    }
+  }
+
+  setLogFolder(newLogFolder) {
+    // Close existing stream if it exists
+    if (this.logStream) {
+      this.logStream.end();
+    }
+
+    // Update log folder
+    this.logFolder = newLogFolder;
+    
+    // Reinitialize with new folder
+    this.initializeLogFile();
+  }
+
+  writeToFile(message) {
+    if (this.logStream) {
+      // Strip ANSI color codes for file output
+      // eslint-disable-next-line no-control-regex
+      const cleanMessage = message.replace(/\x1b\[[0-9;]*m/g, '');
+      this.logStream.write(`${cleanMessage}\n`);
+    }
   }
 
   info(message) {
     console.log(chalk.blue(`[INFO] ${message}`));
+    this.writeToFile(`[INFO] ${message}`);
   }
 
   success(message) {
     console.log(chalk.green(`[SUCCESS] ${message}`));
+    this.writeToFile(`[SUCCESS] ${message}`);
   }
 
   error(message) {
     console.error(chalk.red(`[ERROR] ${message}`));
+    this.writeToFile(`[ERROR] ${message}`);
   }
 
   warn(message) {
     console.warn(chalk.yellow(`[WARN] ${message}`));
+    this.writeToFile(`[WARN] ${message}`);
   }
 
   verbose(message) {
     if (this.isVerbose) {
       console.log(chalk.gray(`[VERBOSE] ${message}`));
+      this.writeToFile(`[VERBOSE] ${message}`);
     }
   }
 }

package/lib/orchestrator.js

@@ -1,19 +1,22 @@
 import { processManager } from './process-manager.js';
 import { healthCheck } from './health-check.js';
 import { log } from './logger.js';
+import { GitCache } from './git-cache.js';
 
 export class Orchestrator {
-  constructor(config, startPhase = null, logFolder = null, phases = null) {
+  constructor(config, startPhase = null, logFolder = null, phases = null, sequential = false) {
     this.config = config;
     this.startPhase = startPhase;
     this.logFolder = logFolder;
     this.phases = phases;
+    this.sequential = sequential;
     this.processManager = processManager;
     this.healthCheck = healthCheck;
     this.logger = log;
     this.failedCommands = [];
     this.skippedCommands = [];
     this.commandTimings = new Map();
+    this.gitCache = new GitCache(logFolder);
     
     // Set the log folder in process manager
     if (logFolder) {
@@ -237,20 +240,44 @@ export class Orchestrator {
 
   async run() {
     try {
+      // Check if we should skip execution based on git state
+      const shouldSkip = await this.gitCache.shouldSkipExecution();
+      if (shouldSkip) {
+        this.logger.success('🎉 No changes detected, skipping execution!');
+        process.exit(0);
+      }
+
       let hasFailures = false;
       let phaseFailed = false;
       let startPhaseFound = false;
 
       // Handle both old array format and new phases format
       if (Array.isArray(this.config)) {
-        // Legacy: Run all commands in parallel
-        const tasks = this.config.map((commandConfig) =>
-          this.executeCommand(commandConfig),
-        );
-        const results = await Promise.all(tasks);
-        hasFailures = results.some(result => !result);
+        // Legacy: Run all commands in parallel or sequential based on flag
+        if (this.sequential) {
+          this.logger.info('🔄 Running in sequential mode');
+          const results = [];
+          for (const commandConfig of this.config) {
+            const result = await this.executeCommand(commandConfig);
+            results.push(result);
+            if (!result) {
+              hasFailures = true;
+              break; // Stop on first failure in sequential mode
+            }
+          }
+        } else {
+          const tasks = this.config.map((commandConfig) =>
+            this.executeCommand(commandConfig),
+          );
+          const results = await Promise.all(tasks);
+          hasFailures = results.some(result => !result);
+        }
       } else if (this.config.phases) {
-        // New: Run phases sequentially, commands within phases in parallel
+        // New: Run phases sequentially, commands within phases in parallel or sequential based on flag
+        if (this.sequential) {
+          this.logger.info('🔄 Running in sequential mode');
+        }
+        
         for (const phase of this.config.phases) {
           // Check if we should start from this phase
           if (this.startPhase && !startPhaseFound) {
@@ -289,11 +316,26 @@ export class Orchestrator {
 
           this.logger.info(`\n🔄 Starting phase: ${phase.name}`);
           
-          const tasks = phase.parallel.map((commandConfig) =>
-            this.executeCommand(commandConfig),
-          );
+          let results;
+          if (this.sequential) {
+            // Run commands sequentially
+            results = [];
+            for (const commandConfig of phase.parallel) {
+              const result = await this.executeCommand(commandConfig);
+              results.push(result);
+              if (!result) {
+                // In sequential mode, stop phase execution on first failure
+                break;
+              }
+            }
+          } else {
+            // Run commands in parallel
+            const tasks = phase.parallel.map((commandConfig) =>
+              this.executeCommand(commandConfig),
+            );
+            results = await Promise.all(tasks);
+          }
           
-          const results = await Promise.all(tasks);
           const phaseHasFailures = results.some(result => !result);
           
           if (phaseHasFailures) {
@@ -340,6 +382,11 @@ export class Orchestrator {
         this.logger.error(`Cleanup failed: ${error.message}`);
       }
       
+      // Update git cache on successful execution
+      if (!hasFailures) {
+        await this.gitCache.updateCache();
+      }
+      
       // Force exit with appropriate status
       if (hasFailures) {
         this.logger.info('Exiting with failure status...');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scripts-orchestrator",
-  "version": "2.7.1",
+  "version": "2.9.0",
   "description": "A powerful script orchestrator for running parallel commands with dependency management, background processes, and health checks",
   "main": "lib/index.js",
   "type": "module",