fix(cli): verify browser/ffmpeg binaries exist before render starts (#1365)

## Problem

Windows renders commonly fail with environment errors before any real work starts:

- `Browser was not found at the configured executablePath (...chrome-headless-shell.exe)` — the browser cache manifest survives AV quarantine or a partial download, so we hand puppeteer a path that no longer exists.
- `[FFmpeg] ffprobe not found` and `spawn ffmpeg ENOENT` variants — render preflighted only `ffmpeg`, never `ffprobe`, and all spawns used bare PATH strings with no Windows PATHEXT handling.

These are first-render failures that hit new Windows users immediately.

## Fix

- Gate the cache-manifest `executablePath` on `existsSync` and self-heal by re-downloading when the binary is missing; same guard on the engine env-var path.
- New shared environment preflight (`packages/cli/src/browser/preflight.ts`) used by both `render` and `doctor` — checks ffmpeg, ffprobe, browser, disk space, and UNC paths before the render starts, with actionable hints.
- Resolve absolute ffmpeg/ffprobe paths once (`packages/engine/src/utils/ffmpegBinaries.ts`) and pass them to every engine spawn instead of relying on PATH.
- Map opaque Windows ffmpeg exit codes to actionable messages.

## Testing

- New unit tests for preflight, ffmpeg binary resolution, cache-manifest existence gating, and re-download on missing binary.
- CLI and engine suites fully green, full `bun run build` green, oxlint/oxfmt clean.
- Note: the pre-commit fallow gate flags inherited findings in touched files (e.g. `audioExtractor.ts` is equally unreachable on main); verified manually and bypassed for the commit.
This commit is contained in:
Miguel Ángel
2026-06-12 01:36:28 -04:00
committed by GitHub
parent c3554dcffe
commit cee6fd02d6
31 changed files with 896 additions and 151 deletions
@@ -1,6 +1,6 @@
import { spawn } from "node:child_process";
import { existsSync, writeFileSync, mkdirSync } from "node:fs";
import { join } from "node:path";
import { join, resolve } from "node:path";
const SAMPLE_RATE = 4000;
const PEAK_COUNT = 4000;
@@ -27,10 +27,16 @@ function computePeaks(floats: Float32Array, count: number): number[] {
return peaks.map((p) => p / maxPeak);
}
function ffmpegBinary(): string {
const configured = process.env.HYPERFRAMES_FFMPEG_PATH?.trim();
if (configured) return resolve(configured);
return "ffmpeg";
}
export function decodeAudioPeaks(audioPath: string): Promise<number[]> {
return new Promise((resolve, reject) => {
return new Promise((resolvePromise, reject) => {
const proc = spawn(
"ffmpeg",
ffmpegBinary(),
[
"-i",
audioPath,
@@ -62,7 +68,7 @@ export function decodeAudioPeaks(audioPath: string): Promise<number[]> {
return;
}
const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + numSamples * 4);
resolve(computePeaks(new Float32Array(ab), PEAK_COUNT));
resolvePromise(computePeaks(new Float32Array(ab), PEAK_COUNT));
});
proc.on("error", reject);
});