scripts-orchestrator 2.6.0 → 2.7.1

package/README.md

@@ -31,6 +31,8 @@ npm install --save-dev scripts-orchestrator
 - **Retry Mechanism**: Configurable retry attempts for failed commands
 - **Process Management**: Proper cleanup of background processes
 - **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
 - **Comprehensive Logging**: Detailed logging of command execution and results
 
 ## Configuration
@@ -45,6 +47,10 @@ Create a configuration file (default: `scripts-orchestrator.config.js`) that def
   attempts: 1,                       // Number of retry attempts
   dependencies: [],                 // Array of dependent commands
   background: false,                // Whether to run in background
+  env: {                            // Optional environment variables
+    PORT: 3000,
+    NODE_ENV: 'production'
+  },
   kill_command: 'kill_storybook',   // Optional kill command to kill the process
   health_check: {                   // Health check configuration
     url: 'http://localhost:port',
@@ -57,6 +63,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,11 +144,69 @@ export default {
           status: 'enabled'
         }
       ]
+    },
+    {
+      name: 'optional-e2e',
+      optional: true,
+      parallel: [
+        {
+          command: 'playwright',
+          description: 'Run end-to-end tests',
+          status: 'enabled',
+          attempts: 1
+        }
+      ]
     }
   ]
 };
 ```
 
+### Using Environment Variables
+
+You can pass custom environment variables to commands using the `env` property. This is useful for configuring ports, API endpoints, or any environment-specific settings:
+
+```javascript
+export default {
+  phases: [
+    {
+      name: 'playwright',
+      parallel: [
+        {
+          command: 'playwright_ci',
+          description: 'Run Playwright tests',
+          env: {
+            PLAYWRIGHT_PORT: 5173,
+            API_URL: 'http://localhost:3000',
+            TEST_ENV: 'ci'
+          },
+          status: 'enabled',
+          attempts: 1,
+          dependencies: [
+            {
+              command: 'dev',
+              background: true,
+              env: {
+                PORT: 5173
+              },
+              health_check: {
+                url: 'http://localhost:5173',
+                max_attempts: 20,
+                interval: 2000
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+};
+```
+
+The command will run with the environment variables set, equivalent to:
+```bash
+PLAYWRIGHT_PORT=5173 API_URL=http://localhost:3000 TEST_ENV=ci npm run playwright_ci
+```
+
 See more examples [here](./docs/samples.md)
 
 ## Command Types
@@ -171,6 +249,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 +284,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,33 +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;
-let logFolder = 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 === '--logFolder' && i + 1 < args.length) {
-    logFolder = 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>] [--logFolder <log-directory>]');
+  log.error('Use --help for usage information');
   process.exit(1);
 }
 
@@ -55,7 +65,7 @@ if (!logFolder && commandsConfig.log_folder) {
 }
 
 // Create and run the orchestrator
-const orchestrator = new Orchestrator(commandsConfig, startPhase, logFolder);
+const orchestrator = new Orchestrator(commandsConfig, startPhase, logFolder, phases);
 
 // Enhanced signal handlers
 const handleSignal = async (signal) => {

package/lib/logger.js

@@ -12,6 +12,10 @@ const argv = yargs(hideBin(process.argv))
     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',

package/lib/orchestrator.js

@@ -3,10 +3,11 @@ import { healthCheck } from './health-check.js';
 import { log } from './logger.js';
 
 export class Orchestrator {
-  constructor(config, startPhase = null, logFolder = 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;
@@ -53,6 +54,7 @@ export class Orchestrator {
       dependencies = [],
       background = false,
       status = 'enabled',
+      log,
       logFile,
       attempts = 1,
       retry_command,
@@ -60,6 +62,7 @@ export class Orchestrator {
       process_tracking = false,
       health_check,
       kill_command,
+      env,
     } = commandConfig;
 
     const startTime = Date.now();
@@ -155,11 +158,12 @@ 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,
         isRetry: attempt > 1,
+        env,
       });
       commandOutput = output;
       result = success;
@@ -213,7 +217,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)`);
@@ -261,6 +267,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 }) => {
@@ -296,6 +313,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

@@ -18,6 +18,14 @@ export class ProcessManager {
     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 }) {
     this.logger.verbose(`Adding background process: ${command} (${url})`);
     this.backgroundProcessesDetails.push({
@@ -29,10 +37,12 @@ export class ProcessManager {
     });
   }
 
-  async runCommand({ cmd, logFile, background = false, healthCheck = null, kill_command = null, isRetry = false }) {
+  async runCommand({ cmd, logFile, background = false, healthCheck = null, kill_command = null, isRetry = false, env = null }) {
     const baseDir = this.logFolder ? path.resolve(this.logFolder) : process.cwd();
     const LOGS_DIR = path.join(baseDir, 'scripts-orchestrator-logs');
-    const LOG_FILE = logFile || path.join(LOGS_DIR, `${cmd}.log`);
+    // 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)) {
@@ -52,10 +62,17 @@ export class ProcessManager {
     }
 
     return new Promise((resolve) => {
-      this.logger.info(`Running: npm run ${cmd}`);
+      // Build command with environment variables if provided
+      let fullCommand = `npm run ${cmd}`;
+      if (env && Object.keys(env).length > 0) {
+        const envStr = Object.entries(env).map(([key, value]) => `${key}=${value}`).join(' ');
+        fullCommand = `${envStr} npm run ${cmd}`;
+      }
+      
+      this.logger.info(`Running: ${fullCommand}`);
       
       // Create isolated environment for each process
-      const isolatedEnv = this.createIsolatedEnvironment({ command: cmd });
+      const isolatedEnv = this.createIsolatedEnvironment({ command: cmd, env });
       
       const options = {
         shell: true,
@@ -70,8 +87,8 @@ export class ProcessManager {
       //this.logger.verbose(`Process options: ${JSON.stringify(options, null, 2)}`);
 
       try {
-        this.logger.verbose(`Spawning process with command: npm run ${cmd}`);
-        const processInstance = spawn('npm', ['run', cmd], options);
+        this.logger.verbose(`Spawning process with command: ${fullCommand}`);
+        const processInstance = spawn(fullCommand, [], options);
 
         processInstance.on('error', (error) => {
           this.logger.error(`Failed to start process: ${error.message}`);
@@ -225,7 +242,7 @@ export class ProcessManager {
     });
   }
 
-  createIsolatedEnvironment({ command }) {
+  createIsolatedEnvironment({ command, env = null }) {
     // Create a deep copy to avoid any reference sharing
     const baseEnv = JSON.parse(JSON.stringify(process.env));
     
@@ -245,6 +262,13 @@ export class ProcessManager {
       npm_config_loglevel: 'error',
     };
 
+    // Merge custom environment variables if provided
+    if (env && typeof env === 'object') {
+      Object.entries(env).forEach(([key, value]) => {
+        isolatedEnv[key] = String(value);
+      });
+    }
+
     // Remove any potentially problematic environment variables
     delete isolatedEnv.npm_lifecycle_event;
     delete isolatedEnv.npm_lifecycle_script;
@@ -504,4 +528,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.6.0",
+  "version": "2.7.1",
   "description": "A powerful script orchestrator for running parallel commands with dependency management, background processes, and health checks",
   "main": "lib/index.js",
   "type": "module",

package/scripts-orchestrator.config.js

@@ -99,6 +99,9 @@ export default {
         {
           command: 'playwright_ci',
           description: 'Run Playwright tests',
+          env: {
+            PLAYWRIGHT_PORT: 5173,
+          },
           status: 'enabled',
           attempts: 1, //Playwright internally retries in CI mode
           dependencies: [