test(engine): add ffprobe-unavailable fallback regression tests

[vanceingalls]

Summary

Mock node:child_process.spawn to surface ENOENT and verify ffprobe's three callers behave correctly when ffprobe is missing.

Why

Chunk 9B of plans/hdr-followups.md. The PNG cICP fallback in extractMediaMetadata was added to support environments without ffprobe, but no test pinned the behavior — silently regressing it would break HDR image support on any system without ffprobe installed.

What changed

packages/engine/src/utils/ffprobe.test.ts: mocks child_process.spawn to surface ENOENT and asserts:

• extractMediaMetadata falls back to PNG cICP metadata for image inputs.
• extractMediaMetadata rethrows for non-image inputs lacking a still-image fallback.
• extractAudioMetadata + analyzeKeyframeIntervals propagate the install-hint error verbatim.

Test plan

• All new tests pass.
• No production code changes — pure regression coverage of existing fallback behavior.

Stack

Chunk 9B of plans/hdr-followups.md. Test-only change, independent of all other chunks.

[vanceingalls]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• docs(engine): document __name polyfill and add regression test #385
• perf(producer): cache transfer-converted hdr image buffers per render job #384
• perf(producer): gate per-frame debug meta via optional isLevelEnabled #383
• perf(producer): hdr benchmark harness — --tags filter, peak heap/RSS tracking, bench:hdr script #382
• test(producer): extract frameDirMaxIndexCache to its own module and pin cross-job isolation #381
• test(engine): cover spawnStreamingEncoder lifecycle and cleanup paths #380
• test(engine): add ffprobe-unavailable fallback regression tests #379 👈 (View in Graphite)
• test(shader-transitions): add midpoint (p=0.5) regression invariants for all shaders #378
• test(engine): lock down sRGB→BT.2020 LUT with byte-exact reference values #377
• build(lfs): track tests/*/src/*.png via Git LFS #376
• test(hdr-regression): tighten Window F maxFrameFailures budget after Chunk 4 fix #375
• fix(engine,shader): handle matrix3d transforms and hide non-first scenes #374
• refactor(producer): extract HDR compositing helpers and rename media metadata #373
• fix(producer): wire --crf and --video-bitrate CLI overrides into encoders #372
• fix(producer): tighten resource lifecycle and harden file server #371
• feat(engine): wire options.hdr through chunkEncoder + dynamic SDR→HDR transfer #370
• test(hdr-regression): tighten Window C maxFrameFailures budget after Chunk 1 fix #369
• fix(engine): stop clobbering native <video> opacity in HDR pipeline #368
• refactor(shader-transitions): extract DEFAULT_DURATION and DEFAULT_EASE constants #367
• refactor(types): tighten type safety, dedupe HfTransitionMeta, prune dead LUT export #366
• test(producer): add hdr-regression and hdr-hlg-regression test suites #365
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jrusso1020]

ffprobe-unavailable regression tests are the right coverage for a fallback path that's easy to break silently. The fallback exists for environments where ffprobe isn't on PATH (some minimal Docker images, some CI runners pre-apt-install) — without test coverage, someone could refactor extractMediaMetadata and lose the fallback entirely, with the bug only showing up when the environment actually lacked ffprobe.

Pinning both the "ffprobe missing" branch and the "ffprobe returns garbage" branch (if covered) is the durable form. Approved.

— Rames Jusso

[vanceingalls]

Thanks for the approval @jrusso1020.

You're right that this is exactly the silent-breakage class — the fallback only matters in environments without ffprobe on PATH (slim Docker images, pre-apt install CI), so a refactor of extractMediaMetadata could remove the fallback and every test would still pass on a normal dev machine.

The pinned surface in packages/engine/src/utils/ffprobe.test.ts is:

1. PNG cICP fallback succeeds when ffprobe is missing — confirms videoCodec, colorTransfer=smpte2084, colorPrimaries=bt2020.
2. Non-image files rethrow the ffprobe not found error verbatim — i.e. the fallback isn't accidentally swallowing errors for inputs it can't handle.
3. Sibling APIs (extractAudioMetadata, analyzeKeyframeIntervals) also rethrow verbatim — pins that the fallback is scoped to extractMediaMetadata and didn't accidentally bleed into other surfaces.
4. Install hint ("Please install FFmpeg") is part of the error contract.

So the "ffprobe missing" branch is fully covered. The "ffprobe returns garbage" branch isn't pinned in this PR — it's a different failure mode (ffprobe runs but emits malformed JSON / unexpected schema) and would need a separate harness. Logged as a follow-up rather than blocking this one.

No outstanding action items from the review.