flake-monster 0.3.5 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flake-monster",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "Source-to-source test hardener that injects async delays to surface flaky tests",
   "type": "module",
   "bin": {

package/src/adapters/javascript/index.js

@@ -15,14 +15,14 @@ const RUNTIME_FILENAME = 'flake-monster.runtime.js';
  * @returns {string}
  */
 function computeRuntimeImportPath(filePath) {
-  // Count directory depth
-  const parts = filePath.split('/').filter(Boolean);
-  if (parts.length <= 1) {
+  const normalized = posix.normalize(filePath);
+  const dir = posix.dirname(normalized);
+  if (dir === '.') {
     // File is at root level
     return `./${RUNTIME_FILENAME}`;
   }
-  // Go up (parts.length - 1) directories
-  const ups = '../'.repeat(parts.length - 1);
+  const depth = dir.split('/').length;
+  const ups = '../'.repeat(depth);
   return `${ups}${RUNTIME_FILENAME}`;
 }
 

package/src/cli/commands/test.js

@@ -1,33 +1,16 @@
 import { resolve } from 'node:path';
-import { execSync } from 'node:child_process';
 import { AdapterRegistry } from '../../adapters/registry.js';
 import { createJavaScriptAdapter } from '../../adapters/javascript/index.js';
 import { InjectorEngine } from '../../core/engine.js';
 import { FlakeProfile } from '../../core/profile.js';
 import { parseSeed, deriveSeed } from '../../core/seed.js';
-import { ProjectWorkspace, getFlakeMonsterDir } from '../../core/workspace.js';
+import { ProjectWorkspace, getFlakeMonsterDir, execAsync } from '../../core/workspace.js';
 import { loadConfig, mergeWithCliOptions } from '../../core/config.js';
 import { Reporter } from '../../core/reporter.js';
 import { detectRunner, parseTestOutput } from '../../core/parsers/index.js';
 import { analyzeFlakiness } from '../../core/flake-analyzer.js';
-
-function execInDir(command, cwd) {
-  try {
-    const stdout = execSync(command, {
-      cwd,
-      env: { ...process.env },
-      encoding: 'utf-8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    return { exitCode: 0, stdout, stderr: '' };
-  } catch (err) {
-    return {
-      exitCode: err.status ?? 1,
-      stdout: err.stdout || '',
-      stderr: err.stderr || '',
-    };
-  }
-}
+import * as terminal from '../terminal.js';
+import { StickyLine } from '../terminal.js';
 
 export function registerTestCommand(program) {
   program
@@ -68,7 +51,7 @@ export function registerTestCommand(program) {
         const registry = new AdapterRegistry();
         registry.register(createJavaScriptAdapter());
         const engine = new InjectorEngine(registry, profile);
-        const reporter = new Reporter({ quiet: jsonOutput });
+        const reporter = new Reporter({ quiet: jsonOutput, terminal });
 
         reporter.log(`FlakeMonster test harness`);
         reporter.log(`  Runs: ${runs} | Mode: ${profile.mode} | Base seed: ${baseSeed}`);
@@ -82,6 +65,7 @@ export function registerTestCommand(program) {
         }
         reporter.log('');
 
+        const harnessTotalStart = Date.now();
         const results = [];
         let lastManifest = null;
 
@@ -99,11 +83,36 @@ export function registerTestCommand(program) {
             const flakeDir = getFlakeMonsterDir(projectRoot);
             await manifest.save(flakeDir);
             lastManifest = manifest;
+            reporter.printInjectionStats(manifest);
 
-            // Run tests in project root
+            // Run tests — stream output with sticky status line
+            const passed = results.filter(r => r.exitCode === 0).length;
+            const failed = results.length - passed;
+            const sticky = new StickyLine();
             const start = Date.now();
-            const { exitCode, stdout, stderr } = execInDir(testCmd, projectRoot);
-            const durationMs = Date.now() - start;
+            let stickyTimer;
+
+            if (!reporter.quiet) {
+              const stickyContent = () => {
+                const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+                const bar = terminal.progressBar(i, runs);
+                return terminal.dim(`  ${bar}  ${passed} passed  ${failed} failed  `) + `Run ${i + 1}/${runs}  ${elapsed}s`;
+              };
+              sticky.start(stickyContent());
+              stickyTimer = setInterval(() => sticky.update(stickyContent()), 200);
+            }
+
+            let exitCode, stdout, stderr, durationMs;
+            try {
+              ({ exitCode, stdout, stderr } = await execAsync(testCmd, projectRoot, {
+                onStdout: reporter.quiet ? undefined : (chunk) => sticky.writeAbove(chunk),
+                onStderr: reporter.quiet ? undefined : (chunk) => sticky.writeAboveStderr(chunk),
+              }));
+              durationMs = Date.now() - start;
+            } finally {
+              if (stickyTimer) clearInterval(stickyTimer);
+              sticky.clear();
+            }
 
             // Parse test output if we have a runner
             const parsed = runner ? parseTestOutput(runner, stdout) : null;
@@ -122,7 +131,6 @@ export function registerTestCommand(program) {
             };
 
             reporter.printRunResult(result, runs);
-            results.push(result);
           } else {
             // Create workspace
             const workspace = new ProjectWorkspace({
@@ -135,14 +143,39 @@ export function registerTestCommand(program) {
             const manifest = await engine.injectAll(workspace.root, globs, runSeed, merged.exclude);
             const flakeDir = getFlakeMonsterDir(workspace.root);
             await manifest.save(flakeDir);
+            reporter.printInjectionStats(manifest);
 
-            // Run tests
+            // Run tests — stream output with sticky status line
+            const passed = results.filter(r => r.exitCode === 0).length;
+            const failed = results.length - passed;
+            const sticky = new StickyLine();
             const start = Date.now();
-            const { exitCode, stdout, stderr } = workspace.exec(testCmd);
-            const durationMs = Date.now() - start;
+            let stickyTimer;
+
+            if (!reporter.quiet) {
+              const stickyContent = () => {
+                const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+                const bar = terminal.progressBar(i, runs);
+                return terminal.dim(`  ${bar}  ${passed} passed  ${failed} failed  `) + `Run ${i + 1}/${runs}  ${elapsed}s`;
+              };
+              sticky.start(stickyContent());
+              stickyTimer = setInterval(() => sticky.update(stickyContent()), 200);
+            }
+
+            let exitCode, stdout, stderr, durationMs;
+            try {
+              ({ exitCode, stdout, stderr } = await workspace.execAsync(testCmd, {
+                onStdout: reporter.quiet ? undefined : (chunk) => sticky.writeAbove(chunk),
+                onStderr: reporter.quiet ? undefined : (chunk) => sticky.writeAboveStderr(chunk),
+              }));
+              durationMs = Date.now() - start;
+            } finally {
+              if (stickyTimer) clearInterval(stickyTimer);
+              sticky.clear();
+            }
 
-            const failed = exitCode !== 0;
-            const shouldKeep = (failed && options.keepOnFail) || options.keepAll;
+            const testFailed = exitCode !== 0;
+            const shouldKeep = (testFailed && options.keepOnFail) || options.keepAll;
 
             // Parse test output if we have a runner
             const parsed = runner ? parseTestOutput(runner, stdout) : null;
@@ -161,7 +194,6 @@ export function registerTestCommand(program) {
             };
 
             reporter.printRunResult(result, runs);
-            results.push(result);
 
             // Cleanup
             if (!shouldKeep) {
@@ -172,12 +204,13 @@ export function registerTestCommand(program) {
 
         // Restore source files after all in-place runs
         if (inPlace && lastManifest) {
-          await engine.restoreAll(projectRoot, lastManifest);
-          reporter.log('\n  Source files restored to original state.');
+          const restoreResult = await engine.restoreAll(projectRoot, lastManifest);
+          reporter.printRestorationResult(restoreResult);
         }
 
         // Run flakiness analysis if we have parsed results
         const analysis = runner ? analyzeFlakiness(results) : null;
+        const totalElapsedMs = Date.now() - harnessTotalStart;
 
         if (jsonOutput) {
           // JSON output for CI consumption
@@ -197,7 +230,7 @@ export function registerTestCommand(program) {
           };
           console.log(JSON.stringify(output));
         } else {
-          reporter.summarize(results, runs);
+          reporter.summarize(results, runs, analysis, totalElapsedMs);
         }
 
         // Exit with failure if any run failed

package/src/cli/index.js

@@ -9,7 +9,7 @@ export function createCli() {
   program
     .name('flake-monster')
     .description('Source-to-source test hardener, injects async delays to surface flaky tests')
-    .version('0.3.1');
+    .version('0.4.0');
 
   registerInjectCommand(program);
   registerRestoreCommand(program);

package/src/cli/terminal.js

@@ -0,0 +1,186 @@
+/**
+ * Terminal utilities for rich CLI output.
+ * Zero dependencies — raw ANSI escape codes + process.stdout.
+ */
+
+// ── Color support detection ───────────────────────────────────────────
+
+let _colorEnabled = null;
+
+/**
+ * Check whether the terminal supports ANSI color codes.
+ * Respects NO_COLOR (https://no-color.org/) and FORCE_COLOR env vars.
+ */
+export function supportsColor() {
+  if (_colorEnabled !== null) return _colorEnabled;
+  if (process.env.NO_COLOR !== undefined) {
+    _colorEnabled = false;
+  } else if (process.env.FORCE_COLOR !== undefined) {
+    _colorEnabled = true;
+  } else {
+    _colorEnabled = process.stdout.isTTY === true;
+  }
+  return _colorEnabled;
+}
+
+/** Reset the memoized color detection (for testing). */
+export function resetColorCache() {
+  _colorEnabled = null;
+}
+
+/** Whether stdout is an interactive terminal. */
+export function isTTY() {
+  return process.stdout.isTTY === true;
+}
+
+// ── ANSI wrappers ─────────────────────────────────────────────────────
+
+function wrap(open, close) {
+  return (s) => supportsColor() ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+}
+
+export const bold = wrap('1', '22');
+export const dim = wrap('2', '22');
+export const red = wrap('31', '39');
+export const green = wrap('32', '39');
+export const yellow = wrap('33', '39');
+export const cyan = wrap('36', '39');
+
+/**
+ * Strip ANSI escape codes from a string.
+ * @param {string} s
+ * @returns {string}
+ */
+export function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1b\[\d+m/g, '');
+}
+
+// ── Progress bar ──────────────────────────────────────────────────────
+
+const BLOCK_FILLED = '\u2588'; // █
+const BLOCK_EMPTY = '\u2591';  // ░
+
+/**
+ * Render a text progress bar.
+ * @param {number} current
+ * @param {number} total
+ * @param {number} [width=20]
+ * @returns {string}  e.g. "██████░░░░░░░░░░░░░░ 3/10"
+ */
+export function progressBar(current, total, width = 20) {
+  const filled = total > 0 ? Math.round((current / total) * width) : 0;
+  const empty = width - filled;
+  return BLOCK_FILLED.repeat(filled) + BLOCK_EMPTY.repeat(empty) + ` ${current}/${total}`;
+}
+
+// ── Box drawing ───────────────────────────────────────────────────────
+
+/**
+ * Wrap lines in a Unicode box.
+ * @param {string[]} lines
+ * @returns {string}
+ */
+export function box(lines) {
+  const stripped = lines.map(stripAnsi);
+  const maxLen = Math.max(...stripped.map(l => l.length));
+  const pad = (line, strippedLine) => {
+    const diff = maxLen - strippedLine.length;
+    return line + ' '.repeat(diff);
+  };
+
+  const top = '  \u250c\u2500' + '\u2500'.repeat(maxLen) + '\u2500\u2510';
+  const bottom = '  \u2514\u2500' + '\u2500'.repeat(maxLen) + '\u2500\u2518';
+  const body = lines.map((line, i) => `  \u2502 ${pad(line, stripped[i])} \u2502`);
+
+  return [top, ...body, bottom].join('\n');
+}
+
+// ── Sticky line ───────────────────────────────────────────────────────
+
+/**
+ * A persistent status line that stays at the bottom of the terminal
+ * while other output scrolls above it.
+ *
+ * On non-TTY terminals, does nothing — output flows normally.
+ */
+export class StickyLine {
+  constructor() {
+    this._content = '';
+    this._active = false;
+  }
+
+  /**
+   * Start showing the sticky line.
+   * @param {string} content - Initial content
+   */
+  start(content) {
+    this._active = true;
+    this._content = content;
+    if (isTTY()) {
+      process.stdout.write(this._content);
+    }
+  }
+
+  /**
+   * Update the sticky line content (e.g. elapsed timer).
+   * @param {string} content
+   */
+  update(content) {
+    this._content = content;
+    if (this._active && isTTY()) {
+      process.stdout.write('\r\x1b[K' + this._content);
+    }
+  }
+
+  /**
+   * Write output above the sticky line.
+   * Clears the sticky, writes the chunk, then re-renders.
+   * @param {Buffer|string} chunk
+   */
+  writeAbove(chunk) {
+    if (!this._active || !isTTY()) {
+      process.stdout.write(chunk);
+      return;
+    }
+    // Clear sticky line
+    process.stdout.write('\r\x1b[K');
+    // Write the actual output
+    process.stdout.write(chunk);
+    // Ensure sticky gets its own line
+    const str = chunk.toString();
+    if (str.length > 0 && !str.endsWith('\n')) {
+      process.stdout.write('\n');
+    }
+    // Re-render sticky
+    process.stdout.write(this._content);
+  }
+
+  /**
+   * Write stderr output above the sticky line.
+   * @param {Buffer|string} chunk
+   */
+  writeAboveStderr(chunk) {
+    if (!this._active || !isTTY()) {
+      process.stderr.write(chunk);
+      return;
+    }
+    // Clear sticky on stdout, write stderr, re-render sticky
+    process.stdout.write('\r\x1b[K');
+    process.stderr.write(chunk);
+    const str = chunk.toString();
+    if (str.length > 0 && !str.endsWith('\n')) {
+      process.stderr.write('\n');
+    }
+    process.stdout.write(this._content);
+  }
+
+  /** Clear the sticky line and deactivate. */
+  clear() {
+    if (this._active && isTTY()) {
+      process.stdout.write('\r\x1b[K');
+    }
+    this._active = false;
+    this._content = '';
+  }
+}

package/src/core/reporter.js

@@ -1,9 +1,29 @@
 /**
  * Formats test run results for terminal output.
+ * Accepts an optional terminal helpers object for colored/styled output.
  */
+
+/** No-op terminal helpers (used when no real terminal is injected). */
+const NOOP_TERMINAL = {
+  bold: (s) => s,
+  dim: (s) => s,
+  red: (s) => s,
+  green: (s) => s,
+  yellow: (s) => s,
+  cyan: (s) => s,
+  progressBar: (c, t) => `${c}/${t}`,
+  box: (lines) => lines.join('\n'),
+};
+
 export class Reporter {
-  constructor({ quiet = false } = {}) {
+  /**
+   * @param {Object} [options]
+   * @param {boolean} [options.quiet=false] - Suppress all output
+   * @param {Object} [options.terminal] - Terminal helpers (colors, progressBar, box)
+   */
+  constructor({ quiet = false, terminal = null } = {}) {
     this.quiet = quiet;
+    this.t = terminal || NOOP_TERMINAL;
   }
 
   log(...args) {
@@ -11,65 +31,137 @@ export class Reporter {
   }
 
   /**
-   * Print a summary of all test runs.
-   * @param {Object[]} results - Array of per-run results
-   *   Each: { runIndex, seed, exitCode, stdout, stderr, durationMs, workspacePath, kept }
-   * @param {number} totalRuns
+   * Print injection scan stats after engine.injectAll().
+   * @param {import('./manifest.js').Manifest} manifest
    */
-  summarize(results, totalRuns) {
+  printInjectionStats(manifest) {
     if (this.quiet) return;
-    console.log('\n--- FlakeMonster Results ---\n');
-
-    const failures = [];
+    const { dim, cyan } = this.t;
+    const fileCount = Object.keys(manifest.getFiles()).length;
+    const injections = manifest.getTotalInjections();
+    console.log(`  ${cyan('\u2713')} ${injections} injection points across ${fileCount} file(s)`);
+  }
 
-    for (const r of results) {
-      const status = r.exitCode === 0 ? 'PASS' : 'FAIL';
-      const dur = (r.durationMs / 1000).toFixed(1);
-      let line = `  Run ${r.runIndex + 1}/${totalRuns}: ${status} (seed=${r.seed}, ${dur}s)`;
+  /**
+   * Print a single run result in real-time (during execution).
+   * @param {Object} result
+   * @param {number} totalRuns
+   */
+  printRunResult(result, totalRuns) {
+    if (this.quiet) return;
+    const { dim, red, green } = this.t;
+    const pass = result.exitCode === 0;
+    const icon = pass ? green('\u2713') : red('\u2717');
+    const status = pass ? green('PASS') : red('FAIL');
+    const dur = (result.durationMs / 1000).toFixed(1);
 
-      if (r.exitCode !== 0 && r.kept) {
-        line += `\n    Workspace kept: ${r.workspacePath}`;
-      }
+    let line = `  ${icon} Run ${result.runIndex + 1}/${totalRuns}  ${status}  seed=${dim(String(result.seed))}  ${dur}s`;
 
-      console.log(line);
+    if (result.parsed && result.tests && result.tests.length > 0) {
+      const passed = result.tests.filter((t) => t.status === 'passed').length;
+      const failed = result.tests.filter((t) => t.status === 'failed').length;
+      let counts = `${passed} passed`;
+      if (failed > 0) counts += `, ${red(String(failed) + ' failed')}`;
+      line += `  (${counts})`;
+    }
 
-      if (r.exitCode !== 0) {
-        failures.push(r);
-      }
+    if (result.exitCode !== 0 && result.kept) {
+      line += `  ${dim('\u2014 workspace kept')}`;
     }
 
+    console.log(line);
+  }
+
+  /**
+   * Print a running tally / progress bar between runs.
+   * @param {Object[]} results - Results so far
+   * @param {number} totalRuns
+   */
+  printProgressTally(results, totalRuns) {
+    if (this.quiet) return;
+    const { dim, green, red } = this.t;
     const passed = results.filter((r) => r.exitCode === 0).length;
     const failed = results.length - passed;
-
-    console.log(`\n  Summary: ${passed}/${totalRuns} passed, ${failed}/${totalRuns} failed`);
-
-    if (failures.length > 0) {
-      const seeds = failures.map((f) => f.seed).join(', ');
-      console.log(`  Failing seeds: ${seeds}`);
-      console.log(`\n  Reproduce a failure:`);
-      console.log(`    flake-monster test --runs 1 --seed ${failures[0].seed} --cmd "<your test command>"`);
-    } else {
-      console.log('\n  No flakes detected in this run.');
-    }
-
+    const bar = this.t.progressBar(results.length, totalRuns);
+    console.log(`  ${dim(bar)}  ${green(String(passed) + ' passed')}  ${failed > 0 ? red(String(failed) + ' failed') : dim('0 failed')}`);
     console.log('');
   }
 
   /**
-   * Print a single run result in real-time (during execution).
-   * @param {Object} result
+   * Print restoration confirmation.
+   * @param {{ filesRestored: number, injectionsRemoved: number }} stats
+   */
+  printRestorationResult({ filesRestored }) {
+    if (this.quiet) return;
+    const { cyan } = this.t;
+    console.log(`\n  ${cyan('\u2713')} Source files restored (${filesRestored} files)`);
+  }
+
+  /**
+   * Print a rich summary of all test runs.
+   * @param {Object[]} results - Array of per-run results
    * @param {number} totalRuns
+   * @param {Object} [analysis] - Flakiness analysis from analyzeFlakiness()
+   * @param {number} [totalElapsedMs] - Total wall-clock time
    */
-  printRunResult(result, totalRuns) {
+  summarize(results, totalRuns, analysis = null, totalElapsedMs = null) {
     if (this.quiet) return;
-    const status = result.exitCode === 0 ? 'PASS' : 'FAIL';
-    const dur = (result.durationMs / 1000).toFixed(1);
-    let line = `  Run ${result.runIndex + 1}/${totalRuns}: ${status} (seed=${result.seed}, ${dur}s)`;
+    const { bold, dim, red, green, yellow } = this.t;
 
-    if (result.exitCode !== 0 && result.kept) {
-      line += ` — workspace kept`;
+    const passed = results.filter((r) => r.exitCode === 0).length;
+    const failed = results.length - passed;
+    const failures = results.filter((r) => r.exitCode !== 0);
+
+    const lines = [];
+    lines.push(bold('FlakeMonster Results'));
+    lines.push('');
+    lines.push(`Runs: ${passed}/${totalRuns} passed, ${failed}/${totalRuns} failed`);
+
+    if (totalElapsedMs != null) {
+      const secs = totalElapsedMs / 1000;
+      if (secs >= 60) {
+        const mins = Math.floor(secs / 60);
+        const rem = Math.round(secs % 60);
+        lines.push(`Total time: ${mins}m ${rem}s`);
+      } else {
+        lines.push(`Total time: ${secs.toFixed(1)}s`);
+      }
     }
 
-    console.log(line);
+    // Flaky test details
+    if (analysis && analysis.flakyTests.length > 0) {
+      lines.push('');
+      lines.push(yellow(`Flaky tests (${analysis.flakyTests.length}):`));
+      for (const t of analysis.flakyTests) {
+        const rate = (t.flakyRate * 100).toFixed(0);
+        const seeds = t.failedRuns
+          .map((i) => {
+            const r = results[i];
+            return r ? String(r.seed) : String(i);
+          })
+          .join(', ');
+        lines.push(`  ${red(rate + '%')} ${t.name}`);
+        lines.push(`       ${dim(`file: ${t.file || 'unknown'}  seeds: ${seeds}`)}`);
+      }
+    }
+
+    if (analysis && analysis.alwaysFailingTests.length > 0) {
+      lines.push('');
+      lines.push(red(`Always failing (${analysis.alwaysFailingTests.length}):`));
+      for (const t of analysis.alwaysFailingTests) {
+        lines.push(`  ${t.name} ${dim(`(${t.file || 'unknown'})`)}`);
+      }
+    }
+
+    if (failures.length > 0) {
+      lines.push('');
+      lines.push('Reproduce:');
+      lines.push(dim(`  flake-monster test --runs 1 --seed ${failures[0].seed}`));
+    } else {
+      lines.push('');
+      lines.push(green('No flakes detected.'));
+    }
+
+    console.log('\n' + this.t.box(lines) + '\n');
   }
 }

package/src/core/workspace.js

@@ -1,6 +1,6 @@
 import { rm, mkdir, readdir, copyFile, stat } from 'node:fs/promises';
 import { join, relative, basename } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execSync, spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 
 const FLAKE_MONSTER_DIR = '.flake-monster';
@@ -120,6 +120,19 @@ export class ProjectWorkspace {
     }
   }
 
+  /**
+   * Execute a shell command inside the workspace asynchronously.
+   * Unlike exec(), this does not block the event loop, allowing spinners to animate.
+   * @param {string} command
+   * @param {Object} [options]
+   * @param {number} [options.timeout] - ms before killing the process
+   * @param {Object} [options.env] - additional env vars
+   * @returns {Promise<{ exitCode: number, stdout: string, stderr: string }>}
+   */
+  execAsync(command, options = {}) {
+    return execAsync(command, this._root, options);
+  }
+
   /**
    * Delete the workspace directory.
    */
@@ -137,3 +150,63 @@ export class ProjectWorkspace {
 export function getFlakeMonsterDir(projectRoot) {
   return join(projectRoot, FLAKE_MONSTER_DIR);
 }
+
+/**
+ * Execute a shell command asynchronously without blocking the event loop.
+ * @param {string} command
+ * @param {string} cwd - Working directory
+ * @param {Object} [options]
+ * @param {number} [options.timeout] - ms before killing the process
+ * @param {Object} [options.env] - additional env vars
+ * @param {Function} [options.onStdout] - Callback for each stdout chunk (receives Buffer)
+ * @param {Function} [options.onStderr] - Callback for each stderr chunk (receives Buffer)
+ * @returns {Promise<{ exitCode: number, stdout: string, stderr: string }>}
+ */
+export function execAsync(command, cwd, options = {}) {
+  return new Promise((resolve) => {
+    const { timeout, env, onStdout, onStderr } = options;
+    const child = spawn(command, {
+      cwd,
+      shell: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, ...env },
+    });
+
+    const stdoutChunks = [];
+    const stderrChunks = [];
+
+    child.stdout.on('data', (chunk) => {
+      stdoutChunks.push(chunk);
+      if (onStdout) onStdout(chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderrChunks.push(chunk);
+      if (onStderr) onStderr(chunk);
+    });
+
+    let timer;
+    if (timeout) {
+      timer = setTimeout(() => {
+        child.kill('SIGTERM');
+      }, timeout);
+    }
+
+    child.on('close', (code) => {
+      if (timer) clearTimeout(timer);
+      resolve({
+        exitCode: code ?? 1,
+        stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
+        stderr: Buffer.concat(stderrChunks).toString('utf-8'),
+      });
+    });
+
+    child.on('error', (err) => {
+      if (timer) clearTimeout(timer);
+      resolve({
+        exitCode: 1,
+        stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
+        stderr: err.message,
+      });
+    });
+  });
+}