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; +}