From c4439890cfbcdbc16d48f1a4b05176abe0138cae Mon Sep 17 00:00:00 2001 From: Michael Wang Date: Tue, 17 Nov 2026 07:16:03 +0000 Subject: [PATCH] fix(cli): escape audio and media-use output, pin model files (#8013) * fix(cli): audio and media-use print control characters from project files as visible escapes hyperframes audio, audio --read and media-use resolve (including --candidates) printed file names, element ids, transcript words, model descriptions and media manifest fields as they were. They now pass through terminalText, so a control character shows as a visible \xNN escape. The media-use engine runs without the CLI's packages, so it carries a small copy of the helper. --json output is unchanged. * fix(engine): playlist check refuses drive-relative and other colon-prefixed entries ffmpeg reads an HLS or ffconcat entry with a colon before its first separator as a URL or a drive, and opens it apart from the list's folder. The folder check read entries such as C:Videos\a.mp4 or c:x.mp4 as names inside the folder and approved them. It now refuses any entry, raw or percent-decoded, whose colon comes before its first /, \, ? or #, as it already refuses absolute and parent-folder paths. http and https segments are still kept. * fix(cli): background-removal and Kokoro TTS model files are pinned to a sha256 The u2net_human_seg weights and the Kokoro model and voices files were downloaded from release URLs and used whatever bytes arrived, and any cached copy was trusted because it existed. Each file now has a pinned size and sha256. A cached copy is checked before it is loaded and downloaded again when it does not match. A download that does not match is discarded with a message that names the file. * fix(engine): playlist check reads entries from the folder ffmpeg uses ffmpeg resolves a list's entries against its path cut at the first ? or #. A list at proj/h#z/list.m3u8 naming ../h#z/x.ts was judged against proj/h#z and approved, while ffmpeg opened proj/../h#z/x.ts. Entries are now judged against the same cut folder. A list in a folder such as "Take #2" still passes when its entries resolve inside that folder. * fix(cli): a pinned model's cached copy is checked and removed under the download lock ensurePinnedFile removed a cached copy that failed its check before the download lock was taken, so a concurrent run could delete a file another run had just published. downloadFile now takes a keepExisting check and runs it under the lock: a copy that passes is kept, one that fails is removed and downloaded again. The mismatch error now says the file does not match its expected checksum, and that a retry helps only if the download was interrupted or corrupted. * fix(cli): audio escapes each field's line breaks, and media-use escapes recipe and stats output The audio formatters escaped their output line by line, so a newline inside a src, warning or transcript still printed as a real line break. Each output line is now escaped whole with terminalText, which shows a newline inside a field as \x0a. media-use resolve also escapes its recipe lines and its --stats lines, which print recipe names, paths and missed intents. * fix(cli): media-use error messages show control characters as visible escapes resolve printed error messages as they were, and some name project or cache data, such as the known recipe names when a recipe is not found. Every error: line now passes through terminalText, as the success lines already do. * ci: the edit accuracy filter includes the CLI model file check The CLI's pinned model download now imports whisper/modelFile.ts, so a change to it must run the edit accuracy bench too. * test(cli): pinned model tests use private temp folders and rename like downloadFile The tests wrote fixtures under fixed names in the shared temp folder, and their download stand-in checked for a file before replacing it. Each test now works in its own mkdtemp folder, and the stand-in asks keepExisting directly and renames the part file into place, as downloadFile does. * test(cli): the media-use terminalText copy is checked against core's The media-use engine keeps its own copy of terminalText. A CLI test now compares the two over U+0000 to U+00A0, so a change to either fails until both match. keepsDest moves above downloadFile's doc comment, which belongs to downloadFile. --- .github/workflows/ci.yml | 1 + .../cli/src/audio/analysis/format.test.ts | 15 +++ packages/cli/src/audio/analysis/format.ts | 3 +- packages/cli/src/audio/read/format.test.ts | 20 ++++ packages/cli/src/audio/read/format.ts | 7 +- .../background-removal/manager.pin.test.ts | 55 ++++++++++ .../cli/src/background-removal/manager.ts | 27 ++--- packages/cli/src/commands/audio.ts | 5 +- packages/cli/src/media-use/lib/candidates.mjs | 5 +- .../cli/src/media-use/lib/candidates.test.mjs | 16 +++ .../cli/src/media-use/lib/terminal-text.d.mts | 1 + .../cli/src/media-use/lib/terminal-text.mjs | 12 +++ packages/cli/src/media-use/resolve.mjs | 36 ++++--- packages/cli/src/media-use/resolve.test.mjs | 61 +++++++++++ .../src/media-use/terminalText.parity.test.ts | 10 ++ packages/cli/src/tts/manager.pin.test.ts | 78 ++++++++++++++ packages/cli/src/tts/manager.ts | 53 +++++----- packages/cli/src/utils/download.test.ts | 37 +++++++ packages/cli/src/utils/download.ts | 15 ++- packages/cli/src/utils/pinnedFile.test.ts | 100 ++++++++++++++++++ packages/cli/src/utils/pinnedFile.ts | 37 +++++++ 21 files changed, 531 insertions(+), 63 deletions(-) create mode 100644 packages/cli/src/background-removal/manager.pin.test.ts create mode 100644 packages/cli/src/media-use/lib/terminal-text.d.mts create mode 100644 packages/cli/src/media-use/lib/terminal-text.mjs create mode 100644 packages/cli/src/media-use/terminalText.parity.test.ts create mode 100644 packages/cli/src/tts/manager.pin.test.ts create mode 100644 packages/cli/src/utils/pinnedFile.test.ts create mode 100644 packages/cli/src/utils/pinnedFile.ts diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 042006a818..dffb95bd16 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -245,6 +245,7 @@ jobs: - "packages/cli/src/server/**" - "packages/cli/src/browser/**" - "packages/cli/src/utils/**" + - "packages/cli/src/whisper/modelFile.ts" - "packages/cli/src/ui/**" - "packages/cli/src/{background-removal,registry,telemetry}/**" - "packages/cli/src/capture/{captureCompositionFrame,captureTimeout,navigateForCapture,readBoundedResponse}.ts" diff --git a/packages/cli/src/audio/analysis/format.test.ts b/packages/cli/src/audio/analysis/format.test.ts index 94e13ba3ec..3c04b3178c 100644 --- a/packages/cli/src/audio/analysis/format.test.ts +++ b/packages/cli/src/audio/analysis/format.test.ts @@ -27,6 +27,21 @@ describe("sparkline", () => { }); describe("formatReport", () => { + it("prints control characters from the project's src, id, errors and warnings as visible escapes", () => { + const text = formatReport({ + version: 1, + items: [ + item({ file: "a\x1b[2K.wav", ref: "#x\x07", warnings: ["w\x1b]52;c;aGk=\x07", "a\nb"] }), + item({ file: "gone\x9b.wav", ref: null, error: "missing \x1b[8m" }), + ], + }); + expect(text).toContain("a\\x1b[2K.wav #x\\x07"); + expect(text).toContain("! w\\x1b]52;c;aGk=\\x07"); + expect(text).toContain("! a\\x0ab"); + expect(text).toContain("gone\\x9b.wav: missing \\x1b[8m"); + for (const raw of ["\x07", "\x1b", "\x9b"]) expect(text).not.toContain(raw); + }); + it("prints file seconds as film seconds through the clip's placement", () => { const text = formatReport({ version: 1, diff --git a/packages/cli/src/audio/analysis/format.ts b/packages/cli/src/audio/analysis/format.ts index 32dd0d9c0d..c0539b9fdb 100644 --- a/packages/cli/src/audio/analysis/format.ts +++ b/packages/cli/src/audio/analysis/format.ts @@ -1,3 +1,4 @@ +import { terminalText } from "@hyperframes/core"; import type { Beats, Downbeats, @@ -147,5 +148,5 @@ function formatItem(item: AudioItem): string[] { export function formatReport(report: AudioReport): string { if (report.items.length === 0) return "No audio matched."; - return report.items.map((item) => formatItem(item).join("\n")).join("\n\n"); + return report.items.map((item) => formatItem(item).map(terminalText).join("\n")).join("\n\n"); } diff --git a/packages/cli/src/audio/read/format.test.ts b/packages/cli/src/audio/read/format.test.ts index 6e2cdf4d6a..3a4b50f782 100644 --- a/packages/cli/src/audio/read/format.test.ts +++ b/packages/cli/src/audio/read/format.test.ts @@ -41,6 +41,26 @@ function read(voiceLufs: number, musicLufs: number): ReadAudio { } describe("formatRead", () => { + it("prints control characters from the transcript, descriptions and file name as visible escapes", () => { + const base = read(-14, -18); + const text = formatRead({ + ...base, + file: "talk\x1b[2K.wav", + description: { overall: "calm\x1b]8;;https://x.test\x07", bgmPrompt: null }, + voice: { + ...base.voice!, + sentences: [{ ...base.voice!.sentences[0]!, text: "hi\x1b]52;c;aGk=\x07" }], + }, + warnings: ["w\x1b[8m", "a\nb"], + }); + expect(text).toContain("talk\\x1b[2K.wav"); + expect(text).toContain("overall: calm\\x1b]8;;https://x.test\\x07"); + expect(text).toContain('"hi\\x1b]52;c;aGk=\\x07"'); + expect(text).toContain("! w\\x1b[8m"); + expect(text).toContain("! a\\x0ab"); + for (const raw of ["\x07", "\x1b"]) expect(text).not.toContain(raw); + }); + it.each([ [-24, -20, "voice -24 LUFS, music -20 LUFS: music 4 dB over voice"], [-14, -18, "voice -14 LUFS, music -18 LUFS: voice 4 dB over music"], diff --git a/packages/cli/src/audio/read/format.ts b/packages/cli/src/audio/read/format.ts index cce7230b07..6e6399c591 100644 --- a/packages/cli/src/audio/read/format.ts +++ b/packages/cli/src/audio/read/format.ts @@ -1,3 +1,4 @@ +import { terminalText } from "@hyperframes/core"; import type { Span } from "@hyperframes/core/audio-analysis"; import { semitones } from "./pitch.js"; import type { @@ -272,7 +273,7 @@ export function formatRead(analysis: ReadAudio, range?: [number, number]): strin const width = Math.max(0, ...lines.map((l) => when(l).length)); const body = lines.map((l) => `${when(l).padEnd(width)} ${l.kind.padEnd(KIND_WIDTH)} ${l.text}`); const warnings = analysis.warnings.map((w) => `! ${w}`); - return [...header(analysis), "", ...body, ...(warnings.length ? ["", ...warnings] : [])].join( - "\n", - ); + return [...header(analysis), "", ...body, ...(warnings.length ? ["", ...warnings] : [])] + .map(terminalText) + .join("\n"); } diff --git a/packages/cli/src/background-removal/manager.pin.test.ts b/packages/cli/src/background-removal/manager.pin.test.ts new file mode 100644 index 0000000000..f3d0d89bdb --- /dev/null +++ b/packages/cli/src/background-removal/manager.pin.test.ts @@ -0,0 +1,55 @@ +import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { afterAll, afterEach, expect, it, vi } from "vitest"; +import { ensureModel, modelPath } from "./manager.js"; + +const cache = await vi.hoisted(async () => { + const { mkdtempSync } = await import("node:fs"); + const { tmpdir } = await import("node:os"); + const dir = mkdtempSync(`${tmpdir()}/hf-bgrm-pin-`); + process.env["HYPERFRAMES_CACHE_DIR"] = dir; + return dir; +}); +vi.mock("../utils/download.js", () => ({ + downloadFile: vi.fn( + async ( + _url: string, + dest: string, + options: { + keepExisting: (path: string) => Promise; + verify: (path: string) => Promise; + }, + ) => { + if (await options.keepExisting(dest)) return; + rmSync(dest, { force: true }); + writeFileSync(`${dest}.part`, "swapped weights"); + await options.verify(`${dest}.part`).catch((error: unknown) => { + rmSync(`${dest}.part`); + throw error; + }); + renameSync(`${dest}.part`, dest); + }, + ), +})); + +afterEach(() => rmSync(cache, { recursive: true, force: true })); +afterAll(() => { + delete process.env["HYPERFRAMES_CACHE_DIR"]; +}); + +it("refuses downloaded weights that do not match the pinned sha256", async () => { + await expect(ensureModel()).rejects.toThrow( + /u2net_human_seg\.onnx was discarded because it does not match/, + ); + + expect(existsSync(modelPath())).toBe(false); +}); + +it("does not load cached weights that do not match the pinned sha256", async () => { + mkdirSync(join(modelPath(), ".."), { recursive: true }); + writeFileSync(modelPath(), "swapped weights"); + + await expect(ensureModel()).rejects.toThrow(/was discarded because it does not match/); + + expect(existsSync(modelPath())).toBe(false); +}); diff --git a/packages/cli/src/background-removal/manager.ts b/packages/cli/src/background-removal/manager.ts index 3a37b40dd2..51e91ecfe1 100644 --- a/packages/cli/src/background-removal/manager.ts +++ b/packages/cli/src/background-removal/manager.ts @@ -1,7 +1,7 @@ -import { existsSync, mkdirSync } from "node:fs"; import { platform, arch } from "node:os"; import { join } from "node:path"; -import { downloadFile } from "../utils/download.js"; +import { ensurePinnedFile } from "../utils/pinnedFile.js"; +import type { ModelFile } from "../whisper/modelFile.js"; import { hyperframesCacheDir } from "@hyperframes/core/cache-dir"; export const MODELS_DIR = hyperframesCacheDir("background-removal", "models"); @@ -14,6 +14,14 @@ const MODEL_URLS: Record = { "https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2net_human_seg.onnx", }; +const MODEL_PINS: Record = { + u2net_human_seg: { + name: "u2net_human_seg.onnx", + bytes: 175_997_641, + sha256: "01eb6a29a5c4d8edb30b56adad9bb3a2a0535338e480724a213e0acfd2d1c73c", + }, +}; + export const MODEL_MEMORY_MB: Record = { u2net_human_seg: 1500, }; @@ -83,15 +91,8 @@ export async function ensureModel( model: ModelId = DEFAULT_MODEL, options?: { onProgress?: (message: string) => void }, ): Promise { - const dest = modelPath(model); - if (existsSync(dest)) return dest; - - mkdirSync(MODELS_DIR, { recursive: true }); - options?.onProgress?.(`Downloading ${model} weights (~168 MB)...`); - await downloadFile(MODEL_URLS[model], dest); - - if (!existsSync(dest)) { - throw new Error(`Model download failed: ${model}`); - } - return dest; + return ensurePinnedFile(MODEL_URLS[model], modelPath(model), MODEL_PINS[model], { + downloading: `Downloading ${model} weights (~168 MB)...`, + onProgress: options?.onProgress, + }); } diff --git a/packages/cli/src/commands/audio.ts b/packages/cli/src/commands/audio.ts index c9406b77dd..2f68c61162 100644 --- a/packages/cli/src/commands/audio.ts +++ b/packages/cli/src/commands/audio.ts @@ -1,4 +1,5 @@ import { join, resolve } from "node:path"; +import { terminalText } from "@hyperframes/core"; import { defineCommand } from "../utils/defineCommand.js"; import type { AnalysisQuality, @@ -205,7 +206,9 @@ async function read(files: string[], flags: AudioFlags) { console.log(JSON.stringify(withMeta(result))); return; } - console.log(`${formatRead(result.analysis, range)}\n\nwhole recording: ${result.textPath}`); + console.log( + `${formatRead(result.analysis, range)}\n\nwhole recording: ${terminalText(result.textPath)}`, + ); } export default defineCommand({ diff --git a/packages/cli/src/media-use/lib/candidates.mjs b/packages/cli/src/media-use/lib/candidates.mjs index c58548c25f..c202d7db22 100644 --- a/packages/cli/src/media-use/lib/candidates.mjs +++ b/packages/cli/src/media-use/lib/candidates.mjs @@ -8,6 +8,7 @@ import { currentRecords } from "./manifest.mjs"; import { readGlobalManifest } from "./cache.mjs"; import { tokenOverlap, typesMatch } from "./match.mjs"; +import { terminalText } from "./terminal-text.mjs"; export const CANDIDATE_CAP = 8; @@ -78,8 +79,8 @@ export function formatCandidates(candidates, { truncated, total } = {}) { const handle = c.scope === "global" ? `--reuse ${String(c.sha).slice(0, 16)}` : c.path || `manifest:${c.id}`; const m = meta(c); - lines.push(` [${c.scope}] ${c.description}${m ? ` (${m})` : ""}`); - lines.push(` ${handle}`); + lines.push(terminalText(` [${c.scope}] ${c.description}${m ? ` (${m})` : ""}`)); + lines.push(terminalText(` ${handle}`)); } if (truncated && total) { lines.push(""); diff --git a/packages/cli/src/media-use/lib/candidates.test.mjs b/packages/cli/src/media-use/lib/candidates.test.mjs index 72dabb587f..aca5ab81f1 100644 --- a/packages/cli/src/media-use/lib/candidates.test.mjs +++ b/packages/cli/src/media-use/lib/candidates.test.mjs @@ -153,3 +153,19 @@ test("formatCandidates shows reuse handles by scope; empty message", () => { assert.match(out, /--reuse ffffffffffffffff/); assert.match(formatCandidates([], {}), /no reuse candidates/); }); + +test("formatCandidates prints control characters from the manifest as visible escapes", () => { + const text = formatCandidates([ + { + scope: "project", + id: "bgm_001", + path: ".media/audio/bgm/\x1b[2Kbgm_001.wav", + description: "calm piano\x1b]52;c;aGk=\x07", + score: 1, + }, + ]); + assert.ok(text.includes("calm piano\\x1b]52;c;aGk=\\x07"), text); + assert.ok(text.includes(".media/audio/bgm/\\x1b[2Kbgm_001.wav"), text); + for (const raw of ["\x07", "\x1b"]) + assert.ok(!text.includes(raw), "no raw control character is left"); +}); diff --git a/packages/cli/src/media-use/lib/terminal-text.d.mts b/packages/cli/src/media-use/lib/terminal-text.d.mts new file mode 100644 index 0000000000..de0c2c20c0 --- /dev/null +++ b/packages/cli/src/media-use/lib/terminal-text.d.mts @@ -0,0 +1 @@ +export function terminalText(value: unknown): string; diff --git a/packages/cli/src/media-use/lib/terminal-text.mjs b/packages/cli/src/media-use/lib/terminal-text.mjs new file mode 100644 index 0000000000..7cd7d9b80a --- /dev/null +++ b/packages/cli/src/media-use/lib/terminal-text.mjs @@ -0,0 +1,12 @@ +// The media-use engine runs without the CLI's packages installed, so it keeps its own copy of +// core's terminalText: control characters print as visible \xNN escapes, tabs stay as they are. +const isControlCode = (code) => (code < 0x20 && code !== 0x09) || (code >= 0x7f && code <= 0x9f); + +export function terminalText(value) { + let shown = ""; + for (const ch of String(value)) { + const code = ch.charCodeAt(0); + shown += isControlCode(code) ? `\\x${code.toString(16).padStart(2, "0")}` : ch; + } + return shown; +} diff --git a/packages/cli/src/media-use/resolve.mjs b/packages/cli/src/media-use/resolve.mjs index 3cbe0f1675..fe79c9356f 100644 --- a/packages/cli/src/media-use/resolve.mjs +++ b/packages/cli/src/media-use/resolve.mjs @@ -69,6 +69,7 @@ import { scoreMatch, } from "./lib/sfx-provider.mjs"; import { writeSfxCredit } from "./lib/openverse.mjs"; +import { terminalText } from "./lib/terminal-text.mjs"; import { mediaVectorRows, rankMediaRowsWithVectors } from "./lib/local-media-search.mjs"; const INGEST_TYPES = listTypes(); @@ -179,7 +180,7 @@ if (args.adopt) { console.log("no new assets to adopt (assets/ empty or already registered)"); } else { console.log(`adopted ${adopted.length} asset${adopted.length === 1 ? "" : "s"} from assets/`); - for (const r of adopted) console.log(` ${r.id} → ${r.path} (${r.type})`); + for (const r of adopted) console.log(terminalText(` ${r.id} → ${r.path} (${r.type})`)); } process.exit(0); } @@ -280,11 +281,14 @@ if (type === "recipe") { console.log(JSON.stringify({ ok: true, ...used })); } else { console.log( - `resolved recipe ${used.recipe.name} (v${used.recipe.version}, ${used.recipe.workflow})`, + terminalText( + `resolved recipe ${used.recipe.name} (v${used.recipe.version}, ${used.recipe.workflow})`, + ), ); - console.log(` frame spec → ${used.frameSpecPath} (copied over)`); - console.log(` storyboard skeleton → ${used.skeletonPath}`); - if (used.briefSkeletonPath) console.log(` brief skeleton → ${used.briefSkeletonPath}`); + console.log(terminalText(` frame spec → ${used.frameSpecPath} (copied over)`)); + console.log(terminalText(` storyboard skeleton → ${used.skeletonPath}`)); + if (used.briefSkeletonPath) + console.log(terminalText(` brief skeleton → ${used.briefSkeletonPath}`)); } process.exit(0); } catch (err) { @@ -553,7 +557,7 @@ async function run() { }), ); } else { - console.error(`error: ${msg}`); + console.error(terminalText(`error: ${msg}`)); } process.exit(1); } @@ -671,7 +675,7 @@ function exitError(message, status = 1) { if (args.json) { console.log(JSON.stringify({ ok: false, error: message })); } else { - console.error(`error: ${message}`); + console.error(terminalText(`error: ${message}`)); } process.exit(status); } @@ -743,7 +747,7 @@ async function colorMiss(type, intent) { if (args.json) { console.log(JSON.stringify({ ok: false, error: msg })); } else { - console.error(`error: ${msg}`); + console.error(terminalText(`error: ${msg}`)); } process.exit(1); } @@ -1184,8 +1188,8 @@ function printStats(report) { return; } for (const [type, misses] of entries) { - console.log(` ${type}:`); - for (const miss of misses) console.log(` ${miss.count} ${miss.intent}`); + console.log(terminalText(` ${type}:`)); + for (const miss of misses) console.log(terminalText(` ${miss.count} ${miss.intent}`)); } } @@ -1196,7 +1200,7 @@ function printMap(label, values) { console.log(" none"); return; } - for (const [key, value] of entries) console.log(` ${key}: ${value}`); + for (const [key, value] of entries) console.log(terminalText(` ${key}: ${value}`)); } function ffDoctorCheck(name, binary) { @@ -1280,7 +1284,7 @@ async function reuseGlobal(shaArg) { } // Do not import an asset under the wrong type. if (!typesMatch(rec.type, type)) { - console.error(`error: sha "${shaArg}" is a ${rec.type} asset, not ${type}`); + console.error(terminalText(`error: sha "${shaArg}" is a ${rec.type} asset, not ${type}`)); process.exit(2); } const ext = extname(rec.cached_path || "") || defaultExt(type); @@ -1308,7 +1312,9 @@ function warnLowConfidence(record, match) { ? `found by its file name, resolved earlier for "${match.resolved_for}"` : `found by its file name, sharing ${match.matched_words.length} of ${match.intent_words} words`; console.error( - `media-use: low-confidence match for "${intent}": ${record.description || record.path} (${why}). Listen before placing it, or resolve again with other words.`, + terminalText( + `media-use: low-confidence match for "${intent}": ${record.description || record.path} (${why}). Listen before placing it, or resolve again with other words.`, + ), ); } @@ -1367,7 +1373,7 @@ async function result(record, source, match = recordedMatch(record)) { ); } else { const meta = formatMeta(record, source); - console.log(`resolved ${record.id} → ${record.path || "inline"} (${meta})`); + console.log(terminalText(`resolved ${record.id} → ${record.path || "inline"} (${meta})`)); } } @@ -1399,7 +1405,7 @@ run().catch((err) => { if (args.json) { console.log(JSON.stringify({ ok: false, error: err.message })); } else { - console.error(`error: ${err.message}`); + console.error(terminalText(`error: ${err.message}`)); } process.exit(1); }); diff --git a/packages/cli/src/media-use/resolve.test.mjs b/packages/cli/src/media-use/resolve.test.mjs index 09a0ebb107..0ed1c36437 100644 --- a/packages/cli/src/media-use/resolve.test.mjs +++ b/packages/cli/src/media-use/resolve.test.mjs @@ -524,6 +524,67 @@ test("project manifest hit skips providers", () => { cleanup(); }); +test("a manifest hit prints control characters from the record as visible escapes", () => { + setup(); + const record = makeRecord({ + id: "bgm_001\x1b]52;c;aGk=\x07", + provenance: { prompt: "cached query", provider: "test" }, + }); + appendRecord(tmp, record); + const filePath = join(tmp, record.path); + mkdirSync(join(filePath, ".."), { recursive: true }); + writeFileSync(filePath, "cached audio"); + + const out = runResolve(["--type", "bgm", "--intent", "cached query", "--project", tmp]); + assert.ok(out.includes("resolved bgm_001\\x1b]52;c;aGk=\\x07 →"), out); + for (const raw of ["\x07", "\x1b"]) + assert.ok(!out.includes(raw), "no raw control character reaches the terminal"); + const json = JSON.parse( + runResolve(["--type", "bgm", "--intent", "cached query", "--project", tmp, "--json"]).trim(), + ); + assert.equal(json.id, record.id, "--json keeps the record as it is"); + cleanup(); +}); + +test("recipe and stats output print control characters as visible escapes", () => { + setup(); + try { + const recipe = join(tmp, ".media", "recipes", "promo"); + mkdirSync(recipe, { recursive: true }); + const name = "promo\x1b[2K"; + writeFileSync( + join(recipe, "recipe.json"), + JSON.stringify({ name, version: 1, workflow: "w\x07" }), + ); + writeFileSync(join(recipe, "frame.md"), "# frame\n"); + const used = runResolve(["--type", "recipe", "--entity", "promo", "--project", tmp]); + assert.ok(used.includes("resolved recipe promo\\x1b[2K (v1, w\\x07)"), used); + + const missing = spawnResolve(["--type", "recipe", "--entity", "nope", "--project", tmp]); + assert.notEqual(missing.status, 0); + assert.ok(missing.stderr.includes("known: promo\\x1b[2K"), missing.stderr); + for (const raw of ["\x07", "\x1b"]) + assert.ok(!missing.stderr.includes(raw), "no raw control character reaches the terminal"); + + const home = join(process.env.HYPERFRAMES_MEDIA_HOME, ".media"); + mkdirSync(home, { recursive: true }); + const miss = { + ts: new Date().toISOString(), + type: "sfx\x1b[8m", + intent: "boom\x1b]52;c;agk=\x07", + }; + writeFileSync(join(home, "misses.jsonl"), `${JSON.stringify(miss)}\n`); + const stats = runResolve(["--stats", "--project", tmp]); + assert.ok(stats.includes(" sfx\\x1b[8m:"), stats); + assert.ok(stats.includes("boom\\x1b]52;c;agk=\\x07"), stats); + for (const out of [used, stats]) + for (const raw of ["\x07", "\x1b"]) + assert.ok(!out.includes(raw), "no raw control character reaches the terminal"); + } finally { + cleanup(); + } +}); + test("entity hit matches across icon/image (figma-imported brand marks)", () => { setup(); const record = makeRecord({ diff --git a/packages/cli/src/media-use/terminalText.parity.test.ts b/packages/cli/src/media-use/terminalText.parity.test.ts new file mode 100644 index 0000000000..ee0ba94cb4 --- /dev/null +++ b/packages/cli/src/media-use/terminalText.parity.test.ts @@ -0,0 +1,10 @@ +import { terminalText as coreTerminalText } from "@hyperframes/core"; +import { expect, it } from "vitest"; +import { terminalText } from "./lib/terminal-text.mjs"; + +it("the media-use copy of terminalText escapes every character as core's does", () => { + for (let code = 0; code <= 0xa0; code++) { + const text = `a${String.fromCharCode(code)}b`; + expect(terminalText(text), `U+${code.toString(16)}`).toBe(coreTerminalText(text)); + } +}); diff --git a/packages/cli/src/tts/manager.pin.test.ts b/packages/cli/src/tts/manager.pin.test.ts new file mode 100644 index 0000000000..50d3111cfe --- /dev/null +++ b/packages/cli/src/tts/manager.pin.test.ts @@ -0,0 +1,78 @@ +import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { afterAll, afterEach, expect, it, vi } from "vitest"; +import { ensureModel, ensureVoices } from "./manager.js"; + +const cache = await vi.hoisted(async () => { + const { mkdtempSync } = await import("node:fs"); + const { tmpdir } = await import("node:os"); + const dir = mkdtempSync(`${tmpdir()}/hf-tts-pin-`); + process.env["HYPERFRAMES_CACHE_DIR"] = dir; + return dir; +}); +vi.mock("../utils/download.js", () => ({ + downloadFile: vi.fn( + async ( + _url: string, + dest: string, + options: { + keepExisting: (path: string) => Promise; + verify: (path: string) => Promise; + }, + ) => { + if (await options.keepExisting(dest)) return; + rmSync(dest, { force: true }); + writeFileSync(`${dest}.part`, "swapped"); + await options.verify(`${dest}.part`).catch((error: unknown) => { + rmSync(`${dest}.part`); + throw error; + }); + renameSync(`${dest}.part`, dest); + }, + ), +})); + +const model = join(cache, "tts", "models", "kokoro-v1.0.onnx"); +const voices = join(cache, "tts", "voices", "voices-v1.0.bin"); + +afterEach(() => rmSync(cache, { recursive: true, force: true })); +afterAll(() => { + delete process.env["HYPERFRAMES_CACHE_DIR"]; +}); + +it.each([ + [ + "model", + () => ensureModel(), + model, + /kokoro-v1\.0\.onnx was discarded because it does not match/, + ], + [ + "voices", + () => ensureVoices(), + voices, + /voices-v1\.0\.bin was discarded because it does not match/, + ], +])( + "refuses a downloaded %s file that does not match the pinned sha256", + async (_k, run, path, error) => { + await expect(run()).rejects.toThrow(error); + + expect(existsSync(path)).toBe(false); + }, +); + +it.each([ + ["model", () => ensureModel(), model], + ["voices", () => ensureVoices(), voices], +])( + "does not load a cached %s file that does not match the pinned sha256", + async (_k, run, path) => { + mkdirSync(join(path, ".."), { recursive: true }); + writeFileSync(path, "swapped"); + + await expect(run()).rejects.toThrow(/was discarded because it does not match/); + + expect(existsSync(path)).toBe(false); + }, +); diff --git a/packages/cli/src/tts/manager.ts b/packages/cli/src/tts/manager.ts index 6181aedf43..900df3983f 100644 --- a/packages/cli/src/tts/manager.ts +++ b/packages/cli/src/tts/manager.ts @@ -1,6 +1,6 @@ -import { existsSync, mkdirSync } from "node:fs"; import { join } from "node:path"; -import { downloadFile } from "../utils/download.js"; +import { ensurePinnedFile } from "../utils/pinnedFile.js"; +import type { ModelFile } from "../whisper/modelFile.js"; import { hyperframesCacheDir } from "@hyperframes/core/cache-dir"; const CACHE_DIR = hyperframesCacheDir("tts"); @@ -14,9 +14,23 @@ const MODEL_URLS: Record = { "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/kokoro-v1.0.onnx", }; +const MODEL_PINS: Record = { + "kokoro-v1.0": { + name: "kokoro-v1.0.onnx", + bytes: 325_532_387, + sha256: "7d5df8ecf7d4b1878015a32686053fd0eebe2bc377234608764cc0ef3636a6c5", + }, +}; + const VOICES_URL = "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/voices-v1.0.bin"; +const VOICES_PIN: ModelFile = { + name: "voices-v1.0.bin", + bytes: 28_214_398, + sha256: "bca610b8308e8d99f32e6fe4197e7ec01679264efed0cac9140fe9c29f1fbf7d", +}; + // Locale codes accepted by Kokoro's phonemizer (misaki for English, // espeak-ng for everything else). Kept as a readonly tuple so the union // type below stays driven by this single source. @@ -103,25 +117,18 @@ export async function ensureModel( model: string = DEFAULT_MODEL, options?: { onProgress?: (message: string) => void }, ): Promise { - const modelPath = join(MODELS_DIR, `${model}.onnx`); - if (existsSync(modelPath)) return modelPath; - const url = MODEL_URLS[model]; - if (!url) { + const pin = MODEL_PINS[model]; + if (!url || !pin) { throw new Error( `Unknown TTS model: ${model}. Available: ${Object.keys(MODEL_URLS).join(", ")}`, ); } - mkdirSync(MODELS_DIR, { recursive: true }); - options?.onProgress?.(`Downloading TTS model ${model} (~311 MB)...`); - await downloadFile(url, modelPath); - - if (!existsSync(modelPath)) { - throw new Error(`Model download failed: ${model}`); - } - - return modelPath; + return ensurePinnedFile(url, join(MODELS_DIR, `${model}.onnx`), pin, { + downloading: `Downloading TTS model ${model} (~311 MB)...`, + onProgress: options?.onProgress, + }); } /** @@ -131,18 +138,10 @@ export async function ensureModel( export async function ensureVoices(options?: { onProgress?: (message: string) => void; }): Promise { - const voicesPath = join(VOICES_DIR, "voices-v1.0.bin"); - if (existsSync(voicesPath)) return voicesPath; - - mkdirSync(VOICES_DIR, { recursive: true }); - options?.onProgress?.("Downloading voice data (~27 MB)..."); - await downloadFile(VOICES_URL, voicesPath); - - if (!existsSync(voicesPath)) { - throw new Error("Voice data download failed"); - } - - return voicesPath; + return ensurePinnedFile(VOICES_URL, join(VOICES_DIR, VOICES_PIN.name), VOICES_PIN, { + downloading: "Downloading voice data (~27 MB)...", + onProgress: options?.onProgress, + }); } export { MODELS_DIR, DEFAULT_MODEL }; diff --git a/packages/cli/src/utils/download.test.ts b/packages/cli/src/utils/download.test.ts index e37f07e2d7..bb1bc3ffd8 100644 --- a/packages/cli/src/utils/download.test.ts +++ b/packages/cli/src/utils/download.test.ts @@ -693,6 +693,43 @@ describe("resuming across runs", () => { expect(readdirSync(dir)).toEqual(["model.onnx"]); }); + it("checks a file already at dest under the lock, and replaces it when the check refuses", async () => { + const dir = mkdtempSync(join(tmpdir(), "hyperframes-download-")); + tempDirs.push(dir); + const dest = join(dir, "model.onnx"); + writeFileSync(dest, "stale"); + mockGet.mockImplementation(rangedHost("hello", '"v1"', [])); + const locked: boolean[] = []; + const keep = async (path: string) => { + locked.push(readdirSync(dir).includes("model.onnx.lock")); + return readFileSync(path, "utf8") === "hello"; + }; + + await downloadFile(url, dest, { keepExisting: keep }); + expect(readFileSync(dest, "utf8")).toBe("hello"); + await downloadFile(url, dest, { keepExisting: keep }); + + expect(mockGet).toHaveBeenCalledTimes(1); + expect(locked).toEqual([true, true]); + }); + + it("removes a refused file at dest when the fresh download is refused too", async () => { + const dir = mkdtempSync(join(tmpdir(), "hyperframes-download-")); + tempDirs.push(dir); + const dest = join(dir, "model.onnx"); + writeFileSync(dest, "stale"); + mockGet.mockImplementation(rangedHost("hello", '"v1"', [])); + + await expect( + downloadFile(url, dest, { + keepExisting: async () => false, + verify: async () => Promise.reject(new Error("bad sha")), + }), + ).rejects.toThrow("bad sha"); + + expect(readdirSync(dir)).toEqual([]); + }); + it("discards a finished file its check refuses", async () => { const { dir, dest } = stoppedRun("hel", '"v1"'); mockGet.mockImplementation(rangedHost("hello", '"v1"', [])); diff --git a/packages/cli/src/utils/download.ts b/packages/cli/src/utils/download.ts index 53b66855b0..e61c146e42 100644 --- a/packages/cli/src/utils/download.ts +++ b/packages/cli/src/utils/download.ts @@ -33,6 +33,7 @@ export interface DownloadOptions { signal?: AbortSignal; /** Checks the finished file before it replaces `dest`; a throw discards it. */ verify?: (path: string) => Promise; + keepExisting?: (path: string) => Promise; } /** Every redirect a host may reasonably answer with, not just the two we saw first. */ @@ -425,6 +426,18 @@ async function downloadToPart(url: string, dest: string, options: DownloadOption await publishPart(part, dest, options); } +async function keepsDest( + dest: string, + waited: boolean, + options: DownloadOptions, +): Promise { + if (!existsSync(dest)) return false; + if (!options.keepExisting) return waited; + if (await options.keepExisting(dest)) return true; + removePartialFile(dest); + return false; +} + /** * Some networks drop every connection at the same byte, so a retry resumes from the partial file. * The partial file and its validator survive a stopped run, so the next run resumes it too. @@ -437,7 +450,7 @@ export async function downloadFile( const lock = `${dest}.lock`; const { owner, waited } = await acquireLock(lock, options.signal); try { - if (!(waited && existsSync(dest))) await downloadToPart(url, dest, options); + if (!(await keepsDest(dest, waited, options))) await downloadToPart(url, dest, options); } finally { heldLocks.delete(owner); if (readLock(lock) === owner) removePartialFile(lock); diff --git a/packages/cli/src/utils/pinnedFile.test.ts b/packages/cli/src/utils/pinnedFile.test.ts new file mode 100644 index 0000000000..ba23768738 --- /dev/null +++ b/packages/cli/src/utils/pinnedFile.test.ts @@ -0,0 +1,100 @@ +import { createHash } from "node:crypto"; +import { + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + readdirSync, + renameSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, beforeEach, expect, it, vi } from "vitest"; +import { downloadFile } from "./download.js"; +import { ensurePinnedFile } from "./pinnedFile.js"; + +const served = vi.hoisted(() => ({ bytes: "model" })); +vi.mock("./download.js", () => ({ + downloadFile: vi.fn( + async ( + _url: string, + dest: string, + options: { + keepExisting: (path: string) => Promise; + verify: (path: string) => Promise; + }, + ) => { + if (await options.keepExisting(dest)) return; + rmSync(dest, { force: true }); + writeFileSync(`${dest}.part`, served.bytes); + await options.verify(`${dest}.part`).catch((error: unknown) => { + rmSync(`${dest}.part`); + throw error; + }); + renameSync(`${dest}.part`, dest); + }, + ), +})); + +let dir = ""; +let dest = ""; +const pin = { + name: "model.onnx", + bytes: 5, + sha256: createHash("sha256").update("model").digest("hex"), +}; +const progress = { downloading: "Downloading model..." }; + +beforeEach(() => { + served.bytes = "model"; + dir = mkdtempSync(join(tmpdir(), "hf-pinned-file-")); + dest = join(dir, "models", "model.onnx"); +}); +afterEach(() => { + rmSync(dir, { recursive: true, force: true }); + vi.clearAllMocks(); +}); + +it("uses a cached file that matches its pin without downloading it", async () => { + mkdirSync(join(dir, "models")); + writeFileSync(dest, "model"); + + await expect(ensurePinnedFile("https://x.test/m", dest, pin, progress)).resolves.toBe(dest); + + expect(downloadFile).not.toHaveBeenCalled(); +}); + +it("downloads a file that matches its pin", async () => { + await expect(ensurePinnedFile("https://x.test/m", dest, pin, progress)).resolves.toBe(dest); + + expect(readFileSync(dest, "utf8")).toBe("model"); +}); + +it("replaces a cached file of the same size that does not match its pin", async () => { + mkdirSync(join(dir, "models")); + writeFileSync(dest, "other"); + const onProgress = vi.fn(); + + await ensurePinnedFile("https://x.test/m", dest, pin, { ...progress, onProgress }); + + expect(readFileSync(dest, "utf8")).toBe("model"); + expect(onProgress).toHaveBeenCalledWith( + "The cached model.onnx does not match its pinned sha256; downloading it again...", + ); +}); + +it("discards a download that does not match its pin and refuses it", async () => { + served.bytes = "swapped"; + mkdirSync(join(dir, "models")); + writeFileSync(dest, "other"); + + await expect(ensurePinnedFile("https://x.test/m", dest, pin, progress)).rejects.toThrow( + "model.onnx was discarded because it does not match its expected size and sha256. " + + "Retrying helps only if the download was interrupted or corrupted.", + ); + + expect(existsSync(dest)).toBe(false); + expect(readdirSync(join(dir, "models"))).toEqual([]); +}); diff --git a/packages/cli/src/utils/pinnedFile.ts b/packages/cli/src/utils/pinnedFile.ts new file mode 100644 index 0000000000..0c8c32711f --- /dev/null +++ b/packages/cli/src/utils/pinnedFile.ts @@ -0,0 +1,37 @@ +import { mkdirSync, statSync } from "node:fs"; +import { dirname } from "node:path"; +import { verifies, type ModelFile } from "../whisper/modelFile.js"; +import { downloadFile } from "./download.js"; + +/** + * `dest` once it holds the pinned bytes: a cached copy that matches is used as it is, any other + * copy is replaced by a fresh download, and a download that does not match is discarded. + */ +export async function ensurePinnedFile( + url: string, + dest: string, + pin: ModelFile, + progress: { downloading: string; onProgress?: (message: string) => void }, +): Promise { + const cached = statSync(dest, { throwIfNoEntry: false }) !== undefined; + if (cached && (await verifies(dest, pin))) return dest; + + mkdirSync(dirname(dest), { recursive: true }); + progress.onProgress?.( + cached + ? `The cached ${pin.name} does not match its pinned sha256; downloading it again...` + : progress.downloading, + ); + await downloadFile(url, dest, { + keepExisting: (path) => verifies(path, pin), + verify: async (path) => { + if (!(await verifies(path, pin))) { + throw new Error( + `${pin.name} was discarded because it does not match its expected size and sha256. ` + + "Retrying helps only if the download was interrupted or corrupted.", + ); + } + }, + }); + return dest; +}