scripts-orchestrator 2.8.0 → 2.10.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
@@ -256,6 +257,15 @@ 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
+
+   # Force execution even if git state is unchanged
+   npm run scripts-orchestrator -- --force
    ```
 
 ### Starting from a Specific Phase
@@ -338,6 +348,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
@@ -348,10 +381,35 @@ 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:
@@ -367,6 +425,21 @@ This feature is particularly useful in CI/CD pipelines where the same commit mig
 
 **Note**: The cache is only updated on successful execution. Failed runs will not update the cache, ensuring subsequent runs will retry.
 
+### Force Execution
+
+You can bypass the git cache check and force execution even when the git state is unchanged by using the `--force` flag:
+
+```bash
+# Force execution regardless of git state
+npm run scripts-orchestrator -- --force
+```
+
+This is useful when you want to:
+- Re-run commands without making code changes
+- Test configuration changes
+- Debug issues without modifying the codebase
+- Override the cache in CI/CD pipelines
+
 ## Exit Codes
 
 - `0`: All commands executed successfully

package/index.js

@@ -31,6 +31,14 @@ 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)',
+  })
+  .option('force', {
+    type: 'boolean',
+    description: 'Force execution even if git state is unchanged',
+  })
   .help()
   .alias('h', 'help')
   .parse();
@@ -41,6 +49,8 @@ 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;
+const force = argv.force || false;
 
 // Validate config file exists
 if (!fs.existsSync(configPath)) {
@@ -64,8 +74,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, force);
 
 // Enhanced signal handlers
 const handleSignal = async (signal) => {

package/lib/logger.js

@@ -66,6 +66,19 @@ class Logger {
     }
   }
 
+  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

package/lib/orchestrator.js

@@ -4,11 +4,13 @@ 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, force = false) {
     this.config = config;
     this.startPhase = startPhase;
     this.logFolder = logFolder;
     this.phases = phases;
+    this.sequential = sequential;
+    this.force = force;
     this.processManager = processManager;
     this.healthCheck = healthCheck;
     this.logger = log;
@@ -239,11 +241,16 @@ 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);
+      // Check if we should skip execution based on git state (unless forced)
+      if (!this.force) {
+        const shouldSkip = await this.gitCache.shouldSkipExecution();
+        if (shouldSkip) {
+          this.logger.success('🎉 No changes detected, skipping execution!');
+          this.logger.info('💡 To force execution, use: --force');
+          process.exit(0);
+        }
+      } else {
+        this.logger.info('⚡ Force execution enabled, skipping git cache check');
       }
 
       let hasFailures = false;
@@ -252,14 +259,31 @@ export class Orchestrator {
 
       // 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) {
@@ -298,11 +322,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) {

package/package.json

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