scripts-orchestrator 2.7.0 → 2.8.0

package/README.md

@@ -31,6 +31,9 @@ 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
+- **Git-Based Caching**: Automatically skips execution when git state is unchanged
 - **Comprehensive Logging**: Detailed logging of command execution and results
 
 ## Configuration
@@ -45,6 +48,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',
@@ -155,6 +162,52 @@ export default {
 };
 ```
 
+### 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
@@ -295,9 +348,25 @@ 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
+- 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
 
+## 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/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,78 @@ 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}`);
+    }
+  }
+
+  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,6 +1,7 @@
 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) {
@@ -14,6 +15,7 @@ export class Orchestrator {
     this.failedCommands = [];
     this.skippedCommands = [];
     this.commandTimings = new Map();
+    this.gitCache = new GitCache(logFolder);
     
     // Set the log folder in process manager
     if (logFolder) {
@@ -62,6 +64,7 @@ export class Orchestrator {
       process_tracking = false,
       health_check,
       kill_command,
+      env,
     } = commandConfig;
 
     const startTime = Date.now();
@@ -162,6 +165,7 @@ export class Orchestrator {
         healthCheck: health_check,
         kill_command,
         isRetry: attempt > 1,
+        env,
       });
       commandOutput = output;
       result = success;
@@ -235,6 +239,13 @@ 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;
@@ -338,6 +349,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/lib/process-manager.js

@@ -37,7 +37,7 @@ 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');
     // Use only the first word of the command for the log filename
@@ -62,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,
@@ -80,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}`);
@@ -235,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));
     
@@ -255,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scripts-orchestrator",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "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: [