scripts-orchestrator 2.15.1 → 3.5.0

package/lib/workspaces.js

@@ -0,0 +1,353 @@
+/**
+ * @file workspaces.js
+ * @description First-class npm-workspace support: discover the workspaces declared in a
+ * repo's root package.json, then aggregate each workspace's orchestrator results JSON
+ * (plus the root run's global-check results) into a single, generic report document that
+ * the shared HTML renderer can turn into one roll-up page.
+ *
+ * The aggregator is intentionally domain-agnostic: it reads only artifacts the library
+ * itself writes (per-scope results JSON + the run-state file), so it needs no log scraping
+ * and no knowledge of any particular task runner. All path conventions are configurable.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { renderReportHtml } from './report-html.js';
+
+const DEFAULTS = {
+  title: 'Workspaces Quality Report',
+  outJson: 'logs/monorepo-quality-report.json',
+  outHtml: 'logs/monorepo-quality-report.html',
+  runStateFile: 'logs/.scripts-orchestrator-run.json',
+  rootResults: 'logs/scripts-orchestrator-logs/scripts-orchestrator-results.json',
+  globalResults: 'logs/scripts-orchestrator-logs/scripts-orchestrator-global-results.json',
+  workspaceResults: 'logs/scripts-orchestrator-logs/scripts-orchestrator-results.json',
+  globalPhase: 'global quality checks',
+  workspacePhase: 'workspace quality gates',
+  refreshSecs: 5,
+  exclude: [],
+};
+
+function readJson(absPath) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function statMtimeMs(absPath) {
+  try {
+    return fs.statSync(absPath).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function toMs(iso) {
+  if (!iso) return null;
+  const ms = Date.parse(iso);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+/**
+ * Walk up from `startDir` (inclusive) to the nearest ancestor whose package.json declares a
+ * non-empty `workspaces` array. Returns that directory, or null if none is found.
+ *
+ * @param {string} startDir
+ * @returns {string | null}
+ */
+export function findRepoRoot(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    const pkg = readJson(path.join(dir, 'package.json'));
+    const ws = pkg?.workspaces;
+    const patterns = Array.isArray(ws) ? ws : Array.isArray(ws?.packages) ? ws.packages : null;
+    if (patterns && patterns.length > 0) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function workspacePatternsOf(pkg) {
+  const ws = pkg?.workspaces;
+  if (Array.isArray(ws)) return ws;
+  if (Array.isArray(ws?.packages)) return ws.packages;
+  return [];
+}
+
+/**
+ * Resolve the directories of the npm workspaces declared in `repoRoot`'s package.json.
+ *
+ * Supports the two common glob shapes (`dir/*` and an exact `dir/name`). A trailing `/*`
+ * expands to the immediate child directories that contain a package.json. Dot-prefixed
+ * directories (e.g. `.template`) are skipped to match npm's own glob behaviour.
+ *
+ * @param {string} repoRoot
+ * @returns {string[]} absolute workspace directories
+ */
+export function discoverWorkspaceDirs(repoRoot) {
+  const pkg = readJson(path.join(repoRoot, 'package.json'));
+  const patterns = workspacePatternsOf(pkg);
+  const dirs = [];
+  const seen = new Set();
+  const add = (absDir) => {
+    if (seen.has(absDir)) return;
+    if (!fs.existsSync(path.join(absDir, 'package.json'))) return;
+    seen.add(absDir);
+    dirs.push(absDir);
+  };
+
+  for (const pattern of patterns) {
+    const normalized = pattern.replace(/\/+$/, '');
+    if (normalized.endsWith('/*')) {
+      const baseDir = path.join(repoRoot, normalized.slice(0, -2));
+      let entries;
+      try {
+        entries = fs.readdirSync(baseDir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name.startsWith('.')) continue; // npm's `*` does not match dotfiles
+        add(path.join(baseDir, entry.name));
+      }
+    } else {
+      add(path.join(repoRoot, normalized));
+    }
+  }
+  return dirs.sort();
+}
+
+function isNoOpGate(pkgJson) {
+  const script = pkgJson?.scripts?.['scripts-orchestrator'];
+  if (script == null) return true; // workspace does not participate in the gate
+  return /echo\s+["']not applicable["']/i.test(script);
+}
+
+/** A results file from a previous run window (older than this run started). */
+function isStale(jsonAbs, payload, runStartedAt) {
+  if (runStartedAt == null) return false;
+  if (payload?.timestamp != null) {
+    const ts = Date.parse(payload.timestamp);
+    if (!Number.isNaN(ts) && ts < runStartedAt - 2000) return true;
+  }
+  const mtime = statMtimeMs(jsonAbs);
+  if (mtime != null && mtime < runStartedAt) return true;
+  return false;
+}
+
+/** Re-root a workspace command's logFile (relative to the workspace) onto the repo root. */
+function commandsWithRepoRelLogs(commands, relDir) {
+  return (commands || []).map((c) => {
+    if (!c.logFile) return { ...c };
+    return { ...c, logFile: toPosix(path.join(relDir, c.logFile)) };
+  });
+}
+
+function classifyWorkspace({ noOp, exists, stale, success, inProgress, fanoutOk }) {
+  if (noOp) return { statusKind: 'muted', statusLabel: 'N/A', state: 'noOp' };
+  if (!exists) {
+    return inProgress
+      ? { statusKind: 'muted', statusLabel: 'PENDING', state: 'pending' }
+      : { statusKind: 'muted', statusLabel: '—', state: 'absent' };
+  }
+  if (stale) {
+    if (inProgress) return { statusKind: 'muted', statusLabel: 'PENDING', state: 'pending' };
+    // The workspace's own results predate this run, but the root run's workspace fan-out phase
+    // still succeeded — so the gate passed this run from a task-runner cache replay (it was not
+    // re-executed, so no fresh JSON was written). Surface its last-known (cached) results rather
+    // than a misleading "no data" STALE. Only a clean fan-out earns this; a failed/partial fan-out
+    // leaves genuinely-unrun workspaces as STALE.
+    if (fanoutOk === true) {
+      return { statusKind: 'warn', statusLabel: 'CACHED', state: 'cached' };
+    }
+    return { statusKind: 'warn', statusLabel: 'STALE', state: 'stale' };
+  }
+  if (success === null || success === undefined) {
+    return inProgress
+      ? { statusKind: 'running', statusLabel: 'RUNNING', state: 'running' }
+      : { statusKind: 'fail', statusLabel: 'INTERRUPTED', state: 'interrupted' };
+  }
+  if (success === false) return { statusKind: 'fail', statusLabel: 'FAIL', state: 'fail' };
+  return { statusKind: 'ok', statusLabel: 'OK', state: 'ok' };
+}
+
+function resolveOptions(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot || findRepoRoot() || process.cwd());
+  const merged = { ...DEFAULTS, ...options, repoRoot };
+  const abs = (p) => (path.isAbsolute(p) ? p : path.join(repoRoot, p));
+  return {
+    ...merged,
+    runStateAbs: abs(merged.runStateFile),
+    rootResultsAbs: abs(merged.rootResults),
+    globalResultsAbs: abs(merged.globalResults),
+    outJsonAbs: abs(merged.outJson),
+    outHtmlAbs: abs(merged.outHtml),
+  };
+}
+
+function collectGlobalCommands(opts, runStartedAt) {
+  const root = readJson(opts.rootResultsAbs);
+  if (root?.commands && !isStale(opts.rootResultsAbs, root, runStartedAt)) {
+    const fromRoot = root.commands.filter((c) => c.phase === opts.globalPhase);
+    if (fromRoot.length > 0) return fromRoot;
+  }
+  const global = readJson(opts.globalResultsAbs);
+  if (global?.commands && !isStale(opts.globalResultsAbs, global, runStartedAt)) {
+    return global.commands.map((c) => ({ ...c, phase: c.phase ?? opts.globalPhase }));
+  }
+  return [];
+}
+
+/**
+ * Build the generic report document aggregating the root run's global checks and every
+ * workspace's own orchestrator results.
+ *
+ * @param {object} [options] see DEFAULTS for the supported keys (all paths repo-root-relative)
+ * @returns {object} a renderable report payload ({ title, success, sections, ... })
+ */
+export function aggregateWorkspacesReport(options = {}) {
+  const opts = resolveOptions(options);
+  const runState = readJson(opts.runStateAbs);
+  const rootJson = readJson(opts.rootResultsAbs);
+
+  // Prefer the run-state file's startedAt (present while the run is in flight). The end-of-run
+  // aggregate fires AFTER the orchestrator clears that file, so fall back to deriving the run
+  // start from the root results: its `timestamp` is the run's END, so subtract its duration.
+  // (Using the raw end timestamp would wrongly flag every workspace JSON — all written before
+  // the root run finished — as stale.) With no duration to anchor the window, stay lenient
+  // (null) rather than risk false "stale" verdicts on this run's results.
+  let runStartedAt = toMs(runState?.startedAt);
+  if (runStartedAt == null && rootJson?.timestamp) {
+    const endMs = toMs(rootJson.timestamp);
+    const durationMs = Number(rootJson.overallDurationMs);
+    if (endMs != null && Number.isFinite(durationMs) && durationMs > 0) {
+      runStartedAt = endMs - durationMs;
+    }
+  }
+
+  const inProgress =
+    options.inProgress != null
+      ? Boolean(options.inProgress)
+      : runState != null || rootJson?.success === null;
+
+  const excludeSet = new Set((opts.exclude || []).map((e) => toPosix(e)));
+
+  // Did this run's workspace fan-out phase pass? (Used to recognise cache-replayed workspaces,
+  // whose own results JSON predates this run because they were not re-executed.) null = no
+  // fan-out phase in the root results (e.g. a standalone workspace run) → no cache recovery.
+  const fanoutCommands = (rootJson?.commands || []).filter((c) => c.phase === opts.workspacePhase);
+  const fanoutOk = fanoutCommands.length === 0 ? null : fanoutCommands.every((c) => c.success !== false);
+
+  // Global quality checks section (commands run by the root orchestrator itself).
+  const globalCommands = collectGlobalCommands(opts, runStartedAt);
+  const globalFailed = globalCommands.filter((c) => c.success === false).length;
+  const sections = [
+    {
+      title: 'Global quality checks',
+      success: inProgress ? null : globalFailed === 0,
+      commands: globalCommands,
+    },
+  ];
+
+  // One section per discovered workspace.
+  let anyWorkspaceBad = false;
+  for (const wsDir of discoverWorkspaceDirs(opts.repoRoot)) {
+    const relDir = toPosix(path.relative(opts.repoRoot, wsDir));
+    if (excludeSet.has(relDir)) continue;
+
+    const pkg = readJson(path.join(wsDir, 'package.json'));
+    if (!pkg) continue;
+    const name = pkg.name || relDir;
+    const noOp = isNoOpGate(pkg);
+
+    const jsonAbs = path.join(wsDir, opts.workspaceResults);
+    const payload = readJson(jsonAbs);
+    const exists = payload != null;
+    const stale = exists && isStale(jsonAbs, payload, runStartedAt);
+    const success = payload?.success;
+
+    const st = classifyWorkspace({ noOp, exists, stale, success, inProgress, fanoutOk });
+    if (st.state === 'fail' || st.state === 'interrupted') anyWorkspaceBad = true;
+
+    const showCommands = st.state === 'ok' || st.state === 'fail' || st.state === 'cached';
+    const commands = showCommands ? commandsWithRepoRelLogs(payload.commands, relDir) : [];
+
+    const note =
+      commands.length === 0 && st.state === 'pending'
+        ? 'Queued — not started yet this run'
+        : commands.length === 0 && st.state === 'stale'
+          ? 'No results for this run window (stale snapshot)'
+          : null;
+
+    sections.push({
+      title: name,
+      statusKind: st.statusKind,
+      statusLabel: st.statusLabel,
+      success:
+        st.state === 'ok' || st.state === 'cached'
+          ? success ?? true
+          : st.state === 'fail'
+            ? false
+            : null,
+      overallDurationMs: showCommands ? payload.overallDurationMs : undefined,
+      meta: { path: relDir, ...(note ? { note } : {}) },
+      commands,
+    });
+  }
+
+  const rootOk = rootJson ? rootJson.success !== false : true;
+  const success = inProgress ? null : rootOk && globalFailed === 0 && !anyWorkspaceBad;
+
+  return {
+    title: opts.title,
+    success,
+    timestamp: new Date().toISOString(),
+    overallDurationMs: rootJson?.overallDurationMs,
+    inProgress,
+    sections,
+    // Carry heat thresholds into the aggregate payload so the renderer honours them.
+    ...(opts.memoryHeat ? { memoryHeat: opts.memoryHeat } : {}),
+    ...(opts.durationHeat ? { durationHeat: opts.durationHeat } : {}),
+  };
+}
+
+/** Insert a meta-refresh so an open browser tab live-reloads while the run is in flight. */
+function injectAutoRefresh(html, refreshSecs) {
+  if (html.includes('http-equiv="refresh"')) return html;
+  const meta = `  <meta http-equiv="refresh" content="${refreshSecs}">\n`;
+  return html.replace(/(<meta charset="utf-8">\n)/, `$1${meta}`);
+}
+
+function atomicWrite(absPath, content) {
+  const tmp = `${absPath}.tmp`;
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(tmp, content, 'utf8');
+  fs.renameSync(tmp, absPath);
+}
+
+/**
+ * Build the aggregate report and write both the JSON document and the rendered HTML.
+ *
+ * @param {object} [options]
+ * @returns {{ payload: object, jsonPath: string, htmlPath: string }}
+ */
+export function writeAggregateReport(options = {}) {
+  const opts = resolveOptions(options);
+  const payload = aggregateWorkspacesReport(options);
+
+  atomicWrite(opts.outJsonAbs, JSON.stringify(payload, null, 2));
+
+  let html = renderReportHtml(payload);
+  if (payload.inProgress) html = injectAutoRefresh(html, opts.refreshSecs);
+  atomicWrite(opts.outHtmlAbs, html);
+
+  return { payload, jsonPath: opts.outJsonAbs, htmlPath: opts.outHtmlAbs };
+}

package/lib/workspaces.test.js

@@ -0,0 +1,303 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import {
+  findRepoRoot,
+  discoverWorkspaceDirs,
+  aggregateWorkspacesReport,
+  writeAggregateReport,
+} from './workspaces.js';
+
+// Anchored in the past so freshly-written fixture files always have an mtime AFTER the run
+// started (the staleness check considers both the payload timestamp and the file mtime).
+const RUN_STARTED = '2020-01-01T10:00:00.000Z';
+const RUN_STARTED_MS = Date.parse(RUN_STARTED);
+const fresh = (offsetSec = 10) => new Date(RUN_STARTED_MS + offsetSec * 1000).toISOString();
+const old = (offsetSec = 60) => new Date(RUN_STARTED_MS - offsetSec * 1000).toISOString();
+
+let repoRoot;
+
+function writeJson(absPath, obj) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, JSON.stringify(obj, null, 2));
+}
+
+function makeWorkspace(relDir, { name, orchestratorScript, results } = {}) {
+  const wsDir = path.join(repoRoot, relDir);
+  writeJson(path.join(wsDir, 'package.json'), {
+    name: name ?? relDir,
+    scripts:
+      orchestratorScript === undefined
+        ? { 'scripts-orchestrator': 'run-gate' }
+        : orchestratorScript === null
+          ? {}
+          : { 'scripts-orchestrator': orchestratorScript },
+  });
+  if (results) {
+    writeJson(
+      path.join(wsDir, 'logs/scripts-orchestrator-logs/scripts-orchestrator-results.json'),
+      results,
+    );
+  }
+}
+
+beforeEach(() => {
+  repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'so-ws-'));
+  writeJson(path.join(repoRoot, 'package.json'), {
+    name: 'root',
+    workspaces: ['packages/*', 'apps/*'],
+  });
+});
+
+afterEach(() => {
+  fs.rmSync(repoRoot, { recursive: true, force: true });
+});
+
+describe('discoverWorkspaceDirs', () => {
+  test('expands dir/* patterns, skips dotdirs and dirs without package.json', () => {
+    makeWorkspace('packages/a');
+    makeWorkspace('packages/b');
+    makeWorkspace('apps/web');
+    fs.mkdirSync(path.join(repoRoot, 'packages/.template'), { recursive: true });
+    writeJson(path.join(repoRoot, 'packages/.template/package.json'), { name: 't' });
+    fs.mkdirSync(path.join(repoRoot, 'packages/no-pkg'), { recursive: true });
+
+    const dirs = discoverWorkspaceDirs(repoRoot).map((d) => path.relative(repoRoot, d));
+    expect(dirs).toEqual(['apps/web', 'packages/a', 'packages/b']);
+  });
+});
+
+describe('findRepoRoot', () => {
+  test('walks up to the package.json that declares workspaces', () => {
+    makeWorkspace('packages/a');
+    const found = findRepoRoot(path.join(repoRoot, 'packages/a'));
+    expect(found).toBe(path.resolve(repoRoot));
+  });
+});
+
+describe('aggregateWorkspacesReport', () => {
+  function rootResults(commands, success = true) {
+    writeJson(
+      path.join(repoRoot, 'logs/scripts-orchestrator-logs/scripts-orchestrator-results.json'),
+      { success, timestamp: fresh(5), overallDurationMs: 1234, commands },
+    );
+  }
+
+  function markRunning() {
+    writeJson(path.join(repoRoot, 'logs/.scripts-orchestrator-run.json'), {
+      startedAt: RUN_STARTED,
+      pid: 123,
+    });
+  }
+
+  test('classifies ok / fail workspaces and re-roots their log paths', () => {
+    rootResults([
+      { command: 'lint', phase: 'global quality checks', success: true },
+    ]);
+    makeWorkspace('apps/web', {
+      name: '@app/web',
+      results: {
+        success: true,
+        timestamp: fresh(),
+        commands: [{ command: 'test', success: true, logFile: 'logs/scripts-orchestrator-logs/test.log' }],
+      },
+    });
+    makeWorkspace('packages/a', {
+      name: '@pkg/a',
+      results: {
+        success: false,
+        timestamp: fresh(),
+        commands: [{ command: 'build', success: false }],
+      },
+    });
+
+    const report = aggregateWorkspacesReport({ repoRoot });
+    expect(report.inProgress).toBe(false);
+    expect(report.success).toBe(false); // a failing workspace fails the roll-up
+
+    const web = report.sections.find((s) => s.title === '@app/web');
+    expect(web.statusLabel).toBe('OK');
+    expect(web.commands[0].logFile).toBe('apps/web/logs/scripts-orchestrator-logs/test.log');
+
+    const a = report.sections.find((s) => s.title === '@pkg/a');
+    expect(a.statusLabel).toBe('FAIL');
+  });
+
+  test('success when every scope passes', () => {
+    rootResults([{ command: 'lint', phase: 'global quality checks', success: true }]);
+    makeWorkspace('apps/web', {
+      results: { success: true, timestamp: fresh(), commands: [] },
+    });
+    const report = aggregateWorkspacesReport({ repoRoot });
+    expect(report.success).toBe(true);
+  });
+
+  test('global check failure fails the roll-up', () => {
+    rootResults(
+      [{ command: 'lint', phase: 'global quality checks', success: false }],
+      false,
+    );
+    makeWorkspace('apps/web', { results: { success: true, timestamp: fresh(), commands: [] } });
+    const report = aggregateWorkspacesReport({ repoRoot });
+    expect(report.success).toBe(false);
+    const global = report.sections.find((s) => s.title === 'Global quality checks');
+    expect(global.success).toBe(false);
+  });
+
+  test('in-progress run: success:null workspace is RUNNING, missing is PENDING', () => {
+    markRunning();
+    rootResults([{ command: 'lint', phase: 'global quality checks', success: true }], null);
+    makeWorkspace('apps/web', {
+      results: { success: null, timestamp: fresh(), commands: [{ command: 'test', success: null }] },
+    });
+    makeWorkspace('packages/a'); // no results yet
+
+    const report = aggregateWorkspacesReport({ repoRoot });
+    expect(report.inProgress).toBe(true);
+    expect(report.success).toBeNull();
+    expect(report.sections.find((s) => s.title === 'apps/web').statusLabel).toBe('RUNNING');
+    expect(report.sections.find((s) => s.title === 'packages/a').statusLabel).toBe('PENDING');
+  });
+
+  test('after the run, a success:null results file reads as INTERRUPTED, not running', () => {
+    rootResults([{ command: 'lint', phase: 'global quality checks', success: true }]);
+    makeWorkspace('apps/web', {
+      results: { success: null, timestamp: fresh(), commands: [{ command: 'test', success: null }] },
+    });
+    const report = aggregateWorkspacesReport({ repoRoot });
+    expect(report.inProgress).toBe(false);
+    expect(report.sections.find((s) => s.title === 'apps/web').statusLabel).toBe('INTERRUPTED');
+    expect(report.success).toBe(false);
+  });
+
+  test('end-of-run fire (no run-state): derives run start from root end − duration, not end', () => {
+    // The orchestrator clears the run-state file before its final aggregate, and the root
+    // results timestamp is the run's END. A workspace that finished mid-run has a timestamp
+    // BEFORE that end — it must read OK, not STALE.
+    const runStart = RUN_STARTED_MS;
+    const runEnd = runStart + 200 * 1000; // 200s run
+    writeJson(
+      path.join(repoRoot, 'logs/scripts-orchestrator-logs/scripts-orchestrator-results.json'),
+      {
+        success: true,
+        timestamp: new Date(runEnd).toISOString(),
+        overallDurationMs: runEnd - runStart,
+        commands: [{ command: 'lint', phase: 'global quality checks', success: true }],
+      },
+    );
+    // Workspace finished 60s into the run — before the root end timestamp.
+    makeWorkspace('apps/web', {
+      results: {
+        success: true,
+        timestamp: new Date(runStart + 60 * 1000).toISOString(),
+        commands: [{ command: 'test', success: true }],
+      },
+    });
+
+    const report = aggregateWorkspacesReport({ repoRoot });
+    expect(report.inProgress).toBe(false);
+    expect(report.sections.find((s) => s.title === 'apps/web').statusLabel).toBe('OK');
+    expect(report.success).toBe(true);
+  });
+
+  test('stale results from a previous run are not counted as this run', () => {
+    rootResults([{ command: 'lint', phase: 'global quality checks', success: true }]);
+    makeWorkspace('apps/web', {
+      results: { success: true, timestamp: old(120), commands: [{ command: 'test', success: true }] },
+    });
+    const report = aggregateWorkspacesReport({ repoRoot });
+    const web = report.sections.find((s) => s.title === 'apps/web');
+    expect(web.statusLabel).toBe('STALE');
+    expect(web.commands).toHaveLength(0);
+  });
+
+  test('cache replay: stale workspace JSON + passing fan-out phase reads as CACHED with commands', () => {
+    // Root results carry the workspace fan-out phase (it passed this run) plus globals.
+    writeJson(
+      path.join(repoRoot, 'logs/scripts-orchestrator-logs/scripts-orchestrator-results.json'),
+      {
+        success: true,
+        timestamp: fresh(5),
+        overallDurationMs: 1234,
+        commands: [
+          { command: 'lint', phase: 'global quality checks', success: true },
+          { command: 'fan-out', phase: 'workspace quality gates', success: true },
+        ],
+      },
+    );
+    // Workspace results predate this run (cache replay did not re-execute it / rewrite its JSON).
+    makeWorkspace('apps/web', {
+      results: { success: true, timestamp: old(600), commands: [{ command: 'test', success: true }] },
+    });
+
+    const report = aggregateWorkspacesReport({ repoRoot });
+    const web = report.sections.find((s) => s.title === 'apps/web');
+    expect(web.statusLabel).toBe('CACHED');
+    expect(web.commands).toHaveLength(1); // last-known (cached) commands surfaced
+    expect(web.success).toBe(true);
+    expect(report.success).toBe(true); // cached pass does not fail the roll-up
+  });
+
+  test('failed fan-out phase does not turn stale workspaces into CACHED', () => {
+    writeJson(
+      path.join(repoRoot, 'logs/scripts-orchestrator-logs/scripts-orchestrator-results.json'),
+      {
+        success: false,
+        timestamp: fresh(5),
+        overallDurationMs: 1234,
+        commands: [{ command: 'fan-out', phase: 'workspace quality gates', success: false }],
+      },
+    );
+    makeWorkspace('apps/web', {
+      results: { success: true, timestamp: old(600), commands: [{ command: 'test', success: true }] },
+    });
+    const report = aggregateWorkspacesReport({ repoRoot });
+    expect(report.sections.find((s) => s.title === 'apps/web').statusLabel).toBe('STALE');
+  });
+
+  test('a no-op gate (echo "not applicable" or no script) is marked N/A', () => {
+    rootResults([{ command: 'lint', phase: 'global quality checks', success: true }]);
+    makeWorkspace('apps/web', { orchestratorScript: 'echo "not applicable"' });
+    makeWorkspace('packages/a', { orchestratorScript: null });
+    const report = aggregateWorkspacesReport({ repoRoot });
+    expect(report.sections.find((s) => s.title === 'apps/web').statusLabel).toBe('N/A');
+    expect(report.sections.find((s) => s.title === 'packages/a').statusLabel).toBe('N/A');
+  });
+
+  test('exclude option drops a workspace from the report', () => {
+    rootResults([]);
+    makeWorkspace('packages/.ignored-by-glob');
+    makeWorkspace('packages/a', { results: { success: true, timestamp: fresh(), commands: [] } });
+    const report = aggregateWorkspacesReport({ repoRoot, exclude: ['packages/a'] });
+    expect(report.sections.find((s) => s.title === 'packages/a')).toBeUndefined();
+  });
+});
+
+describe('writeAggregateReport', () => {
+  test('writes JSON + HTML and injects auto-refresh only while in progress', () => {
+    writeJson(path.join(repoRoot, 'logs/.scripts-orchestrator-run.json'), {
+      startedAt: RUN_STARTED,
+      pid: 1,
+    });
+    writeJson(
+      path.join(repoRoot, 'logs/scripts-orchestrator-logs/scripts-orchestrator-results.json'),
+      { success: null, timestamp: fresh(), commands: [] },
+    );
+    makeWorkspace('apps/web', { results: { success: true, timestamp: fresh(), commands: [] } });
+
+    const { jsonPath, htmlPath } = writeAggregateReport({ repoRoot, title: 'My Roll-up' });
+    expect(fs.existsSync(jsonPath)).toBe(true);
+    const html = fs.readFileSync(htmlPath, 'utf8');
+    expect(html).toContain('My Roll-up');
+    expect(html).toContain('http-equiv="refresh"'); // in progress → live refresh
+
+    // Once finished (no run-state, root results finalized) the refresh meta is gone.
+    fs.rmSync(path.join(repoRoot, 'logs/.scripts-orchestrator-run.json'));
+    writeJson(
+      path.join(repoRoot, 'logs/scripts-orchestrator-logs/scripts-orchestrator-results.json'),
+      { success: true, timestamp: fresh(), commands: [] },
+    );
+    const res = writeAggregateReport({ repoRoot, title: 'My Roll-up' });
+    expect(fs.readFileSync(res.htmlPath, 'utf8')).not.toContain('http-equiv="refresh"');
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scripts-orchestrator",
-  "version": "2.15.1",
+  "version": "3.5.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,10 +1,22 @@
 export default {
+  // Optional: prefix prepended to every command. Defaults to 'npm run'.
+  // Set to '' (or false/null) to run commands verbatim as regular shell commands,
+  // or to another runner like 'pnpm run'. Per-command `shell: true` / `prefix` override this.
+  // command_prefix: 'npm run',
   // 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',
+  // Optional: memory heat thresholds for the HTML report — fractions (0–1) of the run's peak memory.
+  // A command at/above `high` is coloured red, at/above `mid` amber, below `mid` green, on both the
+  // Gantt and the Memory table column. Defaults to { mid: 0.33, high: 0.66 } if omitted/invalid.
+  // memory_heat: { mid: 0.33, high: 0.66 },
+  // Optional: duration heat thresholds for the HTML report — fractions (0–1) of the run's slowest
+  // command. A command at/above `high` is coloured red, at/above `mid` amber, below `mid` green, in
+  // the Duration table column. Defaults to { mid: 0.33, high: 0.66 } if omitted/invalid.
+  // duration_heat: { mid: 0.33, high: 0.66 },
   phases: [
     {
       name: 'build',