From 84799bdc59b18f6a3df6595d8a8d1ec03dfde673 Mon Sep 17 00:00:00 2001 From: James Russo Date: Wed, 11 Nov 2026 09:46:52 +0000 Subject: [PATCH] fix: take helper programs only from install locations, never the project folder (#7524) * fix(cli,parsers): take helper programs only from install locations, never the project folder FFmpeg, FFprobe, whisper-cli, parakeet-mlx, Python and system Chrome are now found through one shared rule: an absolute PATH entry outside the working directory, or a fixed install dir. A relative PATH entry and any folder inside the working directory are skipped, on every platform. Windows walks PATH itself instead of asking `where`, which lists the working directory first. FFmpeg discovery no longer falls back to `.hyperframes/bin` or to an installer package in the project's node_modules; an installer package installed next to HyperFrames still works. The env overrides are unchanged. The CLI skill reference stops suggesting the project-local folder. Co-Authored-By: Claude Opus 5.5 * test(cli): give the PATH-lookup tests a fixed PATH on Windows Windows now walks PATH instead of running `where`, so tests that faked `where` output found the runner's real python and cmake. Both tests now set PATH to a temp folder holding only the programs they expect. Co-Authored-By: Claude Opus 5.5 * fix: report a missing helper program instead of running it by bare name When no trusted FFmpeg or FFprobe is found, the engine, the producer's probes and Studio's waveform, peak and audio-track helpers now report "not found" with the HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH hint instead of handing the bare name to the OS lookup. Callers that degraded on a missing binary still do: runFfmpeg returns a spawn_error result, the GPU and version probes report none, and Studio's audio helpers fail soft. The Lambda handler names its bundled ffmpeg and ffprobe by path, since they live under the task root, which is the working directory. brew, git and cmake for the whisper.cpp install, and the clipboard tool for `hyperframes add`, run by the absolute path the trusted lookup approved. The media-use engine gets a PATH holding only trusted folders. Co-Authored-By: Claude Opus 5.5 * fix(engine): fail a missing FFmpeg the way a failed spawn always has Throwing from getFfmpegBinary turned every caller's missing-binary path into a synchronous throw: the streaming encoder's "failure result, not a throw" contract broke, and unit lanes that run without FFmpeg crashed at module load. With no trusted copy the getters now return an absolute path inside HyperFrames' own install that is never created, named for the override to set. Spawning it fails with ENOENT exactly as before, and the OS still never looks the bare name up. The call-site guards and fixture changes that the throw needed are reverted. The whisper install tests match git and cmake by name and skip the brew case on Windows, where the lookup walks the real PATH. Co-Authored-By: Claude Opus 5.5 * test(engine): pin the found FFmpeg before the HDR test looks it up as macOS on Windows Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- packages/aws-lambda/src/handler.test.ts | 52 ++++- packages/aws-lambda/src/handler.ts | 28 ++- packages/cli/src/browser/manager.test.ts | 29 ++- packages/cli/src/browser/manager.ts | 24 +-- packages/cli/src/commands/media-use.test.ts | 29 ++- packages/cli/src/commands/media-use.ts | 14 +- packages/cli/src/tts/python.test.ts | 35 +++- packages/cli/src/tts/python.ts | 20 +- packages/cli/src/utils/clipboard.test.ts | 21 ++ packages/cli/src/utils/clipboard.ts | 25 ++- .../src/utils/clipboard.windowsHide.test.ts | 30 ++- .../cli/src/whisper/manager.install.test.ts | 45 +++- packages/cli/src/whisper/manager.ts | 62 +++--- packages/cli/src/whisper/parakeet.ts | 19 +- .../cli/src/whisper/trustedLookup.test.ts | 46 +++++ .../services/videoFrameExtractor.hdr.test.ts | 5 + .../engine/src/utils/ffmpegBinaries.test.ts | 61 +++++- packages/engine/src/utils/ffmpegBinaries.ts | 16 +- packages/parsers/src/ffBinaries.test.ts | 192 ++++++++++-------- packages/parsers/src/ffBinaries.ts | 56 +++-- .../parsers/src/trustedExecutable.test.ts | 41 ++++ packages/parsers/src/trustedExecutable.ts | 96 +++++++++ .../helpers/childProcess.windowsHide.test.ts | 1 + .../src/helpers/loudness.windowsHide.test.ts | 5 + .../src/helpers/mediaMetadata.ts | 6 +- .../src/helpers/noTrustedFfmpeg.test.ts | 69 +++++++ .../src/helpers/peakMap.decodeFailure.test.ts | 1 + packages/studio-server/src/helpers/peakMap.ts | 5 +- .../src/helpers/waveform.file-race.test.ts | 5 +- .../studio-server/src/helpers/waveform.ts | 5 +- skills-manifest.json | 2 +- .../references/doctor-browser.md | 2 +- 32 files changed, 765 insertions(+), 282 deletions(-) create mode 100644 packages/cli/src/whisper/trustedLookup.test.ts create mode 100644 packages/parsers/src/trustedExecutable.test.ts create mode 100644 packages/parsers/src/trustedExecutable.ts create mode 100644 packages/studio-server/src/helpers/noTrustedFfmpeg.test.ts diff --git a/packages/aws-lambda/src/handler.test.ts b/packages/aws-lambda/src/handler.test.ts index bbd4784eca..34294bc7bd 100644 --- a/packages/aws-lambda/src/handler.test.ts +++ b/packages/aws-lambda/src/handler.test.ts @@ -40,7 +40,12 @@ import type { RenderChunkEvent, StitchPartsEvent, } from "./events.js"; -import { handler as handleEvent, stitchHelper, unwrapEvent } from "./handler.js"; +import { + handler as handleEvent, + stitchHelper, + unwrapEvent, + useBundledBinaries, +} from "./handler.js"; import { S3PlanV2ArtifactPublisher } from "./s3PlanV2Publisher.js"; interface FakeS3Op { @@ -258,6 +263,51 @@ describe("unwrapEvent", () => { }); }); +describe("useBundledBinaries", () => { + function taskRoot(...binaries: string[]): string { + const root = mkdtempSync(join(tmpdir(), "hf-lambda-task-")); + mkdirSync(join(root, "bin")); + for (const name of binaries) writeFileSync(join(root, "bin", name), ""); + return root; + } + + it("names the bundled ffmpeg and ffprobe by path, since the task root is the working directory", () => { + const root = taskRoot("ffmpeg", "ffprobe"); + const env: NodeJS.ProcessEnv = { PATH: "/usr/bin" }; + try { + useBundledBinaries(root, env); + } finally { + rmSync(root, { recursive: true, force: true }); + } + + expect(env).toEqual({ + PATH: `${join(root, "bin")}:/usr/bin`, + HYPERFRAMES_FFMPEG_PATH: join(root, "bin", "ffmpeg"), + HYPERFRAMES_FFPROBE_PATH: join(root, "bin", "ffprobe"), + }); + }); + + it("keeps an override already set and skips a binary the bundle lacks", () => { + const root = taskRoot("ffprobe"); + const env: NodeJS.ProcessEnv = { HYPERFRAMES_FFPROBE_PATH: "/opt/ffprobe" }; + try { + useBundledBinaries(root, env); + } finally { + rmSync(root, { recursive: true, force: true }); + } + + expect(env.HYPERFRAMES_FFPROBE_PATH).toBe("/opt/ffprobe"); + expect(env.HYPERFRAMES_FFMPEG_PATH).toBeUndefined(); + }); + + it("changes nothing without a bundled bin folder", () => { + const env: NodeJS.ProcessEnv = { PATH: "/usr/bin" }; + useBundledBinaries(join(tmpdir(), "hf-lambda-no-such-task"), env); + + expect(env).toEqual({ PATH: "/usr/bin" }); + }); +}); + describe("handler dispatch", () => { it("answers a warm event without touching S3 or the project", async () => { const s3 = new FakeS3Client(); diff --git a/packages/aws-lambda/src/handler.ts b/packages/aws-lambda/src/handler.ts index eb58e987ed..b221eab59e 100644 --- a/packages/aws-lambda/src/handler.ts +++ b/packages/aws-lambda/src/handler.ts @@ -322,20 +322,30 @@ function summarizeEvent( } } -/** - * Lambda sets `TMPDIR` to `/tmp` already, but the bundled binaries (Chrome - * + ffmpeg) live alongside the handler at `/var/task/bin/`. Add that to - * PATH the first time the handler runs so spawn("ffmpeg", …) inside the - * OSS primitives resolves to the bundled binary. - */ let runtimeEnvPrimed = false; function primeRuntimeEnv(): void { if (runtimeEnvPrimed) return; runtimeEnvPrimed = true; - const taskRoot = process.env.LAMBDA_TASK_ROOT ?? "/var/task"; + useBundledBinaries(process.env.LAMBDA_TASK_ROOT ?? "/var/task"); +} + +const BUNDLED_FF_BINARIES = [ + ["ffmpeg", "HYPERFRAMES_FFMPEG_PATH"], + ["ffprobe", "HYPERFRAMES_FFPROBE_PATH"], +] as const; + +/** + * The bundled binaries live in `/bin`. The task root is Lambda's working directory, + * which FFmpeg discovery never takes a program from, so ffmpeg and ffprobe are named by path. + * An override already set wins. + */ +export function useBundledBinaries(taskRoot: string, env: NodeJS.ProcessEnv = process.env): void { const bin = join(taskRoot, "bin"); - if (existsSync(bin)) { - process.env.PATH = `${bin}:${process.env.PATH ?? ""}`; + if (!existsSync(bin)) return; + env.PATH = `${bin}:${env.PATH ?? ""}`; + for (const [name, setting] of BUNDLED_FF_BINARIES) { + const binary = join(bin, name); + if (!env[setting]?.trim() && existsSync(binary)) env[setting] = binary; } } diff --git a/packages/cli/src/browser/manager.test.ts b/packages/cli/src/browser/manager.test.ts index bc52014694..1fc280abcd 100644 --- a/packages/cli/src/browser/manager.test.ts +++ b/packages/cli/src/browser/manager.test.ts @@ -31,7 +31,7 @@ import { writeFileSync, } from "node:fs"; import { tmpdir } from "node:os"; -import { basename, dirname, join, relative, sep } from "node:path"; +import { basename, delimiter, dirname, join, relative, sep } from "node:path"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { managedChromeVersion } from "./manager.js"; @@ -328,6 +328,7 @@ describe("findBrowser — cache resolution", () => { configurable: true, }); vi.restoreAllMocks(); + vi.unstubAllEnvs(); vi.doUnmock("node:fs"); vi.doUnmock("node:os"); vi.doUnmock("node:child_process"); @@ -355,29 +356,25 @@ describe("findBrowser — cache resolution", () => { expect(result).toEqual({ executablePath: HF_BINARY, source: "cache" }); }); - it("hides the Windows console used by the where lookup", async () => { + it("on Windows, skips a google-chrome.exe in the working directory and takes the PATH copy", async () => { Object.defineProperty(process, "platform", { value: "win32", configurable: true, }); - installFsMocks({ existing: new Set() }); + const project = join("/", "projects", "shared"); + const tools = join("/", "tools", "chrome"); + vi.spyOn(process, "cwd").mockReturnValue(project); + vi.stubEnv("PATH", [project, tools].join(delimiter)); + const existing = installFsMocks({ existing: new Set([join(project, "google-chrome.exe")]) }); installPuppeteerBrowsersMock(); - const execSync = vi.fn((command: string) => - command === "where google-chrome" ? "C:\\Chrome\\chrome.exe\n" : "", - ); - vi.doMock("node:child_process", () => ({ execSync, spawnSync: vi.fn() })); + const { findSystemBrowser } = await import("./manager.js"); - const { findBrowser } = await import("./manager.js"); - const result = await findBrowser(); - - expect(result).toEqual({ - executablePath: "C:\\Chrome\\chrome.exe", + expect(findSystemBrowser()).toBeUndefined(); + existing.add(join(tools, "google-chrome.exe")); + expect(findSystemBrowser()).toEqual({ + executablePath: join(tools, "google-chrome.exe"), source: "system", }); - expect(execSync).toHaveBeenCalledWith( - "where google-chrome", - expect.objectContaining({ windowsHide: true }), - ); }); it("finds Chrome in the standard Windows Program Files location", async () => { diff --git a/packages/cli/src/browser/manager.ts b/packages/cli/src/browser/manager.ts index 8dcd87ff1d..46541b4630 100644 --- a/packages/cli/src/browser/manager.ts +++ b/packages/cli/src/browser/manager.ts @@ -1,5 +1,5 @@ // fallow-ignore-file code-duplication -import { execSync, spawnSync } from "node:child_process"; +import { spawnSync } from "node:child_process"; import { randomUUID } from "node:crypto"; import { existsSync, @@ -14,6 +14,7 @@ import { } from "node:fs"; import { homedir } from "node:os"; import { basename, dirname, join, relative } from "node:path"; +import { findTrustedExecutable } from "@hyperframes/parsers/ff-binaries"; import { browserPathFromEnv, managedChromeVersion, @@ -286,25 +287,6 @@ const SYSTEM_CHROME_PATHS: ReadonlyArray = "/usr/bin/chromium-browser", ]; -function whichBinary(name: string): string | undefined { - try { - const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`; - const output = execSync(cmd, { - encoding: "utf-8", - stdio: ["pipe", "pipe", "pipe"], - timeout: 5000, - windowsHide: true, - }); - const first = output - .split(/\r?\n/) - .map((s) => s.trim()) - .find(Boolean); - return first || undefined; - } catch { - return undefined; - } -} - // A caller-supplied browser, named by HYPERFRAMES_BROWSER_PATH or PRODUCER_HEADLESS_SHELL_PATH (the engine's // and the deploy docs' name). check, snapshot and compare honour it as render does; which name wins is // browserPathFromEnv's, so the engine launches what this resolved. @@ -448,7 +430,7 @@ export function findSystemBrowser(): BrowserResult | undefined { } } - const fromWhich = whichBinary("google-chrome") ?? whichBinary("chromium"); + const fromWhich = findTrustedExecutable("google-chrome") ?? findTrustedExecutable("chromium"); if (fromWhich) { return { executablePath: fromWhich, source: "system" }; } diff --git a/packages/cli/src/commands/media-use.test.ts b/packages/cli/src/commands/media-use.test.ts index 2c44fea040..dc15b5e6f6 100644 --- a/packages/cli/src/commands/media-use.test.ts +++ b/packages/cli/src/commands/media-use.test.ts @@ -1,7 +1,8 @@ -import { describe, expect, it } from "vitest"; -import { mkdtempSync, rmSync } from "node:fs"; +import { describe, expect, it, onTestFinished, vi } from "vitest"; +import { spawnSync } from "node:child_process"; +import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; -import { join, resolve } from "node:path"; +import { delimiter, join, resolve } from "node:path"; import { createMediaUseCommand, MEDIA_USE_VERBS, @@ -25,6 +26,28 @@ describe("mediaUseEngineEnv", () => { expect(mediaUseEngineEnv({}, "src/cli.ts")).toEqual({}); expect(mediaUseEngineEnv({}, "")).toEqual({}); }); + + it.skipIf(process.platform === "win32")( + "gives the engine no PATH folder in the project, so a tool it runs by name is never the project's", + () => { + const project = realpathSync(mkdtempSync(join(tmpdir(), "hf-media-use-project-"))); + onTestFinished(() => rmSync(project, { recursive: true, force: true })); + const bin = join(project, "node_modules", ".bin"); + mkdirSync(bin, { recursive: true }); + const marker = join(project, "ran"); + writeFileSync(join(bin, "codex"), `#!/bin/sh\necho codex > "${marker}"\n`, { mode: 0o755 }); + vi.spyOn(process, "cwd").mockReturnValue(project); + onTestFinished(() => { + vi.restoreAllMocks(); + }); + + const env = mediaUseEngineEnv({ PATH: [bin, ".", "/usr/bin", "/bin"].join(delimiter) }, ""); + spawnSync("/bin/sh", ["-c", "codex --version"], { cwd: project, env, stdio: "ignore" }); + + expect(existsSync(marker)).toBe(false); + expect(env.PATH).toBe(["/usr/bin", "/bin"].join(delimiter)); + }, + ); }); describe("media-use command wiring", () => { diff --git a/packages/cli/src/commands/media-use.ts b/packages/cli/src/commands/media-use.ts index 1277604786..51a53f9c9f 100644 --- a/packages/cli/src/commands/media-use.ts +++ b/packages/cli/src/commands/media-use.ts @@ -1,10 +1,11 @@ import { defineCommand } from "../utils/defineCommand.js"; -import { dirname, join, resolve } from "node:path"; +import { delimiter, dirname, join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import { spawnSync } from "node:child_process"; import { existsSync } from "node:fs"; import { finishCommand } from "../utils/commandResult.js"; import { withMediaAuthEnvironment } from "../auth/media-environment.js"; +import { trustedPathDirs } from "@hyperframes/parsers/ff-binaries"; const MEDIA_USE_ARGS = { type: { type: "string", description: "What to find: bgm, sfx, image, icon, logo, voice" }, @@ -75,12 +76,19 @@ export function mediaUseVerbFlags(verb: MediaUseVerb): string[] { return verb === "resolve" ? [] : [`--${verb}`]; } +function withOnlyTrustedPathFolders(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv { + const pathKey = Object.keys(env).find((name) => name.toUpperCase() === "PATH"); + if (!pathKey) return env; + return { ...env, [pathKey]: trustedPathDirs(env[pathKey]).join(delimiter) }; +} + export function mediaUseEngineEnv( env: NodeJS.ProcessEnv, entry: string | undefined = process.argv[1], ): NodeJS.ProcessEnv { - if (!entry || /\.[cm]?ts$/.test(entry)) return env; - return { ...env, HYPERFRAMES_CLI_ENTRY: resolve(entry) }; + const scoped = withOnlyTrustedPathFolders(env); + if (!entry || /\.[cm]?ts$/.test(entry)) return scoped; + return { ...scoped, HYPERFRAMES_CLI_ENTRY: resolve(entry) }; } type InvokeMediaUse = (verb: MediaUseVerb) => never | Promise; diff --git a/packages/cli/src/tts/python.test.ts b/packages/cli/src/tts/python.test.ts index bfb2ba7a90..820b51989e 100644 --- a/packages/cli/src/tts/python.test.ts +++ b/packages/cli/src/tts/python.test.ts @@ -1,3 +1,6 @@ +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; // Regression coverage for a silent HYPERFRAMES_PYTHON override rejection: @@ -64,15 +67,43 @@ describe("findPython / describeRejectedPythonOverride", () => { it("findPython still falls back to the PATH probe when the override is rejected", () => { process.env.HYPERFRAMES_PYTHON = "/nonexistent/python"; + const bin = mkdtempSync(join(tmpdir(), "hf-python-path-")); + for (const file of ["python3", "python3.exe"]) + writeFileSync(join(bin, file), "", { mode: 0o755 }); + vi.stubEnv("PATH", bin); execFileSyncMock.mockImplementation((cmd: string, args: string[]) => { if (args[0] === "--version" && cmd === "/nonexistent/python") { throw new Error("ENOENT: no such file or directory"); } - if (cmd === "which" || cmd === "where") return "/usr/bin/python3\n"; + if (cmd === "which") return `${join(bin, "python3")}\n`; if (args[0] === "--version") return "Python 3.11.0"; throw new Error(`unexpected call: ${cmd} ${args.join(" ")}`); }); - expect(findPython()).toBe("/usr/bin/python3"); + try { + expect(findPython()).toBe( + join(bin, process.platform === "win32" ? "python3.exe" : "python3"), + ); + } finally { + vi.unstubAllEnvs(); + rmSync(bin, { recursive: true, force: true }); + } + }); + + it("findPython never runs a python that the lookup finds in the working directory", () => { + delete process.env.HYPERFRAMES_PYTHON; + vi.stubEnv("PATH", ""); + const planted = join(process.cwd(), "python3"); + execFileSyncMock.mockImplementation((cmd: string, args: string[]) => { + if (cmd === "which" || cmd === "where") return `${planted}\n`; + if (args[0] === "--version") return "Python 3.11.0"; + throw new Error(`unexpected call: ${cmd} ${args.join(" ")}`); + }); + try { + expect(findPython()).toBeUndefined(); + expect(execFileSyncMock.mock.calls.some(([cmd]) => cmd === planted)).toBe(false); + } finally { + vi.unstubAllEnvs(); + } }); it("findPython uses the override directly when it validates", () => { diff --git a/packages/cli/src/tts/python.ts b/packages/cli/src/tts/python.ts index 92b77b5576..91ea11e0b3 100644 --- a/packages/cli/src/tts/python.ts +++ b/packages/cli/src/tts/python.ts @@ -7,7 +7,7 @@ */ import { execFileSync } from "node:child_process"; -import { dirname, resolve } from "node:path"; +import { findTrustedExecutable } from "@hyperframes/parsers/ff-binaries"; type PythonOverrideValidation = { ok: true } | { ok: false; reason: string }; @@ -29,29 +29,13 @@ function validatePythonOverride(override: string): PythonOverrideValidation { } } -function inWorkingDirectory(candidate: string): boolean { - return ( - process.platform === "win32" && - dirname(resolve(candidate)).toLowerCase() === resolve(process.cwd()).toLowerCase() - ); -} - /** Locate a Python 3: `HYPERFRAMES_PYTHON` env override first, then PATH. */ export function findPython(): string | undefined { const override = process.env.HYPERFRAMES_PYTHON; if (override && validatePythonOverride(override).ok) return override; for (const name of ["python3", "python"]) { try { - const cmd = process.platform === "win32" ? "where" : "which"; - const output = execFileSync(cmd, [name], { - encoding: "utf-8", - stdio: ["pipe", "pipe", "pipe"], - timeout: 5000, - }); - const first = output - .split(/\r?\n/) - .map((s) => s.trim()) - .find((s) => s && !inWorkingDirectory(s)); + const first = findTrustedExecutable(name); if (!first) continue; // Verify it's Python 3 diff --git a/packages/cli/src/utils/clipboard.test.ts b/packages/cli/src/utils/clipboard.test.ts index 2cf2422269..a1d1b17ecc 100644 --- a/packages/cli/src/utils/clipboard.test.ts +++ b/packages/cli/src/utils/clipboard.test.ts @@ -1,7 +1,9 @@ import { beforeEach, describe, expect, it, vi } from "vitest"; const spawnSync = vi.hoisted(() => vi.fn()); +const findTrustedExecutable = vi.hoisted(() => vi.fn()); vi.mock("node:child_process", () => ({ spawnSync })); +vi.mock("@hyperframes/parsers/ff-binaries", () => ({ findTrustedExecutable })); vi.mock("node:os", async (orig) => ({ ...(await orig()), platform: () => "darwin", @@ -10,6 +12,8 @@ vi.mock("node:os", async (orig) => ({ describe("copyToClipboard", () => { beforeEach(() => { spawnSync.mockReset(); + findTrustedExecutable.mockReset(); + findTrustedExecutable.mockImplementation((name: string) => `/usr/bin/${name}`); vi.resetModules(); }); @@ -28,4 +32,21 @@ describe("copyToClipboard", () => { const { copyToClipboard } = await import("./clipboard.js"); expect(copyToClipboard("snippet")).toBe(false); }); + + it("runs the tool by the path the trusted lookup approved, never by name", async () => { + spawnSync.mockReturnValue({ status: 0 }); + const { copyToClipboard } = await import("./clipboard.js"); + + expect(copyToClipboard("snippet")).toBe(true); + expect(findTrustedExecutable).toHaveBeenCalledWith("pbcopy"); + expect(spawnSync.mock.calls.map(([command]) => command)).toEqual(["/usr/bin/pbcopy"]); + }); + + it("copies nothing when no trusted tool is installed", async () => { + findTrustedExecutable.mockReturnValue(undefined); + const { copyToClipboard } = await import("./clipboard.js"); + + expect(copyToClipboard("snippet")).toBe(false); + expect(spawnSync).not.toHaveBeenCalled(); + }); }); diff --git a/packages/cli/src/utils/clipboard.ts b/packages/cli/src/utils/clipboard.ts index 02cc2e839a..aa42bb5d99 100644 --- a/packages/cli/src/utils/clipboard.ts +++ b/packages/cli/src/utils/clipboard.ts @@ -8,6 +8,7 @@ import { spawnSync } from "node:child_process"; import { platform } from "node:os"; +import { findTrustedExecutable } from "@hyperframes/parsers/ff-binaries"; const COPY_TIMEOUT_MS = 5000; @@ -16,27 +17,25 @@ interface ClipboardProvider { args: string[]; } -function detectProvider(): ClipboardProvider | undefined { +function candidateProviders(): ClipboardProvider[] { const os = platform(); - if (os === "darwin") { - return { cmd: "pbcopy", args: [] }; - } - if (os === "win32") { - return { cmd: "clip.exe", args: [] }; - } - // Linux / BSD — pick the first tool that's on PATH. + if (os === "darwin") return [{ cmd: "pbcopy", args: [] }]; + if (os === "win32") return [{ cmd: "clip", args: [] }]; + // Linux / BSD — pick the first tool installed. // WSL exposes clip.exe too; prefer it so copies land in the Windows // clipboard where the user actually sees them. - const candidates: ClipboardProvider[] = [ + return [ { cmd: "clip.exe", args: [] }, { cmd: "wl-copy", args: [] }, { cmd: "xclip", args: ["-selection", "clipboard"] }, { cmd: "xsel", args: ["--clipboard", "--input"] }, ]; - const cmd = process.platform === "win32" ? "where" : "which"; - for (const p of candidates) { - const result = spawnSync(cmd, [p.cmd], { stdio: "ignore", windowsHide: true }); - if (result.status === 0) return p; +} + +function detectProvider(): ClipboardProvider | undefined { + for (const provider of candidateProviders()) { + const cmd = findTrustedExecutable(provider.cmd); + if (cmd) return { cmd, args: provider.args }; } return undefined; } diff --git a/packages/cli/src/utils/clipboard.windowsHide.test.ts b/packages/cli/src/utils/clipboard.windowsHide.test.ts index d49349eb76..0b32d8d70e 100644 --- a/packages/cli/src/utils/clipboard.windowsHide.test.ts +++ b/packages/cli/src/utils/clipboard.windowsHide.test.ts @@ -1,36 +1,34 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; -const { spawnSyncMock } = vi.hoisted(() => ({ spawnSyncMock: vi.fn() })); +const { spawnSyncMock, findTrustedExecutable } = vi.hoisted(() => ({ + spawnSyncMock: vi.fn(), + findTrustedExecutable: vi.fn(), +})); vi.mock("node:child_process", () => ({ spawnSync: spawnSyncMock })); -vi.mock("node:os", () => ({ platform: () => "linux" })); +vi.mock("@hyperframes/parsers/ff-binaries", () => ({ findTrustedExecutable })); +vi.mock("node:os", () => ({ platform: () => "win32" })); import { copyToClipboard } from "./clipboard.js"; describe("clipboard child-process options", () => { - const originalPlatform = process.platform; - beforeEach(() => { - // Exercise the `where`-based provider probe: os.platform() reports a - // non-Windows OS (so the candidate loop runs) while the probe itself - // resolves `where`, the branch taken on Windows. - Object.defineProperty(process, "platform", { value: "win32", configurable: true }); spawnSyncMock.mockReturnValue({ status: 0 }); + findTrustedExecutable.mockReturnValue("C:\\Windows\\System32\\clip.exe"); }); afterEach(() => { - Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true }); vi.clearAllMocks(); }); - it("hides console windows for provider probing and copying", () => { + it("copies with the trusted clip.exe and hides its console window", () => { expect(copyToClipboard("snippet")).toBe(true); - // One `where` probe plus the provider copy itself. - expect(spawnSyncMock.mock.calls.length).toBeGreaterThanOrEqual(2); - expect(spawnSyncMock.mock.calls[0]?.[0]).toBe("where"); - for (const call of spawnSyncMock.mock.calls) { - expect(call[2]).toEqual(expect.objectContaining({ windowsHide: true })); - } + expect(findTrustedExecutable).toHaveBeenCalledWith("clip"); + expect(spawnSyncMock.mock.calls).toHaveLength(1); + expect(spawnSyncMock.mock.calls[0]?.[0]).toBe("C:\\Windows\\System32\\clip.exe"); + expect(spawnSyncMock.mock.calls[0]?.[2]).toEqual( + expect.objectContaining({ windowsHide: true }), + ); }); }); diff --git a/packages/cli/src/whisper/manager.install.test.ts b/packages/cli/src/whisper/manager.install.test.ts index a3f9c6a5e3..f92a76c863 100644 --- a/packages/cli/src/whisper/manager.install.test.ts +++ b/packages/cli/src/whisper/manager.install.test.ts @@ -9,6 +9,9 @@ vi.mock("node:os", async (original) => ({ ...(await original()), platform: () => "darwin", })); +// Windows walks PATH itself, so there the lookup returns the real install's path, not `/bin/`. +const isTool = (command: string, name: string) => + new RegExp(`(^|[\\\\/])${name}(\\.exe)?$`, "i").test(command); afterEach(() => { vi.unstubAllEnvs(); calls.exec.mockReset(); @@ -30,8 +33,8 @@ it("never installs when the runtime vanishes after discovery and installation is WhisperUnavailableError, ); expect( - calls.exec.mock.calls.filter( - ([command]) => command === "brew" || command === "git" || command === "cmake", + calls.exec.mock.calls.filter(([command]) => + ["brew", "git", "cmake"].some((name) => isTool(command, name)), ), ).toEqual([]); } finally { @@ -50,12 +53,12 @@ it("clones whisper.cpp inside its build dir, with no cache path on the command l if (lookup && (args[0] === "brew" || args[0] === "whisper-cli")) throw new Error("not available"); if (lookup) return `/bin/${args[0]}\n`; - if (command === "git" && args[0] === "clone") throw new Error("stop after the clone"); + if (isTool(command, "git") && args[0] === "clone") throw new Error("stop after the clone"); return ""; }); try { await expect(ensure()).rejects.toBeInstanceOf(Unavailable); - const clone = calls.exec.mock.calls.find(([c, a]) => c === "git" && a[0] === "clone"); + const clone = calls.exec.mock.calls.find(([c, a]) => isTool(c, "git") && a[0] === "clone"); const [, args, options] = clone as [string, string[], { cwd?: string }]; expect(args.some((arg) => arg.includes(cache))).toBe(false); expect(options.cwd).toBe(join(cache, "whisper", "whisper.cpp")); @@ -74,21 +77,49 @@ it("builds only the reviewed whisper.cpp commit", async () => { if (lookup && (args[0] === "brew" || args[0] === "whisper-cli")) throw new Error("not available"); if (lookup) return `/bin/${args[0]}\n`; - if (command === "git" && args[0] === "rev-parse") return "0123456789abcdef\n"; + if (isTool(command, "git") && args[0] === "rev-parse") return "0123456789abcdef\n"; return ""; }); try { await expect(ensure()).rejects.toThrow(); - const clone = calls.exec.mock.calls.find(([c, a]) => c === "git" && a[0] === "clone"); + const clone = calls.exec.mock.calls.find(([c, a]) => isTool(c, "git") && a[0] === "clone"); expect((clone as [string, string[]])[1]).toEqual(expect.arrayContaining(["--branch"])); - expect(calls.exec.mock.calls.some(([command]) => command === "cmake")).toBe(false); + expect(calls.exec.mock.calls.some(([command]) => isTool(command, "cmake"))).toBe(false); } finally { rmSync(cache, { recursive: true, force: true }); } }); +it.skipIf(process.platform === "win32")( + "installs with the brew the trusted lookup approved, by its path", + async () => { + const cache = mkdtempSync(join(tmpdir(), "hf-whisper-cache-")); + vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache); + vi.stubEnv("HYPERFRAMES_WHISPER_PATH", ""); + vi.resetModules(); + const { ensureWhisper: ensure } = await import("./manager.js"); + calls.exec.mockImplementation((command: string, args: string[]) => { + const lookup = command === "which" || command === "where"; + if (lookup && args[0] === "brew") return "/opt/homebrew/bin/brew\n"; + throw new Error("not available"); + }); + try { + await expect(ensure()).rejects.toThrow(); + const runs = calls.exec.mock.calls.map(([command]) => command as string); + expect(runs).toContain("/opt/homebrew/bin/brew"); + expect(runs).not.toContain("brew"); + } finally { + rmSync(cache, { recursive: true, force: true }); + } + }, +); + it("names the missing build tool when whisper.cpp cannot be built", async () => { vi.stubEnv("HYPERFRAMES_CACHE_DIR", mkdtempSync(join(tmpdir(), "hf-whisper-cache-"))); + // Windows walks PATH itself, so PATH holds only git there. + const bin = mkdtempSync(join(tmpdir(), "hf-whisper-path-")); + writeFileSync(join(bin, "git.exe"), ""); + vi.stubEnv("PATH", bin); vi.resetModules(); const { ensureWhisper: ensure } = await import("./manager.js"); calls.exec.mockImplementation((command: string, args: string[]) => { diff --git a/packages/cli/src/whisper/manager.ts b/packages/cli/src/whisper/manager.ts index 1aea96f64c..7480a8cab7 100644 --- a/packages/cli/src/whisper/manager.ts +++ b/packages/cli/src/whisper/manager.ts @@ -9,6 +9,7 @@ import { downloadFile } from "../utils/download.js"; import { stoppableExecFile } from "../utils/stoppableExecFile.js"; import { verifies, type ModelFile } from "./modelFile.js"; import { hyperframesCacheDir } from "@hyperframes/core/cache-dir"; +import { findTrustedExecutable } from "@hyperframes/parsers/ff-binaries"; const MODELS_DIR = hyperframesCacheDir("whisper", "models"); const DEFAULT_MODEL = "small.en"; @@ -103,24 +104,6 @@ export function pinnedWhisperModel(model: string): ModelFile | undefined { // --- Find helpers ----------------------------------------------------------- -function whichBinary(name: string): string | undefined { - try { - const cmd = process.platform === "win32" ? "where" : "which"; - const output = execFileSync(cmd, [name], { - encoding: "utf-8", - stdio: ["pipe", "pipe", "pipe"], - timeout: 5000, - }); - const first = output - .split(/\r?\n/) - .map((s) => s.trim()) - .find(Boolean); - return first || undefined; - } catch { - return undefined; - } -} - function findFromEnv(): WhisperResult | undefined { const envPath = process.env["HYPERFRAMES_WHISPER_PATH"]; if (envPath && existsSync(envPath)) { @@ -131,7 +114,7 @@ function findFromEnv(): WhisperResult | undefined { function findFromSystem(): WhisperResult | undefined { // `whisper` is the OpenAI Python CLI; only whisper.cpp's binary accepts our flags. - const path = whichBinary("whisper-cli"); + const path = findTrustedExecutable("whisper-cli"); if (path) return { executablePath: path, source: "system" }; // Check brew paths directly on macOS @@ -152,8 +135,8 @@ const WHISPER_REPO = "https://github.com/ggml-org/whisper.cpp.git"; const WHISPER_TAG = "v1.9.5"; const WHISPER_COMMIT = "d1be6fde11ac6e0407606b4e42fe72d34add8037"; -function assertPinnedCheckout(): void { - const head = execFileSync("git", ["rev-parse", "HEAD"], { +function assertPinnedCheckout(git: string): void { + const head = execFileSync(git, ["rev-parse", "HEAD"], { cwd: BUILD_DIR, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], @@ -180,6 +163,7 @@ function findBuiltBinary(): WhisperResult | undefined { } async function buildFromSource( + { git, cmake }: BuildTools, onProgress?: (msg: string) => void, signal?: AbortSignal, ): Promise { @@ -192,7 +176,7 @@ async function buildFromSource( onProgress?.("Downloading whisper.cpp..."); mkdirSync(BUILD_DIR, { recursive: true }); await stoppableExecFile( - "git", + git, ["clone", "--depth", "1", "--branch", WHISPER_TAG, WHISPER_REPO, "."], { cwd: BUILD_DIR, @@ -202,18 +186,18 @@ async function buildFromSource( signal, }, ); - assertPinnedCheckout(); + assertPinnedCheckout(git); } onProgress?.("Building whisper.cpp (this may take a minute)..."); try { - await stoppableExecFile("cmake", ["-B", "build"], { + await stoppableExecFile(cmake, ["-B", "build"], { cwd: BUILD_DIR, stdio: ["pipe", "pipe", "pipe"], timeout: 120_000, signal, }); - await stoppableExecFile("cmake", ["--build", "build", "--config", "Release", "-j"], { + await stoppableExecFile(cmake, ["--build", "build", "--config", "Release", "-j"], { cwd: BUILD_DIR, stdio: ["pipe", "pipe", "pipe"], timeout: 300_000, @@ -267,17 +251,14 @@ export function getInstallInstructions(): string { return "See https://github.com/ggml-org/whisper.cpp#building"; } -function hasBrew(): boolean { - return whichBinary("brew") !== undefined; +interface BuildTools { + git: string; + cmake: string; } -function hasGit(): boolean { - const git = whichBinary("git"); - return git !== undefined && runsWithoutInstallPrompt(git); -} - -function hasCmake(): boolean { - return whichBinary("cmake") !== undefined; +function trustedGit(): string | undefined { + const git = findTrustedExecutable("git"); + return git !== undefined && runsWithoutInstallPrompt(git) ? git : undefined; } export async function ensureWhisper(options?: { @@ -301,10 +282,11 @@ export async function ensureWhisper(options?: { const why = (err: unknown) => (err instanceof Error ? err.message : String(err)).trim(); // 2. Try brew (macOS, fastest — pre-built bottle) - if (platform() === "darwin" && hasBrew()) { + const brew = platform() === "darwin" ? findTrustedExecutable("brew") : undefined; + if (brew) { options?.onProgress?.("Installing whisper-cpp via Homebrew..."); try { - await stoppableExecFile("brew", ["install", "whisper-cpp"], { + await stoppableExecFile(brew, ["install", "whisper-cpp"], { stdio: "ignore", timeout: 300_000, signal, @@ -318,15 +300,17 @@ export async function ensureWhisper(options?: { } // 3. Build from source (needs git + cmake + C compiler) - if (hasGit() && hasCmake() && runsWithoutInstallPrompt("cc")) { + const git = trustedGit(); + const cmake = findTrustedExecutable("cmake"); + if (git && cmake && runsWithoutInstallPrompt("cc")) { try { - return await buildFromSource(options?.onProgress, signal); + return await buildFromSource({ git, cmake }, options?.onProgress, signal); } catch (err) { causes.push(why(err)); } signal?.throwIfAborted(); } else { - const missing = [!hasGit() && "git", !hasCmake() && "cmake"].filter(Boolean).join(" and "); + const missing = [!git && "git", !cmake && "cmake"].filter(Boolean).join(" and "); causes.push(`cannot build whisper.cpp: ${missing} not found on PATH`); } diff --git a/packages/cli/src/whisper/parakeet.ts b/packages/cli/src/whisper/parakeet.ts index 96ce6c8b22..66e43569a4 100644 --- a/packages/cli/src/whisper/parakeet.ts +++ b/packages/cli/src/whisper/parakeet.ts @@ -14,6 +14,7 @@ */ import { execFileSync } from "node:child_process"; +import { findTrustedExecutable } from "@hyperframes/parsers/ff-binaries"; import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { homedir, tmpdir } from "node:os"; import { basename, extname, join } from "node:path"; @@ -66,22 +67,8 @@ export function findParakeet(): string | undefined { for (const path of candidates) { if (existsSync(path) && isRunnable(path)) return path; } - try { - const which = process.platform === "win32" ? "where" : "which"; - const out = execFileSync(which, ["parakeet-mlx"], { - encoding: "utf-8", - stdio: ["ignore", "pipe", "ignore"], - timeout: 5000, - }); - const first = out - .split(/\r?\n/) - .map((s) => s.trim()) - .find(Boolean); - if (first && existsSync(first)) return first; - } catch { - // not on PATH - } - return undefined; + const onPath = findTrustedExecutable("parakeet-mlx"); + return onPath && existsSync(onPath) ? onPath : undefined; } interface ParakeetToken { diff --git a/packages/cli/src/whisper/trustedLookup.test.ts b/packages/cli/src/whisper/trustedLookup.test.ts new file mode 100644 index 0000000000..a75f81f7d6 --- /dev/null +++ b/packages/cli/src/whisper/trustedLookup.test.ts @@ -0,0 +1,46 @@ +import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { delimiter, join } from "node:path"; +import { afterEach, expect, it, onTestFinished, vi } from "vitest"; + +const originalPlatform = process.platform; + +afterEach(() => { + Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true }); + vi.restoreAllMocks(); + vi.unstubAllEnvs(); +}); + +function folderWith(prefix: string, files: string[]): string { + const dir = realpathSync(mkdtempSync(join(tmpdir(), prefix))); + for (const file of files) writeFileSync(join(dir, file), ""); + onTestFinished(() => rmSync(dir, { recursive: true, force: true })); + return dir; +} + +// Windows lists the working directory before PATH; a same-named file in the project must lose. +it("on Windows, never takes whisper-cli or parakeet-mlx from the working directory", async () => { + const project = folderWith("hf-trusted-project-", ["whisper-cli.exe", "parakeet-mlx.exe"]); + const tools = folderWith("hf-trusted-tools-", ["whisper-cli.exe", "parakeet-mlx.exe"]); + vi.stubEnv("HYPERFRAMES_CACHE_DIR", folderWith("hf-trusted-cache-", [])); + vi.stubEnv("HYPERFRAMES_WHISPER_PATH", ""); + vi.stubEnv("HYPERFRAMES_PARAKEET", ""); + vi.stubEnv("HOME", folderWith("hf-trusted-home-", [])); + vi.stubEnv("USERPROFILE", process.env.HOME ?? ""); + vi.spyOn(process, "cwd").mockReturnValue(project); + vi.resetModules(); + const { findWhisper } = await import("./manager.js"); + const { findParakeet } = await import("./parakeet.js"); + Object.defineProperty(process, "platform", { value: "win32", configurable: true }); + + vi.stubEnv("PATH", [project, ".", ""].join(delimiter)); + expect(findWhisper()).toBeUndefined(); + expect(findParakeet()).toBeUndefined(); + + vi.stubEnv("PATH", [project, tools].join(delimiter)); + expect(findWhisper()).toEqual({ + executablePath: join(tools, "whisper-cli.exe"), + source: "system", + }); + expect(findParakeet()).toBe(join(tools, "parakeet-mlx.exe")); +}); diff --git a/packages/engine/src/services/videoFrameExtractor.hdr.test.ts b/packages/engine/src/services/videoFrameExtractor.hdr.test.ts index 01d2b48ba0..59596c534a 100644 --- a/packages/engine/src/services/videoFrameExtractor.hdr.test.ts +++ b/packages/engine/src/services/videoFrameExtractor.hdr.test.ts @@ -10,6 +10,7 @@ import { type ExtractionResult, } from "./videoFrameExtractor.js"; import { extractVideoMetadata } from "../utils/ffprobe.js"; +import { getFfmpegBinary, getFfprobeBinary } from "../utils/ffmpegBinaries.js"; import { runFfmpeg } from "../utils/runFfmpeg.js"; import { SCHEMA_PREFIX } from "./extractionCache.js"; @@ -577,6 +578,9 @@ describe.skipIf(!HAS_ZSCALE)("forced-SDR HDR extraction", () => { expect(zscale.errors).toEqual([]); const realPlatform = process.platform; + // The fresh modules look FFmpeg up as macOS would, which cannot walk a Windows PATH. + vi.stubEnv("HYPERFRAMES_FFMPEG_PATH", getFfmpegBinary()); + vi.stubEnv("HYPERFRAMES_FFPROBE_PATH", getFfprobeBinary()); vi.resetModules(); vi.doMock("../utils/psnrFilterAvailability.js", () => ({ isFfmpegFilterAvailable: async () => false, @@ -604,6 +608,7 @@ describe.skipIf(!HAS_ZSCALE)("forced-SDR HDR extraction", () => { } finally { stderr.mockRestore(); Object.defineProperty(process, "platform", platform); + vi.unstubAllEnvs(); vi.doUnmock("../utils/psnrFilterAvailability.js"); vi.resetModules(); } diff --git a/packages/engine/src/utils/ffmpegBinaries.test.ts b/packages/engine/src/utils/ffmpegBinaries.test.ts index 5388e50432..dad0c98146 100644 --- a/packages/engine/src/utils/ffmpegBinaries.test.ts +++ b/packages/engine/src/utils/ffmpegBinaries.test.ts @@ -1,5 +1,7 @@ -import { resolve } from "node:path"; -import { afterEach, describe, expect, it, vi } from "vitest"; +import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { delimiter, join, resolve } from "node:path"; +import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest"; import { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, @@ -14,6 +16,7 @@ describe("ffmpeg binary env resolution", () => { afterEach(() => { vi.resetModules(); vi.doUnmock("child_process"); + vi.doUnmock("@hyperframes/parsers/ff-binaries"); if (originalFfmpegPath === undefined) delete process.env.HYPERFRAMES_FFMPEG_PATH; else process.env.HYPERFRAMES_FFMPEG_PATH = originalFfmpegPath; if (originalFfprobePath === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH; @@ -50,4 +53,58 @@ describe("ffmpeg binary env resolution", () => { expect(() => assertConfiguredFfmpegBinariesExist()).toThrow(/replacement character|mangled/i); }); + + describe.skipIf(process.platform === "win32")("with no trusted FFmpeg installed", () => { + // A project's node_modules/.bin on PATH, as `npm run` and `npx` set it, holding planted tools. + function plantTools(...names: string[]): { marker: string } { + const project = realpathSync(mkdtempSync(join(tmpdir(), "hf-ff-planted-"))); + onTestFinished(() => rmSync(project, { recursive: true, force: true })); + const bin = join(project, "node_modules", ".bin"); + mkdirSync(bin, { recursive: true }); + const marker = join(project, "ran"); + for (const name of names) { + writeFileSync(join(bin, name), `#!/bin/sh\necho ${name} >> "${marker}"\n`, { mode: 0o755 }); + } + delete process.env.HYPERFRAMES_FFMPEG_PATH; + delete process.env.HYPERFRAMES_FFPROBE_PATH; + process.env.PATH = `${bin}${delimiter}${originalPath ?? ""}`; + vi.resetModules(); + vi.doMock("@hyperframes/parsers/ff-binaries", async (importOriginal) => { + const actual = await importOriginal(); + return { ...actual, findFfBinary: () => undefined }; + }); + return { marker }; + } + + it("reports ffmpeg as missing instead of running the one PATH finds by name", async () => { + const { marker } = plantTools("ffmpeg"); + const { runFfmpeg } = await import("./runFfmpeg.js"); + const { getFfmpegBinary: binary } = await import("./ffmpegBinaries.js"); + expect(binary()).toMatch(/ffmpeg-not-found-set-HYPERFRAMES_FFMPEG_PATH[\\/]ffmpeg$/); + + const result = await runFfmpeg(["-version"]); + + expect(existsSync(marker)).toBe(false); + expect(result).toMatchObject({ success: false, terminationReason: "spawn_error" }); + expect(result.error).toMatchObject({ code: "ENOENT" }); + }); + + it("finds no GPU encoder rather than failing the probe", async () => { + const { marker } = plantTools("ffmpeg"); + const { detectGpuEncoder } = await import("./gpuEncoder.js"); + + await expect(detectGpuEncoder()).resolves.toBeNull(); + expect(existsSync(marker)).toBe(false); + }); + + it("fails a probe with the install hint instead of running the ffprobe PATH finds", async () => { + const { marker } = plantTools("ffprobe"); + const { runFfprobe } = await import("./ffprobe.js"); + + await expect(runFfprobe("/no/such/clip.mp4", ["-show_format"])).rejects.toThrow( + /ffprobe not found/, + ); + expect(existsSync(marker)).toBe(false); + }); + }); }); diff --git a/packages/engine/src/utils/ffmpegBinaries.ts b/packages/engine/src/utils/ffmpegBinaries.ts index 702f0a591d..7f98de761f 100644 --- a/packages/engine/src/utils/ffmpegBinaries.ts +++ b/packages/engine/src/utils/ffmpegBinaries.ts @@ -1,17 +1,23 @@ import { existsSync } from "fs"; +import { dirname, join } from "path"; +import { fileURLToPath } from "url"; import { FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, findFfBinary } from "@hyperframes/parsers/ff-binaries"; export { FFMPEG_PATH_ENV, FFPROBE_PATH_ENV }; -// The engine hands spawn a bare binary name as the last resort so the spawn -// error names what the user must install; a configured-but-missing override -// is surfaced separately by assertConfiguredFfmpegBinariesExist below. +// With no trusted copy, an absolute path in HyperFrames' own install that is never created: spawning it +// fails with ENOENT as a missing binary always has, so callers degrade as before, and the OS never +// searches PATH or the working directory for the bare name. The folder name carries the install hint. +function notFound(name: "ffmpeg" | "ffprobe", setting: string): string { + return join(dirname(fileURLToPath(import.meta.url)), `${name}-not-found-set-${setting}`, name); +} + export function getFfmpegBinary(): string { - return findFfBinary("ffmpeg") ?? "ffmpeg"; + return findFfBinary("ffmpeg") ?? notFound("ffmpeg", FFMPEG_PATH_ENV); } export function getFfprobeBinary(): string { - return findFfBinary("ffprobe") ?? "ffprobe"; + return findFfBinary("ffprobe") ?? notFound("ffprobe", FFPROBE_PATH_ENV); } export function assertConfiguredFfmpegBinariesExist(): void { diff --git a/packages/parsers/src/ffBinaries.test.ts b/packages/parsers/src/ffBinaries.test.ts index a12a6a0077..3de881cea7 100644 --- a/packages/parsers/src/ffBinaries.test.ts +++ b/packages/parsers/src/ffBinaries.test.ts @@ -9,7 +9,7 @@ import { writeFileSync, } from "node:fs"; import { tmpdir } from "node:os"; -import { join, resolve } from "node:path"; +import { delimiter, join, resolve } from "node:path"; import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest"; type FfBinariesModule = typeof import("./ffBinaries.js"); @@ -177,38 +177,6 @@ describe("findFfBinary", () => { expect(findFfBinary("ffmpeg")).toBe(resolve("/opt/homebrew/bin/ffmpeg")); }); - it("falls back to the project-local .hyperframes bin", async () => { - delete process.env.HYPERFRAMES_FFMPEG_PATH; - process.env.PATH = ""; - const projectBinary = resolve( - ".hyperframes", - "bin", - process.platform === "win32" ? "ffmpeg.exe" : "ffmpeg", - ); - vi.resetModules(); - vi.doMock("node:child_process", () => { - const mocked = { - execFileSync: () => { - throw new Error("not found"); - }, - }; - return { ...mocked, default: mocked }; - }); - vi.doMock("node:fs", () => { - const mocked = { - existsSync: (candidate: unknown) => candidate === projectBinary, - accessSync: () => { - throw new Error("not executable"); - }, - constants: { X_OK: 1 }, - }; - return { ...mocked, default: mocked }; - }); - const { findFfBinary } = await importFresh(); - - expect(findFfBinary("ffmpeg")).toBe(projectBinary); - }); - function installerProject( name: "ffmpeg" | "ffprobe", { viaInstaller = false, mode = 0o755, content = "" as string | Buffer } = {}, @@ -242,24 +210,30 @@ describe("findFfBinary", () => { async function findInProjectDir( project: string, name: "ffmpeg" | "ffprobe", - systemBinaries: string[] = [], + { + systemBinaries = [], + pathDirs = [], + which, + }: { systemBinaries?: string[]; pathDirs?: string[]; which?: string } = {}, ) { skipped = {}; vi.stubEnv("HYPERFRAMES_FFMPEG_PATH", ""); vi.stubEnv("HYPERFRAMES_FFPROBE_PATH", ""); - process.env.PATH = ""; + process.env.PATH = pathDirs.join(delimiter); vi.spyOn(process, "cwd").mockReturnValue(project); vi.resetModules(); vi.doMock("node:fs", async (importOriginal) => { const actual = await importOriginal(); const existsSync = (candidate: PathLike) => systemBinaries.includes(String(candidate)) || - (String(candidate).startsWith(project) && actual.existsSync(candidate)); + ([project, ...pathDirs].some((dir) => String(candidate).startsWith(dir)) && + actual.existsSync(candidate)); return { ...actual, existsSync, default: { ...actual, existsSync } }; }); vi.doMock("node:child_process", () => { const mocked = { execFileSync: () => { + if (which) return `${which}\n`; throw new Error("not found"); }, }; @@ -276,19 +250,68 @@ describe("findFfBinary", () => { } } - it.each(["ffmpeg", "ffprobe"] as const)( - "falls back to the project's @%s-installer package", - async (name) => { - const { project, binary } = installerProject(name); + function binDir(prefix: string, name: "ffmpeg" | "ffprobe", content: string | Buffer = "") { + const dir = realpathSync(mkdtempSync(join(tmpdir(), prefix))); + const binary = join(dir, process.platform === "win32" ? `${name}.exe` : name); + writeFileSync(binary, content); + chmodSync(binary, 0o755); + onTestFinished(() => rmSync(dir, { recursive: true, force: true })); + return { dir, binary }; + } - expect(await findInProjectDir(project, name)).toBe(binary); + it.each(["ffmpeg", "ffprobe"] as const)( + "never runs a %s from the project's installer package or .hyperframes/bin", + async (name) => { + const { project } = installerProject(name); + mkdirSync(join(project, ".hyperframes", "bin"), { recursive: true }); + const local = join(project, ".hyperframes", "bin", name); + writeFileSync(local, ""); + chmodSync(local, 0o755); + + expect(await findInProjectDir(project, name)).toBeUndefined(); }, ); - it("finds the platform package next to the installer package (pnpm layout)", async () => { - const { project, binary } = installerProject("ffprobe", { viaInstaller: true }); + it("never runs an installer binary in the project's pnpm layout", async () => { + const { project } = installerProject("ffprobe", { viaInstaller: true }); - expect(await findInProjectDir(project, "ffprobe")).toBe(binary); + expect(await findInProjectDir(project, "ffprobe")).toBeUndefined(); + }); + + it("skips a project ffmpeg that `which` finds on PATH and takes the install dir's copy", async () => { + const { dir: project, binary: planted } = binDir("hf-ff-project-", "ffmpeg"); + const { dir: tools, binary: installed } = binDir("hf-ff-tools-", "ffmpeg"); + + expect( + await findInProjectDir(project, "ffmpeg", { pathDirs: [project, tools], which: planted }), + ).toBe(installed); + }); + + it("finds no ffmpeg when the only copy is in the project, even with the project on PATH", async () => { + const { dir: project, binary: planted } = binDir("hf-ff-project-", "ffmpeg"); + mkdirSync(join(project, "bin")); + writeFileSync(join(project, "bin", "ffmpeg"), ""); + chmodSync(join(project, "bin", "ffmpeg"), 0o755); + + expect( + await findInProjectDir(project, "ffmpeg", { + pathDirs: [project, join(project, "bin"), ".", "bin"], + which: planted, + }), + ).toBeUndefined(); + }); + + it("on Windows, skips an ffmpeg.exe in the working directory and takes the PATH copy", async () => { + const project = realpathSync(mkdtempSync(join(tmpdir(), "hf-ff-project-"))); + writeFileSync(join(project, "ffmpeg.exe"), ""); + const tools = realpathSync(mkdtempSync(join(tmpdir(), "hf-ff-tools-"))); + writeFileSync(join(tools, "ffmpeg.exe"), ""); + onTestFinished(() => rmSync(tools, { recursive: true, force: true })); + Object.defineProperty(process, "platform", { value: "win32", configurable: true }); + + expect(await findInProjectDir(project, "ffmpeg", { pathDirs: [project, tools] })).toBe( + join(tools, "ffmpeg.exe"), + ); }); it.skipIf(process.platform === "win32")( @@ -296,18 +319,9 @@ describe("findFfBinary", () => { async () => { const { project } = installerProject("ffprobe"); - expect(await findInProjectDir(project, "ffprobe", ["/usr/bin/ffprobe"])).toBe( - "/usr/bin/ffprobe", - ); - }, - ); - - it.skipIf(process.platform === "win32")( - "skips an installer binary that is not executable", - async () => { - const { project } = installerProject("ffprobe", { mode: 0o644 }); - - expect(await findInProjectDir(project, "ffprobe")).toBeUndefined(); + expect( + await findInProjectDir(project, "ffprobe", { systemBinaries: ["/usr/bin/ffprobe"] }), + ).toBe("/usr/bin/ffprobe"); }, ); @@ -319,42 +333,23 @@ describe("findFfBinary", () => { vi.spyOn(process, "arch", "get").mockReturnValue("arm64"); } - it("skips an x86_64 installer binary", async () => { + it("skips an x86_64 binary on PATH and names it under its own name only", async () => { asAppleSilicon(); - const { project } = installerProject("ffprobe", { content: machO(0x07) }); - - expect(await findInProjectDir(project, "ffprobe")).toBeUndefined(); - }); - - it("names the skipped binary under its own name only", async () => { - asAppleSilicon(); - const { project, binary } = installerProject("ffprobe", { content: machO(0x07) }); - - await findInProjectDir(project, "ffprobe"); + const { dir, binary } = binDir("hf-ff-x86-", "ffprobe", machO(0x07)); + const project = mkdtempSync(join(tmpdir(), "hf-ff-cwd-")); + expect(await findInProjectDir(project, "ffprobe", { pathDirs: [dir] })).toBeUndefined(); expect(skipped).toEqual({ ffprobe: binary }); }); - it("skips an x86_64 binary in the project's .hyperframes/bin", async () => { + it("keeps an arm64 binary on PATH", async () => { asAppleSilicon(); - const project = realpathSync(mkdtempSync(join(tmpdir(), "hf-ff-local-"))); - mkdirSync(join(project, ".hyperframes", "bin"), { recursive: true }); - const binary = join(project, ".hyperframes", "bin", "ffprobe"); - writeFileSync(binary, machO(0x07)); - chmodSync(binary, 0o755); + const { dir, binary } = binDir("hf-ff-arm-", "ffprobe", machO(0x0c)); + const project = mkdtempSync(join(tmpdir(), "hf-ff-cwd-")); - expect(await findInProjectDir(project, "ffprobe")).toBeUndefined(); - expect(skipped.ffprobe).toBe(binary); - }); - - it("keeps an arm64 installer binary", async () => { - asAppleSilicon(); - const { project, binary } = installerProject("ffprobe", { content: machO(0x0c) }); - - expect(await findInProjectDir(project, "ffprobe")).toBe(binary); + expect(await findInProjectDir(project, "ffprobe", { pathDirs: [dir] })).toBe(binary); }); }); - it("returns undefined when the binary is nowhere, and caches the miss until cleared", async () => { delete process.env.HYPERFRAMES_FFMPEG_PATH; Object.defineProperty(process, "platform", { value: "linux", configurable: true }); @@ -385,6 +380,37 @@ describe("findFfBinary", () => { expect(execFileSync).toHaveBeenCalledTimes(2); }); + it("requireFfBinary throws an ENOENT naming the override instead of returning a bare name", async () => { + delete process.env.HYPERFRAMES_FFMPEG_PATH; + Object.defineProperty(process, "platform", { value: "linux", configurable: true }); + process.env.PATH = ""; + vi.resetModules(); + const execFileSync = vi.fn(() => { + throw new Error("not found"); + }); + vi.doMock("node:child_process", () => ({ execFileSync, default: { execFileSync } })); + vi.doMock("node:fs", () => { + const mocked = { + existsSync: () => false, + accessSync: () => { + throw new Error("not executable"); + }, + constants: { X_OK: 1 }, + }; + return { ...mocked, default: mocked }; + }); + const { requireFfBinary } = await importFresh(); + + expect(() => requireFfBinary("ffmpeg")).toThrow( + expect.objectContaining({ + code: "ENOENT", + message: expect.stringMatching(/HYPERFRAMES_FFMPEG_PATH/), + }), + ); + process.env.HYPERFRAMES_FFMPEG_PATH = "/tools/ffmpeg"; + expect(requireFfBinary("ffmpeg")).toBe(resolve("/tools/ffmpeg")); + }); + it("finds a binary installed in a common dir shortly after an earlier miss, then caches the hit", async () => { vi.useFakeTimers(); onTestFinished(() => { diff --git a/packages/parsers/src/ffBinaries.ts b/packages/parsers/src/ffBinaries.ts index e72df7e742..8401b19a63 100644 --- a/packages/parsers/src/ffBinaries.ts +++ b/packages/parsers/src/ffBinaries.ts @@ -1,7 +1,8 @@ import { execFileSync } from "node:child_process"; import { accessSync, closeSync, constants, existsSync, openSync, readSync } from "node:fs"; import { createRequire } from "node:module"; -import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path"; +import { basename, dirname, join, resolve } from "node:path"; +import { isTrustedExecutablePath, trustedPathDirs } from "./trustedExecutable.js"; /** * Shared FFmpeg/FFprobe binary resolution for every package that shells out @@ -9,6 +10,13 @@ import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:pa * `@hyperframes/parsers/ff-binaries` subpath, never from a browser bundle. */ +export { + findTrustedExecutable, + isTrustedDirectory, + isTrustedExecutablePath, + trustedPathDirs, +} from "./trustedExecutable.js"; + export const FFMPEG_PATH_ENV = "HYPERFRAMES_FFMPEG_PATH"; export const FFPROBE_PATH_ENV = "HYPERFRAMES_FFPROBE_PATH"; @@ -90,9 +98,7 @@ function isExecutablePathCandidate(candidate: string): boolean { } function scanPath(name: FfBinaryName): string | undefined { - const pathValue = process.env.PATH; - // Only absolute PATH entries: the working directory is project content, not an install location. - const searchDirs = (pathValue ? pathValue.split(delimiter) : []).filter((dir) => isAbsolute(dir)); + const searchDirs = trustedPathDirs(); if (searchDirs.length === 0) return undefined; const extensions = @@ -109,7 +115,7 @@ function scanPath(name: FfBinaryName): string | undefined { ] : [""]; const candidates: string[] = []; - for (const dir of new Set(searchDirs)) { + for (const dir of searchDirs) { for (const ext of extensions) { const candidate = join(dir, `${name}${ext}`); if (isExecutablePathCandidate(candidate)) candidates.push(candidate); @@ -131,7 +137,9 @@ const COMMON_BIN_DIRS = function findInCommonDirsOrInstallerPackage(name: FfBinaryName): string | undefined { for (const dir of COMMON_BIN_DIRS) { const candidate = `${dir}/${name}`; - if (existsSync(candidate) && runsOnThisMac(candidate)) return candidate; + if (isTrustedExecutablePath(candidate) && existsSync(candidate) && runsOnThisMac(candidate)) { + return candidate; + } } return findInInstallerPackage(name); } @@ -140,11 +148,6 @@ function binaryFileName(name: FfBinaryName): string { return process.platform === "win32" ? `${name}.exe` : name; } -function findInProjectLocalBin(name: FfBinaryName): string | undefined { - const candidate = resolve(".hyperframes", "bin", binaryFileName(name)); - return existsSync(candidate) && runsOnThisMac(candidate) ? candidate : undefined; -} - function tryResolve(fromFile: string, request: string): string | undefined { try { return createRequire(fromFile).resolve(request); @@ -153,16 +156,19 @@ function tryResolve(fromFile: string, request: string): string | undefined { } } -// An @ffmpeg-installer / @ffprobe-installer package reachable from the current folder, located -// but never loaded. The platform package is resolved via the installer package first (pnpm layout). +// An @ffmpeg-installer / @ffprobe-installer package installed next to HyperFrames itself (a global +// or npx install), located but never loaded. A copy in the working directory is project content, +// so it is skipped. The platform package is resolved via the installer package first (pnpm layout). function findInInstallerPackage(name: FfBinaryName): string | undefined { - const project = resolve("package.json"); + const project = import.meta.url; const platformManifest = `@${name}-installer/${process.platform}-${process.arch}/package.json`; const installer = tryResolve(project, `@${name}-installer/${name}/package.json`); const manifest = (installer && tryResolve(installer, platformManifest)) ?? tryResolve(project, platformManifest); const candidate = manifest && join(dirname(manifest), binaryFileName(name)); - return candidate && isExecutablePathCandidate(candidate) ? candidate : undefined; + return candidate && isTrustedExecutablePath(candidate) && isExecutablePathCandidate(candidate) + ? candidate + : undefined; } function searchSystem(name: FfBinaryName): string | undefined { @@ -180,12 +186,14 @@ function searchSystem(name: FfBinaryName): string | undefined { timeout: 5000, }); const candidate = chooseBestPathCandidate(name, output.split(/\r?\n/)); - found = candidate && isExecutablePathCandidate(candidate) ? candidate : scanPath(name); + found = + candidate && isTrustedExecutablePath(candidate) && isExecutablePathCandidate(candidate) + ? candidate + : scanPath(name); } catch { found = scanPath(name); } } - found ??= findInProjectLocalBin(name); found ??= findInCommonDirsOrInstallerPackage(name); return found; } @@ -217,9 +225,9 @@ export interface FindFfBinaryOptions { /** * Resolve an FFmpeg-family binary: env override first, then a native - * PATH scan on Windows or `which` plus PATH scan on Unix, - * then a project-local `.hyperframes/bin`, then well-known Unix install dirs, then an - * `@ffmpeg-installer`/`@ffprobe-installer` package reachable from the current folder. + * PATH scan on Windows or `which` plus PATH scan on Unix, then well-known Unix install dirs, + * then an `@ffmpeg-installer`/`@ffprobe-installer` package installed next to HyperFrames. + * Discovery never returns a file in the working directory (see trustedExecutable.ts). * A found binary is cached for the process lifetime; a miss only for a few * seconds, so a long-running server sees an install made after it started. The env * override is re-read on every call. @@ -236,6 +244,14 @@ export function findFfBinary( return lookupOnSystem(name); } +/** {@link findFfBinary}, or an ENOENT error naming the override. Never the bare name for the OS to look up. */ +export function requireFfBinary(name: FfBinaryName): string { + const found = findFfBinary(name); + if (found) return found; + const message = `[FFmpeg] ${name} not found. Install FFmpeg or set ${ENV_BY_NAME[name]} to its absolute path.`; + throw Object.assign(new Error(message), { code: "ENOENT" }); +} + /** Test hook: drop cached system lookups so resolution can be re-exercised. */ export function clearFfBinaryLookupCache(): void { pathLookupCache.clear(); diff --git a/packages/parsers/src/trustedExecutable.test.ts b/packages/parsers/src/trustedExecutable.test.ts new file mode 100644 index 0000000000..98e475e237 --- /dev/null +++ b/packages/parsers/src/trustedExecutable.test.ts @@ -0,0 +1,41 @@ +import { homedir } from "node:os"; +import { dirname, join, resolve } from "node:path"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { isTrustedDirectory, isTrustedExecutablePath } from "./trustedExecutable.js"; + +describe("isTrustedDirectory", () => { + afterEach(() => { + vi.restoreAllMocks(); + }); + + it("rejects relative entries, the working directory and folders inside it", () => { + const project = resolve("/projects/shared"); + vi.spyOn(process, "cwd").mockReturnValue(project); + + for (const dir of ["", ".", "bin", "./node_modules/.bin"]) { + expect(isTrustedDirectory(dir)).toBe(false); + } + expect(isTrustedDirectory(project)).toBe(false); + expect(isTrustedDirectory(join(project, "node_modules", ".bin"))).toBe(false); + expect(isTrustedExecutablePath(join(project, ".hyperframes", "bin", "ffmpeg"))).toBe(false); + expect(isTrustedExecutablePath("ffmpeg")).toBe(false); + }); + + it("accepts absolute folders outside the working directory", () => { + vi.spyOn(process, "cwd").mockReturnValue(resolve("/projects/shared")); + + expect(isTrustedDirectory(resolve("/usr/local/bin"))).toBe(true); + expect(isTrustedDirectory(resolve("/projects/shared-tools"))).toBe(true); + expect(isTrustedExecutablePath(resolve("/opt/homebrew/bin/ffmpeg"))).toBe(true); + }); + + it("run from the home folder or above it, skips only that folder itself", () => { + const home = homedir(); + for (const cwd of [home, dirname(home)]) { + vi.spyOn(process, "cwd").mockReturnValue(cwd); + + expect(isTrustedDirectory(cwd)).toBe(false); + expect(isTrustedDirectory(join(home, ".local", "bin"))).toBe(true); + } + }); +}); diff --git a/packages/parsers/src/trustedExecutable.ts b/packages/parsers/src/trustedExecutable.ts new file mode 100644 index 0000000000..75f8c04038 --- /dev/null +++ b/packages/parsers/src/trustedExecutable.ts @@ -0,0 +1,96 @@ +import { execFileSync } from "node:child_process"; +import { accessSync, constants, existsSync, realpathSync } from "node:fs"; +import { homedir } from "node:os"; +import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; + +/** + * The one rule for finding a helper program by name. A project folder can come from anyone, so a + * program is taken only from an absolute PATH entry outside the working directory, or a fixed + * install dir. Only an override the person sets in their own environment may point into it. + */ + +function comparable(path: string): string { + let full = resolve(path); + try { + full = realpathSync.native(full); + } catch { + full = resolve(path); + } + return process.platform === "win32" ? full.toLowerCase() : full; +} + +function contains(parent: string, child: string): boolean { + const rel = relative(parent, child); + return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)); +} + +/** Whether a program in `dir` may be run without the person naming it. */ +export function isTrustedDirectory(dir: string): boolean { + if (!dir || !isAbsolute(dir)) return false; + const target = comparable(dir); + const cwd = comparable(process.cwd()); + if (target === cwd) return false; + // From the home folder (or above it) every per-user install dir is inside; skip only the folder. + return contains(cwd, comparable(homedir())) || !contains(cwd, target); +} + +/** Whether `file` is an absolute path in a folder {@link isTrustedDirectory} accepts. */ +export function isTrustedExecutablePath(file: string): boolean { + return isAbsolute(file) && isTrustedDirectory(dirname(file)); +} + +/** The PATH folders a helper program may come from, in PATH order. */ +export function trustedPathDirs(pathValue = process.env.PATH ?? ""): string[] { + const entries = pathValue.split(delimiter); + return [...new Set(entries.filter((dir) => isTrustedDirectory(dir)))]; +} + +function windowsExtensions(): string[] { + const listed = (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD") + .split(";") + .map((ext) => ext.trim().toLowerCase()) + .filter(Boolean); + return [...new Set([".exe", ...listed])]; +} + +function isExecutableFile(file: string): boolean { + if (process.platform === "win32") return existsSync(file); + try { + accessSync(file, constants.X_OK); + return true; + } catch { + return false; + } +} + +function scanTrustedPath(name: string): string | undefined { + const extensions = process.platform === "win32" ? windowsExtensions() : [""]; + for (const dir of trustedPathDirs()) { + for (const ext of extensions) { + const candidate = join(dir, `${name}${ext}`); + if (isExecutableFile(candidate)) return candidate; + } + } + return undefined; +} + +/** Windows walks PATH itself: `where` lists the working directory first. Elsewhere `which` + * answers, and an untrusted first hit falls through to the PATH walk. */ +export function findTrustedExecutable(name: string): string | undefined { + if (process.platform === "win32") return scanTrustedPath(name); + let listed: string | undefined; + try { + listed = execFileSync("which", [name], { + encoding: "utf-8", + stdio: ["ignore", "pipe", "ignore"], + timeout: 5000, + }) + .split(/\r?\n/) + .map((line) => line.trim()) + .find(Boolean); + } catch { + return undefined; + } + if (!listed) return undefined; + return isTrustedExecutablePath(listed) ? listed : scanTrustedPath(name); +} diff --git a/packages/studio-server/src/helpers/childProcess.windowsHide.test.ts b/packages/studio-server/src/helpers/childProcess.windowsHide.test.ts index 64a9b5b318..94e6ec6973 100644 --- a/packages/studio-server/src/helpers/childProcess.windowsHide.test.ts +++ b/packages/studio-server/src/helpers/childProcess.windowsHide.test.ts @@ -12,6 +12,7 @@ vi.mock("node:child_process", () => { }); vi.mock("@hyperframes/parsers/ff-binaries", () => ({ findFfBinary: (name: string) => `/fake/bin/${name}`, + requireFfBinary: (name: string) => `/fake/bin/${name}`, })); import { probeMediaMetadata } from "./mediaMetadata.js"; diff --git a/packages/studio-server/src/helpers/loudness.windowsHide.test.ts b/packages/studio-server/src/helpers/loudness.windowsHide.test.ts index 6493d3dca0..6274504b91 100644 --- a/packages/studio-server/src/helpers/loudness.windowsHide.test.ts +++ b/packages/studio-server/src/helpers/loudness.windowsHide.test.ts @@ -24,6 +24,11 @@ vi.mock("node:child_process", async (importOriginal) => { return { ...actual, default: { ...actual, execFile: execFileMock }, execFile: execFileMock }; }); +// A lane without FFmpeg still reaches the stubbed ffprobe. +vi.mock("@hyperframes/parsers/ff-binaries", () => ({ + findFfBinary: (name: string) => `/fake/${name}`, +})); + import { measureAudio } from "./loudness.js"; describe("measureAudio child-process options", () => { diff --git a/packages/studio-server/src/helpers/mediaMetadata.ts b/packages/studio-server/src/helpers/mediaMetadata.ts index 6381f88b4b..2e05dc9340 100644 --- a/packages/studio-server/src/helpers/mediaMetadata.ts +++ b/packages/studio-server/src/helpers/mediaMetadata.ts @@ -294,8 +294,12 @@ export async function probeAudioTrack( filePath: string, runner: FfprobeRunner = execFileRunner, ): Promise<{ stream: number; channels: number } | null> { + const ffprobePath = + findFfBinary("ffprobe", { configuredMustExist: true }) ?? + (runner === execFileRunner ? undefined : "ffprobe"); + if (!ffprobePath) return null; const result = await runner( - findFfBinary("ffprobe") ?? "ffprobe", + ffprobePath, [ ...["-v", "error", "-select_streams", "a"], ...["-show_entries", "stream=codec_type,codec_name,channels", "-of", "json", "--", filePath], diff --git a/packages/studio-server/src/helpers/noTrustedFfmpeg.test.ts b/packages/studio-server/src/helpers/noTrustedFfmpeg.test.ts new file mode 100644 index 0000000000..f2f2761e70 --- /dev/null +++ b/packages/studio-server/src/helpers/noTrustedFfmpeg.test.ts @@ -0,0 +1,69 @@ +import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { delimiter, join } from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +// Which FFmpeg tools have a trusted install; the rest are missing, as on a machine without FFmpeg. +const trusted = vi.hoisted(() => ({ paths: {} as Record })); +vi.mock("@hyperframes/parsers/ff-binaries", () => ({ + findFfBinary: (name: string) => trusted.paths[name], + requireFfBinary: (name: string) => { + const found = trusted.paths[name]; + if (found) return found; + throw Object.assign(new Error(`[FFmpeg] ${name} not found.`), { code: "ENOENT" }); + }, +})); + +import { probeAudioTrack } from "./mediaMetadata.js"; +import { decodePeakMap } from "./peakMap.js"; +import { decodeAudioPeaks } from "./waveform.js"; + +describe.skipIf(process.platform === "win32")( + "studio audio helpers without a trusted FFmpeg", + () => { + const originalPath = process.env.PATH; + let root = ""; + let marker = ""; + + function script(dir: string, name: string, body: string): string { + const file = join(dir, name); + writeFileSync(file, `#!/bin/sh\n${body}\n`, { mode: 0o755 }); + return file; + } + + // The project's node_modules/.bin leads PATH, as under `npm run`, and holds planted tools. + beforeEach(() => { + root = realpathSync(mkdtempSync(join(tmpdir(), "hf-studio-planted-"))); + marker = join(root, "ran"); + const bin = join(root, "project", "node_modules", ".bin"); + mkdirSync(bin, { recursive: true }); + for (const name of ["ffmpeg", "ffprobe"]) script(bin, name, `echo ${name} >> "${marker}"`); + process.env.PATH = `${bin}${delimiter}${originalPath ?? ""}`; + trusted.paths = {}; + }); + + afterEach(() => { + process.env.PATH = originalPath; + rmSync(root, { recursive: true, force: true }); + }); + + it("decodes no peaks rather than running the ffmpeg PATH finds by name", async () => { + const tools = join(root, "tools"); + mkdirSync(tools); + trusted.paths.ffprobe = script( + tools, + "ffprobe", + `echo '{"streams":[{"codec_type":"audio","codec_name":"aac","channels":2}]}'`, + ); + + await expect(decodeAudioPeaks("clip.m4a")).rejects.toThrow(/ffmpeg not found/); + await expect(decodePeakMap("clip.m4a")).rejects.toThrow(/ffmpeg not found/); + expect(existsSync(marker)).toBe(false); + }); + + it("finds no audio track rather than running the ffprobe PATH finds by name", async () => { + await expect(probeAudioTrack("clip.m4a")).resolves.toBeNull(); + expect(existsSync(marker)).toBe(false); + }); + }, +); diff --git a/packages/studio-server/src/helpers/peakMap.decodeFailure.test.ts b/packages/studio-server/src/helpers/peakMap.decodeFailure.test.ts index a51a2c0add..488226b354 100644 --- a/packages/studio-server/src/helpers/peakMap.decodeFailure.test.ts +++ b/packages/studio-server/src/helpers/peakMap.decodeFailure.test.ts @@ -7,6 +7,7 @@ import { describe, expect, it, vi } from "vitest"; const fakeBin = vi.hoisted(() => ({ dir: "" })); vi.mock("@hyperframes/parsers/ff-binaries", () => ({ findFfBinary: (name: string) => join(fakeBin.dir, name), + requireFfBinary: (name: string) => join(fakeBin.dir, name), })); import { decodePeakMap } from "./peakMap"; diff --git a/packages/studio-server/src/helpers/peakMap.ts b/packages/studio-server/src/helpers/peakMap.ts index 2ad15e201c..cc9018846a 100644 --- a/packages/studio-server/src/helpers/peakMap.ts +++ b/packages/studio-server/src/helpers/peakMap.ts @@ -1,5 +1,5 @@ import { spawn } from "node:child_process"; -import { findFfBinary } from "@hyperframes/parsers/ff-binaries"; +import { requireFfBinary } from "@hyperframes/parsers/ff-binaries"; import { probeAudioTrack } from "./mediaMetadata.js"; export const PEAK_BIN_SECONDS = 0.05; @@ -64,9 +64,10 @@ export async function decodePeakMap(mediaPath: string): Promise { const track = await probeAudioTrack(mediaPath); if (!track || track.channels < 1) throw new Error("no audio stream"); const { stream, channels } = track; + const ffmpeg = requireFfBinary("ffmpeg"); return new Promise((resolvePromise, reject) => { const proc = spawn( - findFfBinary("ffmpeg") ?? "ffmpeg", + ffmpeg, [ "-v", "error", diff --git a/packages/studio-server/src/helpers/waveform.file-race.test.ts b/packages/studio-server/src/helpers/waveform.file-race.test.ts index fbd54d57ad..a0ad02d343 100644 --- a/packages/studio-server/src/helpers/waveform.file-race.test.ts +++ b/packages/studio-server/src/helpers/waveform.file-race.test.ts @@ -34,7 +34,10 @@ vi.mock("node:child_process", async () => { }), }; }); -vi.mock("@hyperframes/parsers/ff-binaries", () => ({ findFfBinary: () => "ffmpeg" })); +vi.mock("@hyperframes/parsers/ff-binaries", () => ({ + findFfBinary: () => "/fake/bin/ffmpeg", + requireFfBinary: () => "/fake/bin/ffmpeg", +})); vi.mock("./mediaMetadata.js", () => ({ probeAudioTrack: async () => ({ stream: 0, channels: 1 }), })); diff --git a/packages/studio-server/src/helpers/waveform.ts b/packages/studio-server/src/helpers/waveform.ts index 07376d0376..3752e4841b 100644 --- a/packages/studio-server/src/helpers/waveform.ts +++ b/packages/studio-server/src/helpers/waveform.ts @@ -9,7 +9,7 @@ import { statSync, } from "node:fs"; import { dirname, join } from "node:path"; -import { findFfBinary } from "@hyperframes/parsers/ff-binaries"; +import { requireFfBinary } from "@hyperframes/parsers/ff-binaries"; import { probeAudioTrack } from "./mediaMetadata.js"; import { createStagingDir } from "@hyperframes/core/atomic-file"; @@ -62,9 +62,10 @@ function computePeaks(floats: Float32Array, count: number): number[] { export async function decodeAudioPeaks(audioPath: string): Promise { const track = await probeAudioTrack(audioPath); if (!track) throw new Error("no audio stream"); + const ffmpeg = requireFfBinary("ffmpeg"); return new Promise((resolvePromise, reject) => { const proc = spawn( - findFfBinary("ffmpeg") ?? "ffmpeg", + ffmpeg, [ "-i", audioPath, diff --git a/skills-manifest.json b/skills-manifest.json index d677bcc706..e4e9ed57c2 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -10,7 +10,7 @@ "files": 78 }, "hyperframes-cli": { - "hash": "2492752b9f8616f2", + "hash": "d6972257fbc99fc0", "files": 13 }, "hyperframes-registry": { diff --git a/skills/hyperframes-cli/references/doctor-browser.md b/skills/hyperframes-cli/references/doctor-browser.md index 7b01899eea..c854881700 100644 --- a/skills/hyperframes-cli/references/doctor-browser.md +++ b/skills/hyperframes-cli/references/doctor-browser.md @@ -56,7 +56,7 @@ npx hyperframes doctor --json Set both variables in the environment that launches HyperFrames. On Windows, point them at `ffmpeg.exe` and `ffprobe.exe` using your shell's environment-variable syntax. A configured path takes precedence over automatic discovery; a missing configured file is reported as missing. -Alternatively, put the binaries in `.hyperframes/bin/ffmpeg` and `.hyperframes/bin/ffprobe` (`.exe` on Windows), then run HyperFrames from that project's directory. Discovery checks `PATH` before this project-local directory, so use the environment variables when you need a particular build. +Automatic discovery never runs an FFmpeg or FFprobe that sits inside the project folder or the working directory, such as `.hyperframes/bin` or a project's `@ffmpeg-installer` package, since a project can come from anyone. Keep the binaries outside the project and either set the variables above or add their folder to `PATH` as an absolute path. Verify the **FFmpeg** and **FFprobe** entries in `doctor --json` report `ok: true` and the expected paths. To gate only these encoding dependencies with `jq`: