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.
This commit is contained in:
Michael Wang
2026-11-16 23:37:37 +00:00
committed by GitHub
parent 7623f4fa12
commit a694ae477d
7 changed files with 176 additions and 27 deletions
+2 -2
View File
@@ -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);
}
// ---------------------------------------------------------------------------
+39 -10
View File
@@ -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, unknown>): 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<void> {
@@ -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);
+23 -1
View File
@@ -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]);
+3 -2
View File
@@ -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,
+3 -2
View File
@@ -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);
}
}
}
@@ -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);
});
});
+38 -10
View File
@@ -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<typeof runWhisper>
): Promise<string> {
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,