scripts-orchestrator 1.2.3 → 2.1.0

package/README.md

@@ -39,13 +39,14 @@ Create a configuration file (default: `scripts-orchestrator.config.js`) that def
 
 ```javascript
 {
-  command: 'command_name',        // The npm script to run
-  description: 'Description',     // Optional description
-  status: 'enabled',             // 'enabled' or 'disabled'
-  attempts: 1,                   // Number of retry attempts
-  dependencies: [],              // Array of dependent commands
-  background: false,             // Whether to run in background
-  health_check: {                // Health check configuration
+  command: 'command_name',           // The npm script to run
+  description: 'Description',        // Optional description
+  status: 'enabled',                 // 'enabled' or 'disabled'
+  attempts: 1,                       // Number of retry attempts
+  dependencies: [],                 // Array of dependent commands
+  background: false,                // Whether to run in background
+  kill_command: 'kill_storybook',   // Optional kill command to kill the process
+  health_check: {                   // Health check configuration
     url: 'http://localhost:port',
     max_attempts: 20,
     interval: 2000
@@ -88,112 +89,48 @@ export default [
 ];
 ```
 
-### Storybook Testing with Background Process
+### Basic Build and Test Pipeline with Phases
 ```javascript
-export default [
-  {
-    command: 'test-storybook',
-    description: 'Run Storybook tests',
-    status: 'enabled',
-    attempts: 2,
-    dependencies: [
-      {
-        command: 'storybook_silent',
-        background: true,
-        wait: 5000,
-        health_check: {
-          url: 'http://localhost:6006',
-          max_attempts: 20,
-          interval: 2000
+export default {
+  phases: [
+    {
+      name: 'build',
+      parallel: [
+        {
+          command: 'build',
+          description: 'Build the project',
+          status: 'enabled',
+          attempts: 1
         }
-      }
-    ]
-  }
-];
-```
-
-### Playwright Testing with Development Server
-```javascript
-export default [
-  {
-    command: 'playwright_ci',
-    description: 'Run Playwright tests',
-    status: 'enabled',
-    attempts: 1,
-    dependencies: [
-      {
-        command: 'dev',
-        background: true,
-        health_check: {
-          url: 'http://localhost:5173',
-          max_attempts: 20,
-          interval: 2000
+      ]
+    },
+    {
+      name: 'test',
+      parallel: [
+        {
+          command: 'test',
+          description: 'Run unit tests',
+          status: 'enabled',
+          attempts: 2,
+          should_retry: (output) => {
+            // Only retry if there are actual test failures
+            const testSummaryMatch = output.match(/Test Suites:.*?(\d+) failed/);
+            return testSummaryMatch && parseInt(testSummaryMatch[1]) > 0;
+          }
+        },
+        {
+          command: 'lint',
+          description: 'Run lint checks',
+          status: 'enabled'
         }
-      }
-    ]
-  }
-];
-```
-
-### Full CI Pipeline with Multiple Checks
-```javascript
-export default [
-  {
-    command: 'build',
-    description: 'Build the project',
-    status: 'enabled',
-    attempts: 1
-  },
-  {
-    command: 'test-ci',
-    description: 'Run unit tests',
-    status: 'enabled',
-    attempts: 2,
-    should_retry: (output) => {
-      const testSummaryMatch = output.match(/Test Suites:.*?(\d+) failed/);
-      const hasTestFailures = testSummaryMatch && parseInt(testSummaryMatch[1]) > 0;
-      const hasCoverageFailures = output.match(/Jest: "global" coverage threshold/);
-      
-      // Only retry for actual test failures, not coverage issues
-      return hasTestFailures;
+      ]
     }
-  },
-  {
-    command: 'test-storybook',
-    description: 'Run Storybook tests',
-    status: 'enabled',
-    attempts: 2,
-    dependencies: [
-      {
-        command: 'storybook_silent',
-        background: true,
-        wait: 5000,
-        health_check: {
-          url: 'http://localhost:6006',
-          max_attempts: 20,
-          interval: 2000
-        }
-      }
-    ]
-  },
-  {
-    command: 'stylelint',
-    description: 'Run stylelint checks',
-    status: 'enabled'
-  },
-  {
-    command: 'lint',
-    description: 'Run lint checks',
-    status: 'enabled'
-  },
-  {
-    command: 'jscpd',
-    description: 'Run code duplication checks',
-    status: 'enabled'
-  }
-];
+  ]
+};
 ```
 
+See more examples [here](./docs/samples.md)
+
 ## Command Types
 
 The orchestrator is completely agnostic to what commands it runs. It can execute any npm scripts. Common use cases include:
@@ -248,6 +185,17 @@ The orchestrator doesn't care what the commands do - it just ensures they run (i
 - `0`: All commands executed successfully
 - `1`: One or more commands failed or were skipped
 
+
+## History
+See [versions](./docs/versions.md)
+
+## Roadmap
+- Better UX to indicate what is happening
+- Tests to avoid regression
+- Retry should append to the log file
+- Run any shell command rather than assume the command is specified in package.json (? tentative)
+
+
 ## Disclaimer
 
 This software is provided "as is", without warranty of any kind, express or implied. The author(s) shall not be liable for any claims, damages, or other liabilities arising from the use of this software. Users are responsible for testing and verifying the software in their own environment before using it in production.
@@ -258,3 +206,5 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## License
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+

package/lib/orchestrator.js

@@ -11,6 +11,22 @@ export class Orchestrator {
     this.failedCommands = [];
     this.skippedCommands = [];
     this.commandTimings = new Map();
+    
+    // Flatten commands for easier tracking
+    this.allCommands = this.flattenCommands(config);
+  }
+
+  flattenCommands(config) {
+    // Handle both old array format and new phases format
+    if (Array.isArray(config)) {
+      return config;
+    }
+    
+    if (config.phases) {
+      return config.phases.flatMap(phase => phase.parallel || []);
+    }
+    
+    return [];
   }
 
   formatDuration(ms) {
@@ -36,6 +52,7 @@ export class Orchestrator {
       should_retry,
       process_tracking = false,
       health_check,
+      kill_command,
     } = commandConfig;
 
     const startTime = Date.now();
@@ -71,6 +88,7 @@ export class Orchestrator {
           url: checkUrl,
           startedByScript: false,
           process_tracking,
+          kill_command,
         });
         this.commandTimings.set(command, Date.now() - startTime);
         visited.delete(command);
@@ -128,12 +146,14 @@ export class Orchestrator {
         await new Promise((resolve) => setTimeout(resolve, 1000));
       }
 
-      const { success, output } = await this.processManager.runCommand(
-        attempt === 1 ? command : retry_command || command,
+      const { success, output } = await this.processManager.runCommand({
+        cmd: attempt === 1 ? command : retry_command || command,
         logFile,
         background,
-        health_check,
-      );
+        healthCheck: health_check,
+        kill_command,
+        isRetry: attempt > 1,
+      });
       commandOutput = output;
       result = success;
 
@@ -170,7 +190,7 @@ export class Orchestrator {
     this.logger.info('\nCommand Summary:');
     let hasFailures = false;
     
-    this.config.forEach(({ command }) => {
+    this.allCommands.forEach(({ command }) => {
       const duration = this.commandTimings.get(command);
       const durationStr = duration ? ` (${this.formatDuration(duration)})` : '';
       
@@ -194,18 +214,42 @@ export class Orchestrator {
 
   async run() {
     try {
-      // Run top-level commands in parallel
-      const tasks = this.config.map((commandConfig) =>
-        this.executeCommand(commandConfig),
-      );
+      let hasFailures = false;
 
-      // Wait for all top-level commands to complete
-      const results = await Promise.all(tasks);
-      
-      // Check if any command failed
-      const hasFailures = results.some(result => !result) || 
-                         this.failedCommands.length > 0 || 
-                         this.skippedCommands.length > 0;
+      // 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);
+      } else if (this.config.phases) {
+        // New: Run phases sequentially, commands within phases in parallel
+        for (const phase of this.config.phases) {
+          this.logger.info(`\n🔄 Starting phase: ${phase.name}`);
+          
+          const tasks = phase.parallel.map((commandConfig) =>
+            this.executeCommand(commandConfig),
+          );
+          
+          const results = await Promise.all(tasks);
+          const phaseHasFailures = results.some(result => !result);
+          
+          if (phaseHasFailures) {
+            hasFailures = true;
+            this.logger.error(`❌ Phase "${phase.name}" completed with failures`);
+            break; // Stop executing remaining phases on failure
+          } else {
+            this.logger.success(`✅ Phase "${phase.name}" completed successfully`);
+          }
+        }
+      }
+
+      // Check final status
+      hasFailures = hasFailures || 
+                   this.failedCommands.length > 0 || 
+                   this.skippedCommands.length > 0;
 
       // Add a small delay to ensure all processes have finished
       await new Promise((resolve) => setTimeout(resolve, 1000));

package/lib/process-manager.js

@@ -11,17 +11,18 @@ export class ProcessManager {
     this.backgroundProcessesDetails = [];
   }
 
-  addBackgroundProcess({ command, url, startedByScript, process_tracking }) {
+  addBackgroundProcess({ command, url, startedByScript, process_tracking, kill_command }) {
     this.logger.verbose(`Adding background process: ${command} (${url})`);
     this.backgroundProcessesDetails.push({
       command,
       url,
       startedByScript,
       process_tracking,
+      kill_command,
     });
   }
 
-  async runCommand(cmd, logFile, background = false, healthCheck = null) {
+  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`);
 
@@ -31,8 +32,12 @@ export class ProcessManager {
         fs.mkdirSync(LOGS_DIR, { recursive: true });
       }
 
-      this.logger.verbose(`Clearing log file at ${LOG_FILE}`);
-      fs.writeFileSync(LOG_FILE, ''); // Clear the log file
+      if (!isRetry) {
+        this.logger.verbose(`Clearing log file at ${LOG_FILE}`);
+        fs.writeFileSync(LOG_FILE, ''); // Clear the log file
+      } else {
+        this.logger.verbose(`Appending to existing log file at ${LOG_FILE} (retry attempt)`);
+      }
     } catch (error) {
       this.logger.error(`Failed to setup log file: ${error.message}`);
       return Promise.resolve({ success: false, output: '' });
@@ -40,15 +45,16 @@ export class ProcessManager {
 
     return new Promise((resolve) => {
       this.logger.info(`Running: npm run ${cmd}`);
+      
+      // Create isolated environment for each process
+      const isolatedEnv = this.createIsolatedEnvironment({ command: cmd });
+      
       const options = {
         shell: true,
         detached: background,
         stdio: ['ignore', 'pipe', 'pipe'],
         cwd: process.cwd(),
-        env: {
-          ...process.env,
-          NODE_ENV: process.env.NODE_ENV || 'development',
-        },
+        env: isolatedEnv,
         windowsHide: true,
         ...(background ? { processGroup: true } : {}),
       };
@@ -102,6 +108,7 @@ export class ProcessManager {
                   startTime: Date.now(),
                   url: healthCheck?.url,
                   startedByScript: true,
+                  kill_command,
                 });
                 
                 this.logger.verbose(`Unreferencing process ${processGroupId}`);
@@ -171,10 +178,46 @@ export class ProcessManager {
     });
   }
 
+  createIsolatedEnvironment({ command }) {
+    // Create a deep copy to avoid any reference sharing
+    const baseEnv = JSON.parse(JSON.stringify(process.env));
+    
+    // Set standard environment variables
+    const isolatedEnv = {
+      ...baseEnv,
+      NODE_ENV: process.env.NODE_ENV || 'development',
+      // Add command-specific environment isolation
+      SCRIPTS_ORCHESTRATOR_COMMAND: command,
+      SCRIPTS_ORCHESTRATOR_PID: process.pid.toString(),
+      // Force fresh PATH to avoid any dynamic modifications
+      PATH: process.env.PATH,
+      // Ensure npm/node paths are isolated
+      npm_config_cache: path.join(process.cwd(), 'node_modules/.cache/npm'),
+      // Prevent npm from sharing config between parallel processes
+      npm_config_progress: 'false',
+      npm_config_loglevel: 'error',
+    };
+
+    // Remove any potentially problematic environment variables
+    delete isolatedEnv.npm_lifecycle_event;
+    delete isolatedEnv.npm_lifecycle_script;
+    
+    return isolatedEnv;
+  }
+
   async cleanup() {
     this.logger.info('\nCleaning up background processes...');
+    
+    // Debug: Log the number of processes we're tracking
+    this.logger.info(`- Found ${this.backgroundProcessesDetails.length} background processes to clean up`);
+    
+    // Debug: Log each process details
+    this.backgroundProcessesDetails.forEach(({ command, pgid, url, startedByScript, kill_command }, index) => {
+      this.logger.verbose(`- Process ${index + 1}: command=${command}, pgid=${pgid}, url=${url}, startedByScript=${startedByScript}, kill_command=${kill_command}`);
+    });
+    
     const killPromises = this.backgroundProcessesDetails.map(
-      async ({ command, pgid, url, startedByScript }) => {
+      async ({ command, pgid, url, startedByScript, kill_command }) => {
         if (!startedByScript) {
           this.logger.verbose(
             `- Skipping cleanup for ${command} (${url}) as it was not started by this script`,
@@ -182,6 +225,26 @@ export class ProcessManager {
           return;
         }
 
+        this.logger.verbose(`- Processing cleanup for ${command} (kill_command: ${kill_command})`);
+
+        // Try custom kill command first if specified
+        if (kill_command) {
+          try {
+            this.logger.verbose(`- Using custom kill command: npm run ${kill_command}`);
+            const result = await this.runCommand({ cmd: kill_command, logFile: null, background: false });
+            if (result.success) {
+              this.logger.verbose(`- Successfully killed ${command} using custom command`);
+              return;
+            } else {
+              this.logger.verbose('- Custom kill command failed, falling back to process signals');
+            }
+          } catch (error) {
+            this.logger.verbose(`- Custom kill command error: ${error.message}, falling back`);
+          }
+        } else {
+          this.logger.verbose(`- No kill_command specified for ${command}, using process signals`);
+        }
+
         try {
           // First try to kill the process group
           try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scripts-orchestrator",
-  "version": "1.2.3",
+  "version": "2.1.0",
   "description": "A powerful script orchestrator for running parallel commands with dependency management, background processes, and health checks",
   "main": "lib/index.js",
   "type": "module",
@@ -8,7 +8,8 @@
     "scripts-orchestrator": "index.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage --detectOpenHandles --runInBand",
     "start": "node index.js",
     "lint": "eslint .",
     "prepare": "npm run lint"
@@ -29,7 +30,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Pratishthan/scripts-orchestrator"
+    "url": "git+https://github.com/Pratishthan/scripts-orchestrator.git"
   },
   "bugs": {
     "url": "https://github.com/Pratishthan/scripts-orchestrator/issues"
@@ -39,10 +40,14 @@
     "node": ">=14.0.0"
   },
   "dependencies": {
-    "chalk": "^4.1.2"
+    "chalk": "^4.1.2",
+    "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "eslint": "^8.0.0"
+    "@types/jest": "^29.5.14",
+    "eslint": "^8.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.3.3"
   },
   "files": [
     "lib/",

package/scripts-orchestrator.config.js

@@ -1,83 +1,115 @@
-export default [
-  {
-    command: 'build',
-    description: 'Build the project',
-    status: 'enabled',
-    attempts: 1,
-  },
-  {
-    command: 'test-ci',
-    description: 'Run unit tests',
-    status: 'enabled',
-    attempts: 2,
-    should_retry: (output) => {
-      // Check for actual test failures in the summary
-      const testSummaryMatch = output.match(/Test Suites:.*?(\d+) failed/);
-      const hasTestFailures =
-        testSummaryMatch && parseInt(testSummaryMatch[1]) > 0;
+export default {
+  phases: [
+    {
+      name: 'build',
+      parallel: [
+        {
+          command: 'build',
+          description: 'Build the project',
+          status: 'enabled',
+          attempts: 1,
+        },
+        {
+          command: 'stylelint',
+          description: 'Run stylelint checks',
+          status: 'enabled',
+        },
+        { command: 'lint', description: 'Run lint checks', status: 'enabled' },
+        {
+          command: 'jscpd',
+          description: 'Run code duplication checks',
+          status: 'enabled',
+        },
+      ],
+    },
+    {
+      name: 'storybook tests',
+      parallel: [
+        {
+          command: 'test-storybook',
+          description: 'Run Storybook tests',
+          status: 'enabled',
+          attempts: 2,
+          dependencies: [
+            {
+              command: 'storybook_silent',
+              background: true,
+              wait: 5000,
+              kill_command: 'kill_storybook',
+              dependencies: [],
+              // Add process tracking
+              process_tracking: true,
+              // Add health check
+              health_check: {
+                url: 'http://localhost:6006',
+                max_attempts: 20,
+                interval: 2000,
+              },
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'unit tests',
+      parallel: [
+        {
+          command: 'test-ci',
+          description: 'Run unit tests',
+          status: 'enabled',
+          attempts: 2,
+          should_retry: (output) => {
+            // Check for test failures in both formats
+            const testSuiteFailureMatch = output.match(
+              /Test Suites:.*?\(\d+\) failed/,
+            );
+            const individualTestFailureMatch =
+              output.match(/✘\s*(\d+)\s*failing/);
+
+            const hasTestSuiteFailures =
+              testSuiteFailureMatch && parseInt(testSuiteFailureMatch[1]) > 0;
+            const hasIndividualTestFailures =
+              individualTestFailureMatch &&
+              parseInt(individualTestFailureMatch[1]) > 0;
+
+            const hasTestFailures =
+              hasTestSuiteFailures || hasIndividualTestFailures;
 
-      // Check for coverage failures
-      const coverageSummaryMatch = output.match(
-        /Jest: "global" coverage threshold/,
-      );
-      const hasCoverageFailures = coverageSummaryMatch !== null;
+            // Check for "Test suite failed to run" in logs
+            if (output.includes('Test suite failed to run')) {
+              console.error('Certain tests could not be run');
+              return false; // Don't retry if certain tests could not be run
+            }
 
-      if (!hasTestFailures && hasCoverageFailures) {
-        console.log(
-          'Tests have passed but coverage thresholds have not been met',
-        );
-        return false; // Don't retry if only coverage failed
-      }
+            if (!hasTestFailures) {
+              console.log(
+                'Tests have passed but coverage thresholds have not been met',
+              );
+              return false; // Don't retry if only coverage failed
+            }
 
-      return hasTestFailures; // Only retry if there are actual test failures
+            return hasTestFailures; // Only retry if there are actual test failures
+          },
+        },
+      ],
     },
-  },
-  {
-    command: 'test-storybook',
-    description: 'Run Storybook tests',
-    status: 'enabled',
-    attempts: 2,
-    dependencies: [
-      {
-        command: 'storybook_silent',
-        background: true,
-        wait: 5000,
-        kill_script: 'kill_storybook',
-        dependencies: [],
-        // Add process tracking
-        process_tracking: true,
-        // Add health check
-        health_check: {
-          url: 'http://localhost:6006',
-          max_attempts: 20,
-          interval: 2000,
+    {
+      name: 'playwright',
+      parallel: [
+        {
+          command: 'playwright_ci',
+          description: 'Run Playwright tests',
+          status: 'enabled',
+          attempts: 1, //Playwright internally retries in CI mode
+          dependencies: [
+            {
+              command: 'dev',
+              background: true,
+              url: 'http://localhost:5173',
+            },
+          ],
         },
-      },
-    ],
-  },
-  {
-    command: 'stylelint',
-    description: 'Run stylelint checks',
-    status: 'enabled',
-  },
-  { command: 'lint', description: 'Run lint checks', status: 'enabled' },
-  {
-    command: 'jscpd',
-    description: 'Run code duplication checks',
-    status: 'enabled',
-  },
-  {
-    command: 'playwright_ci',
-    description: 'Run Playwright tests',
-    status: 'enabled',
-    attempts: 1, //Playwright internally retries in CI mode
-    dependencies: [
-      {
-        command: 'dev',
-        background: true,
-        url: 'http://localhost:5173',
-        kill: 'application_end',
-      },
-    ],
-  },
-];
+      ],
+    },
+  ],
+};