From a694ae477db2b88a1d6aed650e658d8358c51004 Mon Sep 17 00:00:00 2001 From: Michael Wang Date: Mon, 16 Nov 2026 23:37:37 +0000 Subject: [PATCH] fix(cli): transcribe replaces a link at its output names instead of writing through it (#7982) * fix(cli): transcribe replaces a link at its output names instead of writing through it whisper-cli now writes its JSON in a private temp folder, and the CLI puts transcript.json in place by rename. The HeyGen engine, the SRT/VTT caption file and the caption script patch also write by rename. A link planted at transcript.json, transcript.srt or transcript.vtt is replaced by a regular file, and the file it pointed to is left unchanged. * test(cli): prove the link was replaced from file contents, not lstat CodeQL reads an lstat followed by a read of the same path as a race. The outside file staying unchanged while the output name holds the new content already shows the link was replaced. * test(cli): make a caption write fail the same way on every OS A dangling link through a file was refused on POSIX but replaced on Windows, where access() on it reports ENOENT and the rename takes its place. Both are safe, so the failure-message tests now use a caption name the disk accepts but whose temp sibling is too long. --- packages/cli/src/api/transcribe.ts | 4 +- packages/cli/src/commands/transcribe.test.ts | 49 ++++++++++--- packages/cli/src/heygen/transcribe.test.ts | 24 ++++++- packages/cli/src/heygen/transcribe.ts | 5 +- packages/cli/src/whisper/normalize.ts | 5 +- .../cli/src/whisper/transcribe.output.test.ts | 68 +++++++++++++++++++ packages/cli/src/whisper/transcribe.ts | 48 ++++++++++--- 7 files changed, 176 insertions(+), 27 deletions(-) create mode 100644 packages/cli/src/whisper/transcribe.output.test.ts diff --git a/packages/cli/src/api/transcribe.ts b/packages/cli/src/api/transcribe.ts index ddd8b3cd67..05602137e6 100644 --- a/packages/cli/src/api/transcribe.ts +++ b/packages/cli/src/api/transcribe.ts @@ -1,4 +1,4 @@ -import { existsSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs"; +import { existsSync, realpathSync, rmSync, statSync } from "node:fs"; import { replaceFileAtomically } from "@hyperframes/core/atomic-file"; import { basename, dirname, extname, join, resolve } from "node:path"; import { transcribeWithHeygen } from "../heygen/transcribe.js"; @@ -319,7 +319,7 @@ function writeCaptionSidecar( const preGrouped = preserveCues || phraseLevelSource; const content = to === "srt" ? formatSrt(words, { preGrouped }) : formatVtt(words, { preGrouped }); - writeFileSync(outPath, content); + replaceFileAtomically(outPath, content); } // --------------------------------------------------------------------------- diff --git a/packages/cli/src/commands/transcribe.test.ts b/packages/cli/src/commands/transcribe.test.ts index 429faf4234..243be48991 100644 --- a/packages/cli/src/commands/transcribe.test.ts +++ b/packages/cli/src/commands/transcribe.test.ts @@ -86,6 +86,10 @@ function fakeTranscript(dir: string, text: string) { }; } +/** A caption name the disk takes, whose temp sibling (13 characters longer) it refuses on every OS, even as root. */ +const NO_ROOM_FOR_TEMP = "c".repeat(250); +const NAME_REFUSED = /ENAMETOOLONG|ENOENT|EINVAL/; + function errorMessage(json: Record): string { return String((json.error as { message?: unknown } | undefined)?.message); } @@ -860,8 +864,7 @@ Render video. Built for agents. dirs.push(dir); const input = join(dir, "subtitles.srt"); writeFileSync(input, "1\n00:00:00,000 --> 00:00:01,000\nHello\n"); - const output = join(dir, "through-file.vtt"); - symlinkSync(join(input, "x.vtt"), output); + const output = join(dir, NO_ROOM_FOR_TEMP); await expect( transcribeCmd.run!({ args: { input, json: true, to: "vtt", output } } as never), @@ -873,8 +876,7 @@ Render video. Built for agents. message: expect.stringContaining(`The caption file ${output} could not be written: `), }), }); - // Windows and Unix report a path through a file with different error codes. - expect(errorMessage(lastJson())).toMatch(/ENOTDIR|ENOENT/); + expect(errorMessage(lastJson())).toMatch(NAME_REFUSED); }); async function runWithInodeZero(zero: (path: string) => boolean, args: object): Promise { @@ -974,12 +976,9 @@ Render video. Built for agents. "it is the same file as", ], [ - "a link that runs through a file", - (dir: string) => { - symlinkSync(join(dir, "narration.wav", "x.srt"), join(dir, "through-file.srt")); - return join(dir, "through-file.srt"); - }, - /ENOTDIR|ENOENT/, + "a name with no room for its temp file", + (dir: string) => join(dir, NO_ROOM_FOR_TEMP), + NAME_REFUSED, ], ])("keeps the transcript when --output is %s", async (_name, output, reason) => { const { dir, input } = dummyAudio(); @@ -1007,6 +1006,36 @@ Render video. Built for agents. expect(JSON.parse(readFileSync(transcript, "utf8"))).toMatchObject([{ text: "whisper" }]); }); + it.each(["srt", "vtt"] as const)( + "replaces a link planted at transcript.%s instead of writing through it", + async (to) => { + const { dir, input } = dummyAudio(); + const outside = mkdtempSync(join(tmpdir(), "hf-transcribe-outside-")); + dirs.push(dir, outside); + const target = join(outside, "profile"); + writeFileSync(target, "keep me\n"); + const caption = join(dir, `transcript.${to}`); + transcribeMock.mockImplementation(async (_input, outputDir) => + fakeTranscript(outputDir, "whisper"), + ); + + symlinkSync(target, caption); + await transcribeCmd.run!({ args: { input, json: true, engine: "whisper", to } } as never); + expect(lastJson()).toMatchObject({ ok: true }); + expect(readFileSync(target, "utf8")).toBe("keep me\n"); + + // Exporting the project's own transcript.json takes the other path to the same file name. + rmSync(caption); + symlinkSync(target, caption); + const transcript = join(dir, "transcript.json"); + await transcribeCmd.run!({ args: { input: transcript, json: true, to } } as never); + expect(lastJson()).toMatchObject({ ok: true, outputPath: caption }); + + expect(readFileSync(target, "utf8")).toBe("keep me\n"); + expect(readFileSync(caption, "utf8")).toContain("-->"); + }, + ); + it("says the transcript was saved when the caption file cannot be written", async () => { const { dir, input } = dummyAudio(); dirs.push(dir); diff --git a/packages/cli/src/heygen/transcribe.test.ts b/packages/cli/src/heygen/transcribe.test.ts index f3ffa836d9..f2f64a4f33 100644 --- a/packages/cli/src/heygen/transcribe.test.ts +++ b/packages/cli/src/heygen/transcribe.test.ts @@ -1,5 +1,5 @@ import { execFileSync } from "node:child_process"; -import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { afterAll, afterEach, describe, expect, it, vi } from "vitest"; @@ -71,6 +71,28 @@ describe("HeyGen transcription", () => { expect(JSON.parse(readFileSync(out, "utf8"))).toHaveLength(2); }); + it.skipIf(!ffmpeg)( + "replaces a link at transcript.json instead of writing through it", + async () => { + const audio = join(dir, "c.wav"); + execFileSync(ffmpeg!, ["-v", "error", "-y", "-f", "lavfi", "-i", "sine=f=300:d=1", audio]); + vi.stubGlobal("fetch", async () => new Response(JSON.stringify({ data: job }))); + const outside = mkdtempSync(join(tmpdir(), "hf-heygen-outside-")); + const target = join(outside, "profile"); + writeFileSync(target, "keep me\n"); + mkdirSync(join(dir, "linked")); + const out = join(dir, "linked", "transcript.json"); + symlinkSync(target, out); + try { + await transcribeWithHeygen(audio, out); + expect(readFileSync(target, "utf8")).toBe("keep me\n"); + expect(JSON.parse(readFileSync(out, "utf8"))).toHaveLength(2); + } finally { + rmSync(outside, { recursive: true, force: true }); + } + }, + ); + it.skipIf(!ffmpeg)("logs the job in the project, wherever the transcript goes", async () => { const audio = join(dir, "a.wav"); execFileSync(ffmpeg!, ["-v", "error", "-y", "-f", "lavfi", "-i", "sine=f=300:d=1.5", audio]); diff --git a/packages/cli/src/heygen/transcribe.ts b/packages/cli/src/heygen/transcribe.ts index c3508f5181..32d8d239c8 100644 --- a/packages/cli/src/heygen/transcribe.ts +++ b/packages/cli/src/heygen/transcribe.ts @@ -1,6 +1,7 @@ // Transcription on HeyGen (`transcribe --engine heygen`): word times from its speech model, with speakers when asked. // The route runs inside the POST and takes an API key; the Idempotency-Key makes a re-run free. -import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { replaceFileAtomically } from "@hyperframes/core/atomic-file"; import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import type { TranscriptionCreateRequest } from "../cloud/_gen/types.js"; @@ -94,7 +95,7 @@ export async function transcribeWithHeygen( }, ); const words = wordsOf(job); - writeFileSync(transcriptPath, JSON.stringify(words, null, 2)); + replaceFileAtomically(transcriptPath, JSON.stringify(words, null, 2)); return { transcriptPath, model: typeof job.model === "string" ? job.model : MODEL, diff --git a/packages/cli/src/whisper/normalize.ts b/packages/cli/src/whisper/normalize.ts index 7c990087d3..1e7c6c349f 100644 --- a/packages/cli/src/whisper/normalize.ts +++ b/packages/cli/src/whisper/normalize.ts @@ -1,4 +1,5 @@ -import { readFileSync, readdirSync, writeFileSync } from "node:fs"; +import { readFileSync, readdirSync } from "node:fs"; +import { replaceFileAtomically } from "@hyperframes/core/atomic-file"; import { readJsonFileText } from "../utils/jsonFlag.js"; import { extname, join } from "node:path"; import { parseExpressionAt, tokenizer } from "acorn"; @@ -600,7 +601,7 @@ export function patchCaptionHtml(dir: string, words: Word[]): void { if (match) { const varName = scriptMatch ? "script" : "TRANSCRIPT"; content = content.replace(match, () => `const ${varName} = ${wordsJson};`); - writeFileSync(file, content, "utf-8"); + replaceFileAtomically(file, content); } } } diff --git a/packages/cli/src/whisper/transcribe.output.test.ts b/packages/cli/src/whisper/transcribe.output.test.ts new file mode 100644 index 0000000000..07e1bc11be --- /dev/null +++ b/packages/cli/src/whisper/transcribe.output.test.ts @@ -0,0 +1,68 @@ +import { + chmodSync, + existsSync, + mkdtempSync, + readFileSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { findFFprobe } from "../browser/ffmpeg.js"; +import * as manager from "./manager.js"; +import { transcribe } from "./transcribe.js"; +import { encodeWav } from "./wav.test-helpers.js"; + +// A shebang script stands in for whisper-cli, and a 16 kHz WAV passes through only after ffprobe reads it. +describe.skipIf(process.platform === "win32" || !findFFprobe())("whisper transcribe output", () => { + let dir: string; + let outside: string; + beforeEach(() => { + dir = mkdtempSync(join(tmpdir(), "hf-whisper-output-")); + outside = mkdtempSync(join(tmpdir(), "hf-whisper-outside-")); + }); + afterEach(() => { + vi.restoreAllMocks(); + rmSync(dir, { recursive: true, force: true }); + rmSync(outside, { recursive: true, force: true }); + }); + + it("has whisper write outside the project and replaces a link at transcript.json", async () => { + const seen = join(outside, "output-file"); + const whisperCli = join(outside, "whisper-cli"); + const json = { transcription: [{ tokens: [{ text: " Hi", offsets: { from: 0, to: 500 } }] }] }; + writeFileSync( + whisperCli, + `#!${process.execPath} +const fs = require("fs"); +const args = process.argv.slice(2); +const base = args[args.indexOf("--output-file") + 1]; +fs.writeFileSync(${JSON.stringify(seen)}, base); +fs.writeFileSync(base + ".json", ${JSON.stringify(JSON.stringify(json))}); +`, + ); + chmodSync(whisperCli, 0o755); + vi.spyOn(manager, "ensureWhisper").mockResolvedValue({ + executablePath: whisperCli, + source: "system", + }); + vi.spyOn(manager, "ensureModel").mockResolvedValue(join(outside, "ggml-small.en.bin")); + const input = join(dir, "narration.wav"); + writeFileSync(input, encodeWav(new Float32Array(16000), 16000)); + const target = join(outside, "authorized_keys"); + writeFileSync(target, "keep me\n"); + const transcriptPath = join(dir, "transcript.json"); + symlinkSync(target, transcriptPath); + + const result = await transcribe(input, dir); + + expect(readFileSync(target, "utf8")).toBe("keep me\n"); + expect(JSON.parse(readFileSync(transcriptPath, "utf8"))).toEqual(json); + expect(result).toMatchObject({ transcriptPath, wordCount: 1 }); + const whisperFolder = dirname(readFileSync(seen, "utf8")); + expect(whisperFolder).not.toBe(dir); + expect(existsSync(whisperFolder)).toBe(false); + }); +}); diff --git a/packages/cli/src/whisper/transcribe.ts b/packages/cli/src/whisper/transcribe.ts index a4af0093eb..8087da5281 100644 --- a/packages/cli/src/whisper/transcribe.ts +++ b/packages/cli/src/whisper/transcribe.ts @@ -3,7 +3,16 @@ import { execFile, execFileSync } from "node:child_process"; import { once } from "node:events"; import { createInterface } from "node:readline"; import type { Readable } from "node:stream"; -import { existsSync, readFileSync, mkdirSync, rmSync, statSync, unlinkSync } from "node:fs"; +import { + existsSync, + readFileSync, + mkdirSync, + mkdtempSync, + rmSync, + statSync, + unlinkSync, +} from "node:fs"; +import { replaceFileAtomically } from "@hyperframes/core/atomic-file"; import { basename, join, extname } from "node:path"; import { homedir, tmpdir } from "node:os"; import { randomUUID } from "node:crypto"; @@ -514,8 +523,10 @@ export async function transcribe( status: "started", durationSeconds: wavSeconds, }); - const outputBase = join(outputDir, basename(TRANSCRIPT_FILE, ".json")); mkdirSync(outputDir, { recursive: true }); + // whisper-cli opens its output by name and follows a link there, so it writes in a private folder. + const workDir = mkdtempSync(join(tmpdir(), "hyperframes-whisper-")); + const outputBase = join(workDir, basename(TRANSCRIPT_FILE, ".json")); const whisperArgs = [ "--model", @@ -540,8 +551,9 @@ export async function transcribe( through = Math.max(through, at); emitWords(onEvent, model, words, through); }; + let produced: string; try { - await runWhisper(whisper.executablePath, whisperArgs, { + produced = await runWhisperInto(`${outputBase}.json`, whisper.executablePath, whisperArgs, { timeoutMs: whisperTimeoutMs, signal: options?.startCancellation?.(), onStdout: @@ -559,6 +571,7 @@ export async function transcribe( : undefined, }); } catch (err) { + if (err instanceof NoWhisperOutput) throw err; // Surface the timeout knob when the child was killed by our own timeout — // otherwise the reporter sees a bare ETIMEDOUT / SIGTERM with no hint that // `--timeout` even exists. Any other failure names the build, model and stderr. @@ -570,15 +583,14 @@ export async function transcribe( }); } throw await diagnoseWhisperFailure(err, whisper, modelPath, model); + } finally { + rmSync(workDir, { recursive: true, force: true }); } - // 6. Read and validate output - const transcriptPath = `${outputBase}.json`; - if (!existsSync(transcriptPath)) { - throw new Error("Whisper did not produce output. Check the input file."); - } - - const transcript = parseWhisperJson(readFileSync(transcriptPath, "utf-8")); + // 6. Validate the output, then put it in place by rename so a link at transcript.json is replaced + const transcript = parseWhisperJson(produced); + const transcriptPath = join(outputDir, TRANSCRIPT_FILE); + replaceFileAtomically(transcriptPath, produced); const reportedLanguage: unknown = transcript.result?.language; const detectedLanguage = automaticLanguage && typeof reportedLanguage === "string" && reportedLanguage.length > 0 @@ -644,6 +656,22 @@ function segmentWords(line: string): { words: Word[]; end: number } | null { return { words, end }; } +/** Runs whisper and returns the JSON it wrote to `output`; a run that wrote none fails as it is, not as a crash. */ +async function runWhisperInto( + output: string, + ...[executable, args, options]: Parameters +): Promise { + await runWhisper(executable, args, options); + if (!existsSync(output)) throw new NoWhisperOutput(); + return readFileSync(output, "utf-8"); +} + +class NoWhisperOutput extends Error { + constructor() { + super("Whisper did not produce output. Check the input file."); + } +} + /** Resolves once whisper exits and both its streams are read, so no printed line is lost. */ async function runWhisper( executable: string,