scripts-orchestrator 2.5.0 → 2.7.0

package/README.md

@@ -57,6 +57,20 @@ Create a configuration file (default: `scripts-orchestrator.config.js`) that def
 }
 ```
 
+### Phase Configuration
+
+When using the phases format, each phase can have the following properties:
+
+```javascript
+{
+  name: 'phase_name',               // The name of the phase
+  optional: true,                   // Whether this phase is optional (default: false)
+  parallel: [                       // Array of commands to run in parallel
+    // ... command configurations
+  ]
+}
+```
+
 ## Example Configurations
 
 Here are some practical examples of how to configure the orchestrator for different scenarios:
@@ -124,6 +138,18 @@ export default {
           status: 'enabled'
         }
       ]
+    },
+    {
+      name: 'optional-e2e',
+      optional: true,
+      parallel: [
+        {
+          command: 'playwright',
+          description: 'Run end-to-end tests',
+          status: 'enabled',
+          attempts: 1
+        }
+      ]
     }
   ]
 };
@@ -171,6 +197,12 @@ The orchestrator doesn't care what the commands do - it just ensures they run (i
 
    # Start from a specific phase with custom config
    npm run scripts-orchestrator -- ./path/to/your/config.js --phase "playwright"
+
+   # Run specific optional phases
+   npm run scripts-orchestrator -- --phases "optional-e2e,optional-performance"
+
+   # Run with verbose logging
+   npm run scripts-orchestrator -- --verbose
    ```
 
 ### Starting from a Specific Phase
@@ -200,6 +232,59 @@ When starting from a specific phase:
 - Commands in skipped phases are marked as "skipped" in the final summary
 - The orchestrator validates that the specified phase exists and shows available phases if not found
 
+### Optional Phases
+
+You can mark phases as optional by adding `optional: true` to the phase configuration. Optional phases will only run if explicitly requested via the `--phases` command line argument.
+
+#### Configuration
+```javascript
+export default {
+  phases: [
+    {
+      name: 'build',
+      parallel: [
+        { command: 'build', description: 'Build the project' }
+      ]
+    },
+    {
+      name: 'optional-e2e',
+      optional: true,  // This phase is optional
+      parallel: [
+        { command: 'playwright', description: 'Run end-to-end tests' }
+      ]
+    },
+    {
+      name: 'optional-performance',
+      optional: true,  // This phase is optional
+      parallel: [
+        { command: 'lighthouse', description: 'Run performance tests' }
+      ]
+    }
+  ]
+};
+```
+
+#### Usage
+```bash
+# Run only the default phases (build, test, etc.)
+npm run scripts-orchestrator
+
+# Run specific optional phases
+npm run scripts-orchestrator -- --phases "optional-e2e"
+
+# Run multiple optional phases
+npm run scripts-orchestrator -- --phases "optional-e2e,optional-performance"
+
+# Run all phases including optional ones
+npm run scripts-orchestrator -- --phases "build,test,optional-e2e,optional-performance"
+```
+
+**Note**: 
+- Optional phases are skipped by default unless explicitly requested
+- You can combine `--phase` and `--phases` arguments
+- The orchestrator validates that all specified phases exist
+- Commands in skipped optional phases are marked as "skipped" in the final summary
+
 ## Error Handling
 
 - The script tracks failed and skipped commands

package/index.js

@@ -9,29 +9,43 @@ import path from 'path';
 import fs from 'fs';
 import { Orchestrator } from './lib/index.js';
 import { log } from './lib/logger.js';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
 
-// Parse command line arguments
-const args = process.argv.slice(2);
-let configPath = './scripts-orchestrator.config.js';
-let startPhase = null;
+// Parse command line arguments using yargs
+const argv = yargs(hideBin(process.argv))
+  .option('verbose', {
+    alias: 'v',
+    type: 'boolean',
+    description: 'Run with verbose logging',
+  })
+  .option('phase', {
+    type: 'string',
+    description: 'Start execution from a specific phase',
+  })
+  .option('phases', {
+    type: 'string',
+    description: 'Comma-separated list of phases to run (for optional phases)',
+  })
+  .option('logFolder', {
+    type: 'string',
+    description: 'Specify the directory for log files',
+  })
+  .help()
+  .alias('h', 'help')
+  .parse();
 
-// Parse arguments
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i];
-  
-  if (arg === '--phase' && i + 1 < args.length) {
-    startPhase = args[i + 1];
-    i++; // Skip the next argument since we consumed it
-  } else if (!arg.startsWith('--') && !configPath) {
-    // First non-flag argument is the config path
-    configPath = arg;
-  }
-}
+// Extract arguments
+const args = argv._;
+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;
 
 // Validate config file exists
 if (!fs.existsSync(configPath)) {
   log.error(`Error: Config file not found at ${configPath}`);
-  log.error('Usage: scripts-orchestrator [path-to-config-file] [--phase <phase-name>]');
+  log.error('Use --help for usage information');
   process.exit(1);
 }
 
@@ -45,8 +59,13 @@ if (!startPhase && commandsConfig.start_phase) {
   startPhase = commandsConfig.start_phase;
 }
 
+// Check for log_folder in config if not provided via command line
+if (!logFolder && commandsConfig.log_folder) {
+  logFolder = commandsConfig.log_folder;
+}
+
 // Create and run the orchestrator
-const orchestrator = new Orchestrator(commandsConfig, startPhase);
+const orchestrator = new Orchestrator(commandsConfig, startPhase, logFolder, phases);
 
 // Enhanced signal handlers
 const handleSignal = async (signal) => {

package/lib/logger.js

@@ -8,6 +8,18 @@ const argv = yargs(hideBin(process.argv))
     type: 'boolean',
     description: 'Run with verbose logging',
   })
+  .option('phase', {
+    type: 'string',
+    description: 'Start execution from a specific phase',
+  })
+  .option('phases', {
+    type: 'string',
+    description: 'Comma-separated list of phases to run (for optional phases)',
+  })
+  .option('logFolder', {
+    type: 'string',
+    description: 'Specify the directory for log files',
+  })
   .parse();
 
 class Logger {

package/lib/orchestrator.js

@@ -3,9 +3,11 @@ import { healthCheck } from './health-check.js';
 import { log } from './logger.js';
 
 export class Orchestrator {
-  constructor(config, startPhase = null) {
+  constructor(config, startPhase = null, logFolder = null, phases = null) {
     this.config = config;
     this.startPhase = startPhase;
+    this.logFolder = logFolder;
+    this.phases = phases;
     this.processManager = processManager;
     this.healthCheck = healthCheck;
     this.logger = log;
@@ -13,6 +15,11 @@ export class Orchestrator {
     this.skippedCommands = [];
     this.commandTimings = new Map();
     
+    // Set the log folder in process manager
+    if (logFolder) {
+      this.processManager.setLogFolder(logFolder);
+    }
+    
     // Flatten commands for easier tracking
     this.allCommands = this.flattenCommands(config);
   }
@@ -47,6 +54,7 @@ export class Orchestrator {
       dependencies = [],
       background = false,
       status = 'enabled',
+      log,
       logFile,
       attempts = 1,
       retry_command,
@@ -149,7 +157,7 @@ export class Orchestrator {
 
       const { success, output } = await this.processManager.runCommand({
         cmd: attempt === 1 ? command : retry_command || command,
-        logFile,
+        logFile: log || logFile, // Prefer 'log' key over 'logFile' for backwards compatibility
         background,
         healthCheck: health_check,
         kill_command,
@@ -207,7 +215,9 @@ export class Orchestrator {
       
       if (this.failedCommands.includes(command)) {
         hasFailures = true;
-        this.logger.error(`- ${command}: ❌${durationStr} (See logs/scripts-orchestrator_${command}.log)`);
+        // Get the actual log path from process manager
+        const logPath = this.processManager.getLogPath(command);
+        this.logger.error(`- ${command}: ❌${durationStr} (See ${logPath})`);
       } else if (this.skippedCommands.includes(command)) {
         hasFailures = true;
         this.logger.warn(`- ${command}: ⚠️${durationStr} (Skipped due to failed dependency)`);
@@ -255,6 +265,17 @@ export class Orchestrator {
             }
           }
 
+          // Check if this is an optional phase that should be skipped
+          if (phase.optional === true && this.phases && !this.phases.includes(phase.name)) {
+            this.logger.info(`\n⏭️  Skipping optional phase: ${phase.name} (not explicitly requested)`);
+            // Mark all commands in this phase as skipped
+            phase.parallel.forEach(({ command }) => {
+              this.skippedCommands.push(command);
+              this.commandTimings.set(command, 0);
+            });
+            continue;
+          }
+
           if (phaseFailed) {
             // Mark all commands in remaining phases as skipped
             phase.parallel.forEach(({ command }) => {
@@ -290,6 +311,16 @@ export class Orchestrator {
         process.exit(1);
       }
 
+      // Validate phases if specified
+      if (this.phases) {
+        const availablePhases = this.config.phases.map(p => p.name);
+        const invalidPhases = this.phases.filter(phase => !availablePhases.includes(phase));
+        if (invalidPhases.length > 0) {
+          this.logger.error(`❌ Invalid phases specified: ${invalidPhases.join(', ')}. Available phases: ${availablePhases.join(', ')}`);
+          process.exit(1);
+        }
+      }
+
       // Check final status
       hasFailures = hasFailures || 
                    this.failedCommands.length > 0 || 

package/lib/process-manager.js

@@ -10,6 +10,20 @@ export class ProcessManager {
     this.logger = log;
     this.backgroundProcesses = [];
     this.backgroundProcessesDetails = [];
+    this.logFolder = 'scripts-orchestrator-logs'; // Default log folder
+  }
+
+  setLogFolder(logFolder) {
+    this.logFolder = logFolder;
+    this.logger.verbose(`Log folder set to: ${logFolder}`);
+  }
+
+  getLogPath(command) {
+    const baseDir = this.logFolder ? path.resolve(this.logFolder) : process.cwd();
+    const LOGS_DIR = path.join(baseDir, 'scripts-orchestrator-logs');
+    // Use only the first word of the command for the log filename
+    const logName = command.split(/\s+/)[0];
+    return path.join(LOGS_DIR, `${logName}.log`);
   }
 
   addBackgroundProcess({ command, url, startedByScript, process_tracking, kill_command }) {
@@ -24,8 +38,11 @@ export class ProcessManager {
   }
 
   async runCommand({ cmd, logFile, background = false, healthCheck = null, kill_command = null, isRetry = false }) {
-    const LOGS_DIR = path.resolve(process.cwd(), 'scripts-orchestrator-logs');
-    const LOG_FILE = logFile || path.join(LOGS_DIR, `${cmd}.log`);
+    const baseDir = this.logFolder ? path.resolve(this.logFolder) : process.cwd();
+    const LOGS_DIR = path.join(baseDir, 'scripts-orchestrator-logs');
+    // Use only the first word of the command for the log filename
+    const logName = cmd.split(/\s+/)[0];
+    const LOG_FILE = logFile || path.join(LOGS_DIR, `${logName}.log`);
 
     try {
       if (!fs.existsSync(LOGS_DIR)) {
@@ -497,4 +514,4 @@ export class ProcessManager {
 }
 
 // For backward compatibility
-export const processManager = new ProcessManager(); 
+export const processManager = new ProcessManager();

package/package.json

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