scripts-orchestrator 2.12.0 → 2.14.0

package/README.md

@@ -36,6 +36,10 @@ npm install --save-dev scripts-orchestrator
 - **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
+- **Incremental JSON results**: Live-updating `json_results` file as commands complete (v2.14+)
+- **NDJSON event stream**: Machine-readable per-command events for dashboards (v2.14+)
+- **Post-run hook**: Run a shell command after results are written via `post_run` config (v2.14+)
+- **Run-state file**: Library-owned in-progress indicator for live dashboard integration (v2.14+)
 
 ## Configuration
 
@@ -410,6 +414,84 @@ export default {
 
 All logs (command logs, main orchestrator logs, and git cache) will be stored in the specified folder.
 
+## Live Dashboard Integration (v2.14+)
+
+### Incremental JSON results
+
+By default `json_results` is written only at the end of a run. From v2.14 onward the file is
+updated atomically (write-to-temp + rename) after **each command starts or completes**, so
+watchers always see a consistent snapshot:
+
+```json
+{
+  "success": null,
+  "timestamp": "2026-06-04T07:13:21.000Z",
+  "commands": [
+    { "command": "lint-ci", "phase": "lint", "success": true, "durationMs": 4200 },
+    { "command": "playwright_ci", "phase": "tests", "success": null, "startedAt": "2026-06-04T07:13:25.000Z" }
+  ]
+}
+```
+
+`"success": null` at the top level is the in-progress sentinel. It is replaced with `true` or
+`false` when `writeJsonResults` writes the final result.
+
+### NDJSON event stream
+
+Alongside `json_results`, the library writes one NDJSON line per event to
+`<json_results_basename>-events.ndjson`:
+
+```jsonl
+{"type":"command_start","timestamp":"...","command":"lint-ci","phase":"lint","scope":"workspace"}
+{"type":"command_end","timestamp":"...","command":"lint-ci","phase":"lint","success":true,"durationMs":4200}
+{"type":"run_end","timestamp":"...","success":true,"durationMs":12800}
+```
+
+Dashboard tools can `tail -f` this file or watch it with `fs.watch` to get real-time updates
+without parsing human-readable log lines.
+
+### Run-state file (A4)
+
+When `--logFolder` is specified, the library writes `{logFolder}/.scripts-orchestrator-run.json`
+at run start and removes it on run end:
+
+```json
+{
+  "startedAt": "2026-06-04T07:13:17.000Z",
+  "pid": 12345,
+  "phase": "tests",
+  "activeCommand": "playwright_ci"
+}
+```
+
+This file is the authoritative in-progress signal for live dashboards. Its absence means the run
+has finished (or never started).
+
+### Post-run hook (A7)
+
+Add `post_run` to your config to run a shell command **after** `json_results` is written and the
+run-state file is cleared, but **before** `process.exit()`:
+
+```javascript
+export default {
+  json_results: './logs/scripts-orchestrator-results.json',
+  post_run: 'node scripts/generate-report.js',  // called after every run
+  phases: [ /* ... */ ]
+};
+```
+
+The hook receives two environment variables:
+- `SCRIPTS_ORCHESTRATOR_SUCCESS=1` (or `0`) — whether the run succeeded
+- `SCRIPTS_ORCHESTRATOR_EXIT_CODE=0` (or `1`) — same, as a numeric exit code
+
+The hook runs synchronously and its exit code is logged but does not change the orchestrator's
+own exit code.
+
+**Typical use case:** trigger a monorepo rollup report after each workspace finishes:
+```javascript
+post_run: 'node ../../scripts/merge-orchestrator-report.js'
+```
+
 ## Git-Based Caching
 
 The orchestrator automatically tracks the git commit hash and repository state to optimize execution:

package/index.js

@@ -39,6 +39,18 @@ const argv = yargs(hideBin(process.argv))
     type: 'boolean',
     description: 'Force execution even if git state is unchanged',
   })
+  .option('metrics', {
+    type: 'string',
+    description: 'Comma-separated metrics to collect and report: time, memory',
+  })
+  .option('json-results', {
+    type: 'string',
+    description: 'Write results JSON to this path; use "-" for stdout only',
+  })
+  .option('html-results', {
+    type: 'string',
+    description: 'Write HTML report to this path; use "-" for stdout only',
+  })
   .help()
   .alias('h', 'help')
   .parse();
@@ -52,6 +64,8 @@ const phases = argv.phases ? argv.phases.split(',').map(p => p.trim()) : null;
 const sequential = argv.sequential || false;
 const force = argv.force || false;
 
+const validMetrics = ['time', 'memory'];
+
 // Validate config file exists
 if (!fs.existsSync(configPath)) {
   log.error(`Error: Config file not found at ${configPath}`);
@@ -74,13 +88,51 @@ if (!logFolder && commandsConfig.log_folder) {
   logFolder = commandsConfig.log_folder;
 }
 
+// Metrics: CLI overrides config
+let metrics = [];
+if (argv.metrics != null && argv.metrics !== '') {
+  metrics = argv.metrics.split(',').map((m) => m.trim()).filter((m) => validMetrics.includes(m));
+} else if (commandsConfig.metrics != null) {
+  const fromConfig = Array.isArray(commandsConfig.metrics)
+    ? commandsConfig.metrics
+    : String(commandsConfig.metrics).split(',').map((m) => m.trim());
+  metrics = fromConfig.filter((m) => validMetrics.includes(m));
+}
+
+// JSON results path: CLI overrides config
+const jsonResultsPath =
+  argv.jsonResults != null
+    ? argv.jsonResults
+    : (commandsConfig.json_results ?? commandsConfig.json_results_path ?? null);
+
+// HTML results path: CLI overrides config (optional)
+const htmlResultsPath =
+  argv.htmlResults != null
+    ? argv.htmlResults
+    : (commandsConfig.html_results ?? commandsConfig.html_results_path ?? null);
+
+// A7: post-run hook — shell command run after json_results written
+const postRun = commandsConfig.post_run ?? null;
+
 // 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, sequential, force);
+const orchestrator = new Orchestrator(
+  commandsConfig,
+  startPhase,
+  logFolder,
+  phases,
+  sequential,
+  force,
+  metrics,
+  jsonResultsPath,
+  htmlResultsPath,
+);
+// A7: wire post-run hook from config
+orchestrator.postRun = postRun;
 
 // Enhanced signal handlers
 const handleSignal = async (signal) => {
@@ -90,6 +142,8 @@ const handleSignal = async (signal) => {
   } catch (error) {
     log.error(`Cleanup failed: ${error.message}`);
   }
+  // A4: clear run-state so dashboards know the run ended
+  orchestrator._clearRunState();
   process.exit(1);
 };
 

package/lib/orchestrator.js

@@ -1,3 +1,6 @@
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
 import { processManager } from './process-manager.js';
 import { healthCheck } from './health-check.js';
 import { log } from './logger.js';
@@ -12,6 +15,9 @@ export class Orchestrator {
     phases = null,
     sequential = false,
     force = false,
+    metrics = [],
+    jsonResultsPath = null,
+    htmlResultsPath = null,
   ) {
     this.config = config;
     this.startPhase = startPhase;
@@ -19,14 +25,28 @@ export class Orchestrator {
     this.phases = phases;
     this.sequential = sequential;
     this.force = force;
+    this.metrics = Array.isArray(metrics) ? metrics : [];
+    this.jsonResultsPath = jsonResultsPath ?? null;
+    this.htmlResultsPath = htmlResultsPath ?? null;
     this.processManager = processManager;
     this.healthCheck = healthCheck;
     this.logger = log;
     this.failedCommands = [];
     this.skippedCommands = [];
     this.skipReasons = new Map(); // Track why commands were skipped
-    this.commandTimings = new Map();
+    this.commandTimings = new Map(); // command -> { durationMs, memoryKb? }
+    this.phaseResults = []; // { name, success, durationMs } per phase run
     this.gitCache = new GitCache(logFolder);
+    // A1: track per-command start times for incremental JSON
+    this.commandStartTimes = new Map(); // command -> ISO start string
+    // A2: events file path derived from jsonResultsPath
+    this.eventsPath = this._deriveEventsPath(jsonResultsPath);
+    // A4: library-owned run-state file
+    this.runStatePath = logFolder
+      ? path.join(path.resolve(logFolder), '.scripts-orchestrator-run.json')
+      : null;
+    // A7: post-run hook command (shell string)
+    this.postRun = null; // set from config in index.js
 
     // Set the log folder in process manager
     if (logFolder) {
@@ -50,6 +70,118 @@ export class Orchestrator {
     return [];
   }
 
+  _deriveEventsPath(jsonResultsPath) {
+    if (!jsonResultsPath || jsonResultsPath === '-') return null;
+    return jsonResultsPath.replace(/\.json$/, '') + '-events.ndjson';
+  }
+
+  // A4: write current run state atomically
+  _writeRunState(extra = {}) {
+    if (!this.runStatePath) return;
+    const state = {
+      startedAt: this.runStartedAt ? new Date(this.runStartedAt).toISOString() : new Date().toISOString(),
+      pid: process.pid,
+      ...extra,
+    };
+    const tmp = this.runStatePath + '.tmp';
+    try {
+      fs.mkdirSync(path.dirname(this.runStatePath), { recursive: true });
+      fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', 'utf8');
+      fs.renameSync(tmp, this.runStatePath);
+    } catch { /* non-fatal */ }
+  }
+
+  // A4: remove run-state file on run end
+  _clearRunState() {
+    if (!this.runStatePath) return;
+    try { fs.unlinkSync(this.runStatePath); } catch { /* ignore */ }
+  }
+
+  // A2: append a structured NDJSON event
+  _appendEvent(type, data = {}) {
+    if (!this.eventsPath) return;
+    const line = JSON.stringify({ type, timestamp: new Date().toISOString(), ...data });
+    try {
+      fs.appendFileSync(this.eventsPath, line + '\n', 'utf8');
+    } catch {
+      // non-fatal: don't let event logging break the run
+    }
+  }
+
+  // A1: atomically write current run state (completed + in-flight commands) to json_results
+  _writePartialResults() {
+    if (this.jsonResultsPath == null || this.jsonResultsPath === '-') return;
+    const outPath = this.jsonResultsPath || './scripts-orchestrator-results.json';
+
+    const commands = [];
+
+    const buildEntry = (command, phaseName) => {
+      const timing = this.commandTimings.get(command);
+      const startedAt = this.commandStartTimes.get(command);
+      const skipped = this.skippedCommands.includes(command);
+      const done = timing != null || skipped;
+
+      if (!done && startedAt) {
+        return { command, ...(phaseName ? { phase: phaseName } : {}), success: null, startedAt };
+      }
+      if (!done) return null; // not yet started — omit
+
+      const skipReason = skipped ? (this.skipReasons.get(command) ?? null) : null;
+      const success =
+        !this.failedCommands.includes(command) &&
+        (skipReason === null ||
+          skipReason === 'disabled' ||
+          skipReason === 'optional_phase_not_requested' ||
+          skipReason === 'before_start_phase');
+      return {
+        command,
+        ...(phaseName ? { phase: phaseName } : {}),
+        success,
+        ...(timing?.durationMs != null && this.metrics.includes('time') ? { durationMs: timing.durationMs } : {}),
+        ...(this.metrics.includes('memory') ? { memoryKb: timing?.memoryKb ?? null } : {}),
+        ...(skipReason ? { skipReason } : {}),
+      };
+    };
+
+    if (Array.isArray(this.config)) {
+      for (const { command } of this.config) {
+        const entry = buildEntry(command, null);
+        if (entry) commands.push(entry);
+      }
+    } else if (this.config.phases) {
+      for (const phase of this.config.phases) {
+        for (const { command } of (phase.parallel || [])) {
+          const entry = buildEntry(command, phase.name);
+          if (entry) commands.push(entry);
+        }
+      }
+    }
+
+    const payload = {
+      success: null, // in-progress sentinel; replaced by writeJsonResults on completion
+      timestamp: new Date().toISOString(),
+      commands,
+      ...(this.config.phases && this.phaseResults.length > 0 ? { phases: this.phaseResults } : {}),
+    };
+
+    const tmpPath = outPath + '.tmp';
+    try {
+      fs.mkdirSync(path.dirname(path.resolve(outPath)), { recursive: true });
+      fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), 'utf8');
+      fs.renameSync(tmpPath, outPath);
+    } catch (err) {
+      this.logger.verbose(`Partial results write failed: ${err.message}`);
+    }
+
+    // A4: keep run-state file in sync with current active commands and phase
+    const inFlight = commands.filter(c => c.success === null).map(c => c.command);
+    const currentPhase = commands.length > 0 ? (commands[commands.length - 1].phase ?? null) : null;
+    this._writeRunState({
+      activeCommand: inFlight.length === 1 ? inFlight[0] : (inFlight.length > 1 ? inFlight : null),
+      phase: currentPhase,
+    });
+  }
+
   formatDuration(ms) {
     if (ms < 1000) return `${ms}ms`;
     const seconds = Math.floor(ms / 1000);
@@ -61,7 +193,7 @@ export class Orchestrator {
     return `${seconds}s`;
   }
 
-  async executeCommand(commandConfig, visited = new Set()) {
+  async executeCommand(commandConfig, visited = new Set(), phaseName = null) {
     const {
       command,
       dependencies = [],
@@ -80,13 +212,17 @@ export class Orchestrator {
 
     const startTime = Date.now();
 
+    const setTiming = (durationMs, memoryKb = null) => {
+      this.commandTimings.set(command, { durationMs, memoryKb });
+    };
+
     // Check for circular dependencies
     if (visited.has(command)) {
       this.logger.error(
         `Circular dependency detected: ${Array.from(visited).join(' -> ')} -> ${command}`,
       );
       this.failedCommands.push(command);
-      this.commandTimings.set(command, Date.now() - startTime);
+      setTiming(Date.now() - startTime);
       return false;
     }
     visited.add(command);
@@ -96,7 +232,7 @@ export class Orchestrator {
       this.logger.warn(`Skipping: npm run ${command} (status: disabled)`);
       this.skippedCommands.push(command);
       this.skipReasons.set(command, 'disabled');
-      this.commandTimings.set(command, Date.now() - startTime);
+      setTiming(Date.now() - startTime);
       visited.delete(command);
       return true;
     }
@@ -127,7 +263,7 @@ export class Orchestrator {
           process_tracking,
           kill_command,
         });
-        this.commandTimings.set(command, Date.now() - startTime);
+        setTiming(Date.now() - startTime);
         visited.delete(command);
         return true;
       }
@@ -140,7 +276,7 @@ export class Orchestrator {
         this.logger.error(`Skipping ${command} due to failed dependency`);
         this.skippedCommands.push(command);
         this.skipReasons.set(command, 'failed_dependency');
-        this.commandTimings.set(command, Date.now() - startTime);
+        setTiming(Date.now() - startTime);
         visited.delete(command);
         return false;
       }
@@ -154,7 +290,7 @@ export class Orchestrator {
         if (!urlAvailable) {
           this.skippedCommands.push(command);
           this.skipReasons.set(command, 'failed_dependency');
-          this.commandTimings.set(command, Date.now() - startTime);
+          setTiming(Date.now() - startTime);
           visited.delete(command);
           return false;
         }
@@ -172,10 +308,16 @@ export class Orchestrator {
       }
     }
 
+    // A1/A2: record start and emit event
+    this.commandStartTimes.set(command, new Date().toISOString());
+    this._appendEvent('command_start', { command, phase: phaseName, scope: 'workspace' });
+    this._writePartialResults();
+
     // Execute the main command with retries
     let result = false;
     let commandOutput = '';
     let commandFailed = false;
+    let lastRunResult = null;
 
     for (let attempt = 1; attempt <= attempts; attempt++) {
       if (attempt > 1) {
@@ -185,7 +327,7 @@ export class Orchestrator {
         await new Promise((resolve) => setTimeout(resolve, 1000));
       }
 
-      const { success, output } = await this.processManager.runCommand({
+      const runResult = await this.processManager.runCommand({
         cmd: attempt === 1 ? command : retry_command || command,
         logFile: log || logFile, // Prefer 'log' key over 'logFile' for backwards compatibility
         background,
@@ -193,7 +335,11 @@ export class Orchestrator {
         kill_command,
         isRetry: attempt > 1,
         env,
+        reportTime: this.metrics.includes('time'),
+        reportMemory: this.metrics.includes('memory'),
       });
+      lastRunResult = runResult;
+      const { success, output } = runResult;
       commandOutput = output;
       result = success;
 
@@ -239,7 +385,11 @@ export class Orchestrator {
       }
     }
 
-    this.commandTimings.set(command, Date.now() - startTime);
+    const totalDurationMs = Date.now() - startTime;
+    setTiming(totalDurationMs, lastRunResult?.memoryKb ?? null);
+    // A1/A2: emit completion event and write incremental results
+    this._appendEvent('command_end', { command, phase: phaseName, success: result, durationMs: totalDurationMs });
+    this._writePartialResults();
     visited.delete(command);
     return result;
   }
@@ -269,8 +419,222 @@ export class Orchestrator {
     }
   }
 
+  writeJsonResults(hasFailures) {
+    const overallDurationMs =
+      this.metrics.includes('time') && this.startTime
+        ? Date.now() - this.startTime
+        : undefined;
+
+    const commands = [];
+    if (Array.isArray(this.config)) {
+      this.config.forEach(({ command }) => {
+        const timing = this.commandTimings.get(command);
+        const skipReason = this.skippedCommands.includes(command)
+          ? this.skipReasons.get(command) ?? null
+          : null;
+        const success =
+          !this.failedCommands.includes(command) &&
+          (skipReason === null ||
+            skipReason === 'disabled' ||
+            skipReason === 'optional_phase_not_requested' ||
+            skipReason === 'before_start_phase');
+        const entry = {
+          command,
+          success,
+          ...(timing?.durationMs != null && this.metrics.includes('time')
+            ? { durationMs: timing.durationMs }
+            : {}),
+          ...(this.metrics.includes('memory')
+            ? { memoryKb: timing?.memoryKb ?? null }
+            : {}),
+          ...(skipReason ? { skipReason } : {}),
+        };
+        commands.push(entry);
+      });
+    } else if (this.config.phases) {
+      this.config.phases.forEach((phase) => {
+        (phase.parallel || []).forEach(({ command }) => {
+          const timing = this.commandTimings.get(command);
+          const skipReason = this.skippedCommands.includes(command)
+            ? this.skipReasons.get(command) ?? null
+            : null;
+          const success =
+            !this.failedCommands.includes(command) &&
+            (skipReason === null ||
+              skipReason === 'disabled' ||
+              skipReason === 'optional_phase_not_requested' ||
+              skipReason === 'before_start_phase');
+          const entry = {
+            command,
+            phase: phase.name,
+            success,
+            ...(timing?.durationMs != null && this.metrics.includes('time')
+              ? { durationMs: timing.durationMs }
+              : {}),
+            ...(this.metrics.includes('memory')
+              ? { memoryKb: timing?.memoryKb ?? null }
+              : {}),
+            ...(skipReason ? { skipReason } : {}),
+          };
+          commands.push(entry);
+        });
+      });
+    }
+
+    const payload = {
+      success: !hasFailures,
+      timestamp: new Date().toISOString(),
+      ...(overallDurationMs != null ? { overallDurationMs } : {}),
+      commands,
+      ...(this.config.phases && this.phaseResults.length > 0
+        ? { phases: this.phaseResults }
+        : {}),
+    };
+
+    const json = JSON.stringify(payload, null, 2);
+    if (this.jsonResultsPath === '-') {
+      console.log(json);
+    } else {
+      const outPath = this.jsonResultsPath || './scripts-orchestrator-results.json';
+      fs.writeFileSync(outPath, json, 'utf8');
+      this.logger.verbose(`Wrote results to ${outPath}`);
+    }
+
+    if (this.htmlResultsPath != null) {
+      this.writeHtmlResults(payload);
+    }
+  }
+
+  formatMs(ms) {
+    if (ms == null || ms === 0) return '—';
+    if (ms < 1000) return `${ms}ms`;
+    const s = (ms / 1000).toFixed(1);
+    return `${s}s`;
+  }
+
+  writeHtmlResults(payload) {
+    const escapeHtml = (s) => {
+      if (s == null) return '';
+      return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+    };
+    const { success, timestamp, overallDurationMs, commands = [], phases = [] } = payload;
+    const maxDuration = Math.max(0, ...commands.map((c) => c.durationMs || 0), ...phases.map((p) => p.durationMs || 0));
+    const maxMemory = Math.max(0, ...commands.map((c) => c.memoryKb || 0));
+
+    const row = (c) => {
+      const durationPct = maxDuration > 0 && c.durationMs != null ? (c.durationMs / maxDuration) * 100 : 0;
+      const memoryPct = maxMemory > 0 && c.memoryKb != null ? (c.memoryKb / maxMemory) * 100 : 0;
+      const statusClass = c.success ? 'ok' : 'fail';
+      const statusLabel = c.success ? 'OK' : (c.skipReason || 'Failed');
+      return `
+        <tr class="${statusClass}">
+          <td><code>${escapeHtml(c.command)}</code></td>
+          <td>${c.phase != null ? escapeHtml(c.phase) : '—'}</td>
+          <td><span class="badge ${statusClass}">${escapeHtml(statusLabel)}</span></td>
+          <td>${this.formatMs(c.durationMs)}</td>
+          <td>${c.memoryKb != null ? `${(c.memoryKb / 1024).toFixed(1)} MB` : '—'}</td>
+          <td class="bar-cell"><div class="bar" style="width:${durationPct}%"></div></td>
+          <td class="bar-cell"><div class="bar mem" style="width:${memoryPct}%"></div></td>
+        </tr>`;
+    };
+
+    const phaseRow = (p) => {
+      const durationPct = maxDuration > 0 && p.durationMs != null ? (p.durationMs / maxDuration) * 100 : 0;
+      const statusClass = p.success ? 'ok' : 'fail';
+      return `
+        <tr class="${statusClass}">
+          <td>${escapeHtml(p.name)}</td>
+          <td><span class="badge ${statusClass}">${p.success ? 'OK' : 'Failed'}</span></td>
+          <td>${this.formatMs(p.durationMs)}</td>
+          <td class="bar-cell"><div class="bar" style="width:${durationPct}%"></div></td>
+        </tr>`;
+    };
+
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Scripts Orchestrator Report</title>
+  <style>
+    * { box-sizing: border-box; }
+    body { font-family: system-ui, sans-serif; margin: 1rem 2rem; background: #1a1a1a; color: #e0e0e0; }
+    h1 { font-size: 1.5rem; margin-bottom: 0.5rem; }
+    .summary { display: flex; gap: 1.5rem; flex-wrap: wrap; margin-bottom: 1.5rem; }
+    .summary .card { background: #2a2a2a; padding: 1rem 1.25rem; border-radius: 8px; min-width: 140px; }
+    .summary .card.success { border-left: 4px solid #22c55e; }
+    .summary .card.fail { border-left: 4px solid #ef4444; }
+    .summary .label { font-size: 0.75rem; text-transform: uppercase; color: #888; }
+    .summary .value { font-size: 1.25rem; font-weight: 600; }
+    section { margin-bottom: 1.5rem; }
+    section h2 { font-size: 1.1rem; color: #a0a0a0; margin-bottom: 0.5rem; }
+    table { width: 100%; border-collapse: collapse; background: #2a2a2a; border-radius: 8px; overflow: hidden; }
+    th, td { padding: 0.5rem 0.75rem; text-align: left; }
+    th { background: #333; color: #888; font-weight: 600; font-size: 0.8rem; }
+    tr.fail { background: rgba(239,68,68,0.08); }
+    .badge { padding: 0.2rem 0.5rem; border-radius: 4px; font-size: 0.8rem; }
+    .badge.ok { background: #22c55e; color: #0f0f0f; }
+    .badge.fail { background: #ef4444; color: #fff; }
+    .bar-cell { width: 120px; }
+    .bar { height: 8px; background: #3b82f6; border-radius: 4px; min-width: 2px; }
+    .bar.mem { background: #8b5cf6; }
+    code { font-size: 0.9em; background: #333; padding: 0.1rem 0.3rem; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <h1>Scripts Orchestrator Report</h1>
+  <div class="summary">
+    <div class="card ${success ? 'success' : 'fail'}">
+      <div class="label">Status</div>
+      <div class="value">${success ? 'Success' : 'Failed'}</div>
+    </div>
+    <div class="card">
+      <div class="label">Timestamp</div>
+      <div class="value" style="font-size:0.9rem">${escapeHtml(timestamp)}</div>
+    </div>
+    ${overallDurationMs != null ? `
+    <div class="card">
+      <div class="label">Total time</div>
+      <div class="value">${this.formatMs(overallDurationMs)}</div>
+    </div>` : ''}
+  </div>
+
+  ${phases.length > 0 ? `
+  <section>
+    <h2>Phases</h2>
+    <table>
+      <thead><tr><th>Phase</th><th>Status</th><th>Duration</th><th></th></tr></thead>
+      <tbody>${phases.map(phaseRow).join('')}</tbody>
+    </table>
+  </section>` : ''}
+
+  <section>
+    <h2>Commands</h2>
+    <table>
+      <thead><tr><th>Command</th><th>Phase</th><th>Status</th><th>Duration</th><th>Memory</th><th>Time</th><th>Memory</th></tr></thead>
+      <tbody>${commands.map(row).join('')}</tbody>
+    </table>
+  </section>
+</body>
+</html>`;
+
+    if (this.htmlResultsPath === '-') {
+      console.log(html);
+    } else {
+      const outPath = this.htmlResultsPath || './scripts-orchestrator-results.html';
+      fs.writeFileSync(outPath, html, 'utf8');
+      this.logger.verbose(`Wrote HTML report to ${outPath}`);
+    }
+  }
+
   async run() {
     this.startTime = Date.now();
+    this.runStartedAt = this.startTime;
+    // A4: write initial run-state at start
+    this._writeRunState({ phase: null, activeCommand: null });
     try {
       // Check if we should skip execution based on git state (unless forced)
       if (!this.force) {
@@ -328,7 +692,7 @@ export class Orchestrator {
               phase.parallel.forEach(({ command }) => {
                 this.skippedCommands.push(command);
                 this.skipReasons.set(command, 'before_start_phase');
-                this.commandTimings.set(command, 0);
+                this.commandTimings.set(command, { durationMs: 0, memoryKb: null });
               });
               continue;
             }
@@ -347,7 +711,7 @@ export class Orchestrator {
             phase.parallel.forEach(({ command }) => {
               this.skippedCommands.push(command);
               this.skipReasons.set(command, 'optional_phase_not_requested');
-              this.commandTimings.set(command, 0);
+              this.commandTimings.set(command, { durationMs: 0, memoryKb: null });
             });
             continue;
           }
@@ -357,7 +721,7 @@ export class Orchestrator {
             phase.parallel.forEach(({ command }) => {
               this.skippedCommands.push(command);
               this.skipReasons.set(command, 'after_phase_failure');
-              this.commandTimings.set(command, 0);
+              this.commandTimings.set(command, { durationMs: 0, memoryKb: null });
             });
             continue;
           }
@@ -369,7 +733,7 @@ export class Orchestrator {
             // Run commands sequentially
             results = [];
             for (const commandConfig of phase.parallel) {
-              const result = await this.executeCommand(commandConfig);
+              const result = await this.executeCommand(commandConfig, new Set(), phase.name);
               results.push(result);
               if (!result) {
                 // In sequential mode, stop phase execution on first failure
@@ -379,15 +743,22 @@ export class Orchestrator {
           } else {
             // Run commands in parallel
             const tasks = phase.parallel.map((commandConfig) =>
-              this.executeCommand(commandConfig),
+              this.executeCommand(commandConfig, new Set(), phase.name),
             );
             results = await Promise.all(tasks);
           }
 
           const phaseHasFailures = results.some((result) => !result);
-          const phaseDurationStr = `(${this.formatDuration(
-            Date.now() - phaseStartTime,
-          )})`;
+          const phaseDurationMs = Date.now() - phaseStartTime;
+          const phaseDurationStr = this.metrics.includes('time')
+            ? `(${this.formatDuration(phaseDurationMs)})`
+            : '';
+
+          this.phaseResults.push({
+            name: phase.name,
+            success: !phaseHasFailures,
+            durationMs: this.metrics.includes('time') ? phaseDurationMs : undefined,
+          });
 
           if (phaseHasFailures) {
             hasFailures = true;
@@ -450,8 +821,8 @@ export class Orchestrator {
         this.logger.error(`Cleanup failed: ${error.message}`);
       }
 
-      // Log overall time after cleanup has finished
-      if (this.startTime) {
+      // Log overall time after cleanup has finished (only when metrics include time)
+      if (this.startTime && this.metrics.includes('time')) {
         const overallDuration = Date.now() - this.startTime;
         this.logger.printMessage(() =>
           console.log(
@@ -462,6 +833,21 @@ export class Orchestrator {
         );
       }
 
+      // A2: emit run_end event; A1: final JSON written by writeJsonResults (replaces partial)
+      const runDurationMs = this.startTime ? Date.now() - this.startTime : undefined;
+      this._appendEvent('run_end', { success: !hasFailures, ...(runDurationMs != null ? { durationMs: runDurationMs } : {}) });
+
+      // Write JSON results if requested
+      if (this.jsonResultsPath != null) {
+        this.writeJsonResults(hasFailures);
+      }
+
+      // A4: clear run-state file — run is done
+      this._clearRunState();
+
+      // A7: run post_run hook after results are written
+      this._runPostRunHook(hasFailures);
+
       // Update git cache on successful execution
       if (!hasFailures) {
         await this.gitCache.updateCache();
@@ -478,6 +864,9 @@ export class Orchestrator {
     } catch (error) {
       this.logger.error(`Orchestrator failed: ${error.message}`);
 
+      // A4: clear run-state on error too
+      this._clearRunState();
+
       // Cleanup on error
       try {
         await this.processManager.cleanup();
@@ -488,4 +877,23 @@ export class Orchestrator {
       process.exit(1);
     }
   }
+
+  // A7: run user-configured post_run shell command
+  _runPostRunHook(hasFailures) {
+    if (!this.postRun) return;
+    this.logger.info(`[post_run] ${this.postRun}`);
+    const result = spawnSync(this.postRun, {
+      shell: true,
+      stdio: 'inherit',
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        SCRIPTS_ORCHESTRATOR_SUCCESS: hasFailures ? '0' : '1',
+        SCRIPTS_ORCHESTRATOR_EXIT_CODE: hasFailures ? '1' : '0',
+      },
+    });
+    if (result.status !== 0) {
+      this.logger.warn(`[post_run] hook exited with code ${result.status}`);
+    }
+  }
 }

package/lib/process-manager.js

@@ -55,6 +55,32 @@ export class ProcessManager {
     });
   }
 
+  parseGnuTimeOutput(filePath) {
+    try {
+      if (!fs.existsSync(filePath)) return null;
+      const text = fs.readFileSync(filePath, 'utf8');
+      const m = text.match(/Maximum resident set size \(kbytes\):\s*(\d+)/i);
+      const kbytes = m ? parseInt(m[1], 10) : null;
+      try {
+        fs.unlinkSync(filePath);
+      } catch {
+        // ignore
+      }
+      return Number.isFinite(kbytes) ? kbytes : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Parse macOS BSD time -l output (bytes) from text; returns memory in KB or null. */
+  parseBsdTimeOutput(text) {
+    if (!text || typeof text !== 'string') return null;
+    const m = text.match(/(\d+)\s+maximum resident set size/i);
+    if (!m) return null;
+    const bytes = parseInt(m[1], 10);
+    return Number.isFinite(bytes) ? Math.round(bytes / 1024) : null;
+  }
+
   async runCommand({
     cmd,
     logFile,
@@ -63,6 +89,8 @@ export class ProcessManager {
     kill_command = null,
     isRetry = false,
     env = null,
+    reportTime = false,
+    reportMemory = false,
   }) {
     const baseDir = this.logFolder
       ? path.resolve(this.logFolder)
@@ -88,11 +116,17 @@ export class ProcessManager {
       }
     } catch (error) {
       this.logger.error(`Failed to setup log file: ${error.message}`);
-      return Promise.resolve({ success: false, output: '' });
+      return Promise.resolve({
+        success: false,
+        output: '',
+        durationMs: 0,
+        memoryKb: null,
+      });
     }
 
     return new Promise((resolve) => {
       const startTime = Date.now();
+      let timeOutputPath = null;
       // Build command with environment variables if provided
       let fullCommand = `npm run ${cmd}`;
       if (env && Object.keys(env).length > 0) {
@@ -101,6 +135,14 @@ export class ProcessManager {
           .join(' ');
         fullCommand = `${envStr} npm run ${cmd}`;
       }
+      const useTimeWrapper =
+        reportMemory && !background && (process.platform === 'linux' || process.platform === 'darwin');
+      if (useTimeWrapper && process.platform === 'linux') {
+        timeOutputPath = path.join(LOGS_DIR, `.time-${logName}-${startTime}.txt`);
+        fullCommand = `/usr/bin/time -v -o ${JSON.stringify(timeOutputPath)} sh -c ${JSON.stringify(fullCommand)}`;
+      } else if (useTimeWrapper && process.platform === 'darwin') {
+        fullCommand = `/usr/bin/time -l sh -c ${JSON.stringify(fullCommand)}`;
+      }
 
       this.logger.startTask(cmd, fullCommand);
 
@@ -126,8 +168,12 @@ export class ProcessManager {
         processInstance.on('error', (error) => {
           this.logger.stopTask(cmd);
           this.logger.error(`Failed to start process: ${error.message}`);
-          //this.logger.verbose(`Process error details: ${JSON.stringify(error, null, 2)}`);
-          resolve({ success: false, output: '' });
+          resolve({
+            success: false,
+            output: '',
+            durationMs: Date.now() - startTime,
+            memoryKb: null,
+          });
         });
 
         if (background) {
@@ -189,7 +235,12 @@ export class ProcessManager {
                       `Failed to read log file: ${error.message}`,
                     );
                   }
-                  return { success: false, output };
+                  return {
+                    success: false,
+                    output,
+                    durationMs: Date.now() - startTime,
+                    memoryKb: null,
+                  };
                 }
 
                 this.logger.verbose(
@@ -216,7 +267,12 @@ export class ProcessManager {
                       `Failed to read log file: ${error.message}`,
                     );
                   }
-                  return { success: false, output };
+                  return {
+                    success: false,
+                    output,
+                    durationMs: Date.now() - startTime,
+                    memoryKb: null,
+                  };
                 }
 
                 this.backgroundProcesses.push(processGroupId);
@@ -236,7 +292,12 @@ export class ProcessManager {
                 this.logger.verbose(
                   `Background process started: npm run ${cmd} (PGID: ${processGroupId})`,
                 );
-                return { success: true, output: '' };
+                return {
+                  success: true,
+                  output: '',
+                  durationMs: Date.now() - startTime,
+                  memoryKb: null,
+                };
               } catch (error) {
                 if (attempt === maxAttempts) {
                   this.logger.error(
@@ -245,7 +306,12 @@ export class ProcessManager {
                   this.logger.verbose(
                     `Final verification attempt failed: ${error.message}`,
                   );
-                  return { success: false, output: '' };
+                  return {
+                    success: false,
+                    output: '',
+                    durationMs: Date.now() - startTime,
+                    memoryKb: null,
+                  };
                 }
                 this.logger.verbose(
                   `Verification attempt ${attempt} failed: ${error.message}`,
@@ -258,7 +324,12 @@ export class ProcessManager {
                 );
               }
             }
-            return { success: false, output: '' };
+            return {
+              success: false,
+              output: '',
+              durationMs: Date.now() - startTime,
+              memoryKb: null,
+            };
           };
 
           verifyProcess().then(resolve);
@@ -293,26 +364,50 @@ export class ProcessManager {
 
             this.logger.stopTask(cmd);
 
-            const duration = Date.now() - startTime;
-            const durationStr = ` (${this.formatDuration(duration)})`;
+            const durationMs = Date.now() - startTime;
+            const durationStr = reportTime
+              ? ` (${this.formatDuration(durationMs)})`
+              : '';
+            let memoryKb = null;
+            if (reportMemory) {
+              if (timeOutputPath) {
+                memoryKb = this.parseGnuTimeOutput(timeOutputPath);
+              } else if (process.platform === 'darwin') {
+                memoryKb = this.parseBsdTimeOutput(output);
+              }
+            }
 
             if (code !== 0) {
               this.logger.error(
                 `Failed: npm run ${cmd} ❌${durationStr} (exit code: ${code})`,
               );
               this.logger.verbose(`Process output: ${output}`);
-              resolve({ success: false, output });
+              resolve({
+                success: false,
+                output,
+                durationMs,
+                memoryKb,
+              });
             } else {
               this.logger.success(`Completed: npm run ${cmd} ✅${durationStr}`);
-              resolve({ success: true, output });
+              resolve({
+                success: true,
+                output,
+                durationMs,
+                memoryKb,
+              });
             }
           });
         }
       } catch (error) {
         this.logger.stopTask(cmd);
         this.logger.error(`Failed to spawn process: ${error.message}`);
-        //this.logger.verbose(`Spawn error details: ${JSON.stringify(error, null, 2)}`);
-        resolve({ success: false, output: '' });
+        resolve({
+          success: false,
+          output: '',
+          durationMs: Date.now() - startTime,
+          memoryKb: null,
+        });
       }
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scripts-orchestrator",
-  "version": "2.12.0",
+  "version": "2.14.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

@@ -1,4 +1,10 @@
 export default {
+  // Optional: metrics to report (time, memory). CLI --metrics overrides.
+  // metrics: ['time'],
+  // Optional: path for JSON results, or '-' for stdout. CLI --json-results overrides.
+  // json_results: './scripts-orchestrator-results.json',
+  // Optional: path for HTML report. CLI --html-results overrides.
+  // html_results: './scripts-orchestrator-results.html',
   phases: [
     {
       name: 'build',