Skip to content

Write HTML. Render video. Built for agents.

fix(media-use): a slow download no longer leaves an empty asset that undo brings back (#4989)

Miguel Ángel18a922f43342
diff --git a/packages/cli/src/media-use/lib/manifest.d.mts b/packages/cli/src/media-use/lib/manifest.d.mts
new file mode 100644
index 0000000000..d60c1cd397
--- /dev/null
+++ b/packages/cli/src/media-use/lib/manifest.d.mts
@@ -0,0 +1,19 @@
+export interface Reservation {
+ id: string;
+ localPath: string;
+ markerPath: string;
+ fullPath: string;
+}
+
+export function typeDirPath(projectDir: string, type: string): string;
+export function allocateId(
+ projectDir: string,
+ type: string,
+ ext: string,
+): Omit<Reservation, "fullPath">;
+export function withReservedFileSync<T>(
+ projectDir: string,
+ type: string,
+ ext: string,
+ populate: (reservation: Reservation) => T,
+): T;
diff --git a/packages/cli/src/media-use/lib/manifest.mjs b/packages/cli/src/media-use/lib/manifest.mjs
index 49e387690f..fcdbd771f7 100644
--- a/packages/cli/src/media-use/lib/manifest.mjs
+++ b/packages/cli/src/media-use/lib/manifest.mjs
@@ -10,6 +10,7 @@ import {
rmSync,
statSync,
} from "node:fs";
+import { randomBytes } from "node:crypto";
import { basename, join } from "node:path";
const MANIFEST_FILE = "manifest.jsonl";
@@ -202,12 +203,12 @@ function withLock(dir, fn) {
}
}
-// Atomically allocate the next free id for `type` AND reserve its file, so a
+// Atomically allocate the next free id for `type` AND reserve it on disk, so a
// slow download/copy between allocation and appendRecord can't let a concurrent
// caller grab the same id (the MU-23 clobber). Under the lock we take the max id
// across BOTH the manifest and any already-reserved files in the type dir, then
-// O_EXCL-create an empty placeholder at the target path; freeze/copy overwrites
-// it. Returns { id, localPath }.
+// O_EXCL-create an empty marker under core's atomic temp name, which Studio's
+// project history skips. Returns { id, localPath, markerPath }.
export function allocateId(projectDir, type, ext) {
mkdirSync(mediaDir(projectDir), { recursive: true });
const typeDir = typeDirPath(projectDir, type);
@@ -215,8 +216,10 @@ export function allocateId(projectDir, type, ext) {
return withLock(mediaDir(projectDir), () => {
const id = nextFreeId(projectDir, type);
const localPath = `.media/${typeSubdir(type)}/${id}${ext}`;
- writeFileSync(join(projectDir, localPath), "", { flag: "wx" }); // durable reservation
- return { id, localPath };
+ // Same shape as core atomicTempPath: an empty file at the final name would be committed.
+ const markerPath = `${join(projectDir, localPath)}.hf${randomBytes(3).toString("hex")}.tmp`;
+ writeFileSync(markerPath, "", { flag: "wx" }); // durable reservation
+ return { id, localPath, markerPath };
});
}
@@ -242,22 +245,23 @@ function reservedFile(projectDir, type, ext) {
return { ...allocation, fullPath: join(projectDir, allocation.localPath) };
}
-function rollbackReservation(reservation) {
- rmSync(reservation.fullPath, { force: true });
+function releaseReservation(reservation, committed) {
+ if (!committed) rmSync(reservation.fullPath, { force: true });
+ rmSync(reservation.markerPath, { force: true });
}
// A reservation is committed only when populate returns a non-null value.
// Throwing/rejecting or returning null means no usable asset was produced, so
-// the placeholder must be released. Keeping this transaction beside allocateId
-// prevents individual provider/cache/LUT paths from forgetting the rollback.
+// the reservation and any partial asset are released. Keeping this transaction
+// beside allocateId prevents provider/cache/LUT paths from forgetting the rollback.
export function withReservedFileSync(projectDir, type, ext, populate) {
const reservation = reservedFile(projectDir, type, ext);
try {
const result = populate(reservation);
- if (result == null) rollbackReservation(reservation);
+ releaseReservation(reservation, result != null);
return result;
} catch (error) {
- rollbackReservation(reservation);
+ releaseReservation(reservation, false);
throw error;
}
}
@@ -266,10 +270,10 @@ export async function withReservedFile(projectDir, type, ext, populate) {
const reservation = reservedFile(projectDir, type, ext);
try {
const result = await populate(reservation);
- if (result == null) rollbackReservation(reservation);
+ releaseReservation(reservation, result != null);
return result;
} catch (error) {
- rollbackReservation(reservation);
+ releaseReservation(reservation, false);
throw error;
}
}
diff --git a/packages/cli/src/media-use/lib/manifest.test.mjs b/packages/cli/src/media-use/lib/manifest.test.mjs
index 348240fdf3..18b0c18c05 100644
--- a/packages/cli/src/media-use/lib/manifest.test.mjs
+++ b/packages/cli/src/media-use/lib/manifest.test.mjs
@@ -100,7 +100,7 @@ function runTests() {
setup();
const allocated = allocateId(tmp, "lut", ".cube");
assert.equal(allocated.localPath, ".media/luts/lut_001.cube");
- assert.ok(existsSync(join(tmp, allocated.localPath)));
+ assert.ok(existsSync(allocated.markerPath));
cleanup();
});
@@ -157,7 +157,8 @@ function runTests() {
setup();
const a = allocateId(tmp, "bgm", ".wav");
assert.equal(a.id, "bgm_001");
- assert.ok(existsSync(join(tmp, a.localPath)), "placeholder reserved on disk");
+ assert.ok(existsSync(a.markerPath), "id reserved on disk");
+ assert.ok(!existsSync(join(tmp, a.localPath)), "no empty asset at the final name");
// Second allocation BEFORE any manifest append (the download window) must not
// hand back bgm_001 again, even with a different extension.
const b = allocateId(tmp, "bgm", ".mp3");
diff --git a/packages/cli/src/media-use/manifestReservation.test.ts b/packages/cli/src/media-use/manifestReservation.test.ts
new file mode 100644
index 0000000000..9376af04ff
--- /dev/null
+++ b/packages/cli/src/media-use/manifestReservation.test.ts
@@ -0,0 +1,43 @@
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { isAtomicTempPath } from "@hyperframes/core/atomic-file";
+import { allocateId, typeDirPath, withReservedFileSync } from "./lib/manifest.mjs";
+
+// Studio's project history commits outside changes after a quiet time but skips atomic temp
+// names (core isAtomicTempPath); a reserved-but-empty asset it commits comes back 0-byte on undo.
+describe("media-use id reservation", () => {
+ let project: string;
+ beforeEach(() => {
+ project = mkdtempSync(join(tmpdir(), "hf-media-reserve-"));
+ });
+ afterEach(() => {
+ rmSync(project, { recursive: true, force: true });
+ });
+
+ it("shows only a temp name until the asset is written, and still holds the id", () => {
+ const typeDir = typeDirPath(project, "bgm");
+ const kept = withReservedFileSync(project, "bgm", ".wav", (reservation) => {
+ expect(readdirSync(typeDir).filter((name) => !isAtomicTempPath(name))).toEqual([]);
+ expect(allocateId(project, "bgm", ".wav").id).toBe("bgm_002");
+ writeFileSync(reservation.fullPath, "completed asset");
+ return reservation;
+ });
+
+ expect(kept.id).toBe("bgm_001");
+ expect(readdirSync(typeDir).filter((name) => name.startsWith("bgm_001"))).toEqual([
+ "bgm_001.wav",
+ ]);
+ });
+
+ it("leaves nothing behind when the download fails partway", () => {
+ expect(() =>
+ withReservedFileSync(project, "image", ".jpg", (reservation) => {
+ writeFileSync(reservation.fullPath, "partial");
+ throw new Error("download failed");
+ }),
+ ).toThrow("download failed");
+ expect(readdirSync(typeDirPath(project, "image"))).toEqual([]);
+ });
+});
diff --git a/skills-manifest.json b/skills-manifest.json
index 0b2c8a84fe..b7af1979e8 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -54,7 +54,7 @@
"files": 1
},
"media-use": {
- "hash": "5d688d039d31df92",
+ "hash": "08bff9e1bf006d4b",
"files": 104
},
"motion-graphics": {
diff --git a/skills/media-use/SKILL.md b/skills/media-use/SKILL.md
index 4a56e599cd..ec0d30ec1e 100644
--- a/skills/media-use/SKILL.md
+++ b/skills/media-use/SKILL.md
@@ -11,6 +11,8 @@ The media OS for HyperFrames: resolve · generate · operate · remember — eve
First run: install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.
+Before generating a voiceover or an avatar video, tell the person: signing in to the heygen CLI with OAuth (`heygen auth login --oauth`) gives a free allowance for TTS voiceover and avatar videos, while an API key bills API credits.
+
## Resolve — the one verb
```bash
diff --git a/skills/media-use/scripts/lib/manifest.mjs b/skills/media-use/scripts/lib/manifest.mjs
index 49e387690f..fcdbd771f7 100644
--- a/skills/media-use/scripts/lib/manifest.mjs
+++ b/skills/media-use/scripts/lib/manifest.mjs
@@ -10,6 +10,7 @@ import {
rmSync,
statSync,
} from "node:fs";
+import { randomBytes } from "node:crypto";
import { basename, join } from "node:path";
const MANIFEST_FILE = "manifest.jsonl";
@@ -202,12 +203,12 @@ function withLock(dir, fn) {
}
}
-// Atomically allocate the next free id for `type` AND reserve its file, so a
+// Atomically allocate the next free id for `type` AND reserve it on disk, so a
// slow download/copy between allocation and appendRecord can't let a concurrent
// caller grab the same id (the MU-23 clobber). Under the lock we take the max id
// across BOTH the manifest and any already-reserved files in the type dir, then
-// O_EXCL-create an empty placeholder at the target path; freeze/copy overwrites
-// it. Returns { id, localPath }.
+// O_EXCL-create an empty marker under core's atomic temp name, which Studio's
+// project history skips. Returns { id, localPath, markerPath }.
export function allocateId(projectDir, type, ext) {
mkdirSync(mediaDir(projectDir), { recursive: true });
const typeDir = typeDirPath(projectDir, type);
@@ -215,8 +216,10 @@ export function allocateId(projectDir, type, ext) {
return withLock(mediaDir(projectDir), () => {
const id = nextFreeId(projectDir, type);
const localPath = `.media/${typeSubdir(type)}/${id}${ext}`;
- writeFileSync(join(projectDir, localPath), "", { flag: "wx" }); // durable reservation
- return { id, localPath };
+ // Same shape as core atomicTempPath: an empty file at the final name would be committed.
+ const markerPath = `${join(projectDir, localPath)}.hf${randomBytes(3).toString("hex")}.tmp`;
+ writeFileSync(markerPath, "", { flag: "wx" }); // durable reservation
+ return { id, localPath, markerPath };
});
}
@@ -242,22 +245,23 @@ function reservedFile(projectDir, type, ext) {
return { ...allocation, fullPath: join(projectDir, allocation.localPath) };
}
-function rollbackReservation(reservation) {
- rmSync(reservation.fullPath, { force: true });
+function releaseReservation(reservation, committed) {
+ if (!committed) rmSync(reservation.fullPath, { force: true });
+ rmSync(reservation.markerPath, { force: true });
}
// A reservation is committed only when populate returns a non-null value.
// Throwing/rejecting or returning null means no usable asset was produced, so
-// the placeholder must be released. Keeping this transaction beside allocateId
-// prevents individual provider/cache/LUT paths from forgetting the rollback.
+// the reservation and any partial asset are released. Keeping this transaction
+// beside allocateId prevents provider/cache/LUT paths from forgetting the rollback.
export function withReservedFileSync(projectDir, type, ext, populate) {
const reservation = reservedFile(projectDir, type, ext);
try {
const result = populate(reservation);
- if (result == null) rollbackReservation(reservation);
+ releaseReservation(reservation, result != null);
return result;
} catch (error) {
- rollbackReservation(reservation);
+ releaseReservation(reservation, false);
throw error;
}
}
@@ -266,10 +270,10 @@ export async function withReservedFile(projectDir, type, ext, populate) {
const reservation = reservedFile(projectDir, type, ext);
try {
const result = await populate(reservation);
- if (result == null) rollbackReservation(reservation);
+ releaseReservation(reservation, result != null);
return result;
} catch (error) {
- rollbackReservation(reservation);
+ releaseReservation(reservation, false);
throw error;
}
}