Skip to content

Write HTML. Render video. Built for agents.

fix(cli): recover stale media cache entries (#5269)

Abdullah M. Nazifb1aa71d7d500
diff --git a/packages/cli/src/media-use/lib/cache.mjs b/packages/cli/src/media-use/lib/cache.mjs
index adcc895d90..768488b560 100644
--- a/packages/cli/src/media-use/lib/cache.mjs
+++ b/packages/cli/src/media-use/lib/cache.mjs
@@ -1,4 +1,11 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from "node:fs";
+import {
+ readFileSync,
+ writeFileSync,
+ mkdirSync,
+ existsSync,
+ copyFileSync,
+ statSync,
+} from "node:fs";
import { join, basename } from "node:path";
import { createHash } from "node:crypto";
import { readManifest, appendRecord, normalizePrompt } from "./manifest.mjs";
@@ -45,9 +52,10 @@ export function findGlobalBySha(shaPrefix) {
.toLowerCase()
.trim();
if (!p) return null;
- const matches = readGlobalManifest().filter(
+ const matchingRecords = readGlobalManifest().filter(
(r) => r.reusable && typeof r.sha === "string" && r.sha.startsWith(p),
);
+ const matches = Array.from(new Map(matchingRecords.map((r) => [r.sha, r])).values());
if (matches.length === 0) return null;
if (matches.length > 1) {
const exact = matches.find((r) => r.sha === p);
@@ -58,27 +66,36 @@ export function findGlobalBySha(shaPrefix) {
}
function validateCacheHit(match) {
- if (!match?.sha) return null;
- return isComplete(cacheEntryDir(globalMediaDir(), match.sha)) ? match : null;
+ if (!match?.sha || !match.cached_path) return null;
+ if (!isComplete(cacheEntryDir(globalMediaDir(), match.sha))) return null;
+ try {
+ const file = statSync(match.cached_path);
+ return file.isFile() && file.size > 0 ? match : null;
+ } catch {
+ return null;
+ }
}
export function cacheGet(prompt, type) {
const key = normalizePrompt(prompt);
if (!key) return null;
- return validateCacheHit(
+ return (
readGlobalManifest().find(
(r) =>
r.reusable &&
normalizePrompt(r.provenance?.prompt) === key &&
- (type == null || r.type === type),
- ),
+ (type == null || r.type === type) &&
+ validateCacheHit(r),
+ ) ?? null
);
}
export function cacheGetByEntity(entity) {
const lower = entity.toLowerCase();
- return validateCacheHit(
- readGlobalManifest().find((r) => r.reusable && r.entity && r.entity.toLowerCase() === lower),
+ return (
+ readGlobalManifest().find(
+ (r) => r.reusable && r.entity && r.entity.toLowerCase() === lower && validateCacheHit(r),
+ ) ?? null
);
}
@@ -86,7 +103,7 @@ export function cachePut(filePath, record) {
const sha = contentHash(filePath);
// Idempotent: same content already promoted -> don't duplicate the global
// record. ponytail: skips usage_count bump; add it when the metric is needed.
- const existing = readGlobalManifest().find((r) => r.sha === sha);
+ const existing = readGlobalManifest().findLast((r) => r.sha === sha && validateCacheHit(r));
if (existing) return { sha, cached_path: existing.cached_path, deduped: true };
const dir = globalMediaDir();
@@ -108,12 +125,9 @@ export function cachePut(filePath, record) {
}
export function importFromCache(cacheRecord, projectDir, localId, localPath) {
+ if (!validateCacheHit(cacheRecord)) return null;
const sha = cacheRecord.sha;
- const entryDir = cacheEntryDir(globalMediaDir(), sha);
- if (!isComplete(entryDir)) return null;
-
const cachedFile = cacheRecord.cached_path;
- if (!cachedFile || !existsSync(cachedFile)) return null;
mkdirSync(join(projectDir, ".media"), { recursive: true });
const fullDest = join(projectDir, localPath);
diff --git a/packages/cli/src/media-use/lib/cache.test.mjs b/packages/cli/src/media-use/lib/cache.test.mjs
new file mode 100644
index 0000000000..c9e52b96f6
--- /dev/null
+++ b/packages/cli/src/media-use/lib/cache.test.mjs
@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { appendRecord } from "./manifest.mjs";
+import {
+ cacheGet,
+ cacheGetByEntity,
+ cachePut,
+ findGlobalBySha,
+ importFromCache,
+ readGlobalManifest,
+} from "./cache.mjs";
+
+function sandbox(t) {
+ const root = mkdtempSync(join(tmpdir(), "mu-cache-recovery-"));
+ const previous = process.env.HYPERFRAMES_MEDIA_HOME;
+ process.env.HYPERFRAMES_MEDIA_HOME = join(root, "library");
+ t.after(() => {
+ if (previous === undefined) delete process.env.HYPERFRAMES_MEDIA_HOME;
+ else process.env.HYPERFRAMES_MEDIA_HOME = previous;
+ rmSync(root, { recursive: true, force: true });
+ });
+ const source = join(root, "original.wav");
+ const bytes = "cache recovery fixture";
+ writeFileSync(source, bytes);
+ const record = {
+ id: "bgm_001",
+ type: "bgm",
+ entity: "Recovery",
+ provenance: { prompt: "cache recovery" },
+ };
+ return { root, source, bytes, record };
+}
+
+for (const invalid of [
+ "missing file",
+ "missing marker",
+ "missing directory",
+ "empty file",
+ "directory",
+]) {
+ test(`cachePut repairs a ${invalid} before deduplicating`, (t) => {
+ const { root, source, bytes, record } = sandbox(t);
+ const first = cachePut(source, record);
+ const entry = dirname(first.cached_path);
+ if (invalid === "missing marker") rmSync(join(entry, ".hf-complete"));
+ else if (invalid === "missing directory") rmSync(entry, { recursive: true });
+ else if (invalid === "empty file") writeFileSync(first.cached_path, "");
+ else {
+ rmSync(first.cached_path);
+ if (invalid === "directory") mkdirSync(first.cached_path);
+ }
+
+ const replacement = join(root, "replacement.wav");
+ writeFileSync(replacement, bytes);
+ const repaired = cachePut(replacement, record);
+
+ assert.equal(repaired.deduped, undefined);
+ assert.equal(repaired.sha, first.sha);
+ assert.equal(readFileSync(repaired.cached_path, "utf8"), bytes);
+ const cached = cacheGet(" Cache Recovery ", "bgm");
+ assert.equal(cached?.sha, repaired.sha);
+ assert.equal(readFileSync(cached.cached_path, "utf8"), bytes);
+ assert.equal(cacheGetByEntity("recovery")?.sha, repaired.sha);
+ const imported = importFromCache(cached, join(root, "project"), "bgm_002", "restored.wav");
+ assert.equal(imported?.provenance.imported_from, first.sha);
+ assert.equal(readFileSync(join(root, "project", "restored.wav"), "utf8"), bytes);
+ });
+}
+
+test("an intact cache stays deduplicated without adding a manifest record", (t) => {
+ const { source, record } = sandbox(t);
+ const first = cachePut(source, record);
+ const second = cachePut(source, record);
+
+ assert.deepEqual(second, { ...first, deduped: true });
+ assert.equal(readGlobalManifest().length, 1);
+});
+
+test("prompt and entity lookups skip a stale entry for another complete match", (t) => {
+ const { root, source, record } = sandbox(t);
+ const first = cachePut(source, record);
+ rmSync(first.cached_path);
+ const secondSource = join(root, "second.wav");
+ writeFileSync(secondSource, "different reusable bytes");
+ const second = cachePut(secondSource, record);
+
+ assert.equal(cacheGet("cache recovery", "bgm")?.sha, second.sha);
+ assert.equal(cacheGetByEntity("RECOVERY")?.sha, second.sha);
+ assert.equal(cacheGet("cache recovery", "sfx"), null);
+});
+
+test("sha reuse counts distinct content and selects the repaired record", (t) => {
+ const { root, source, bytes, record } = sandbox(t);
+ const first = cachePut(source, record);
+ rmSync(first.cached_path);
+ const replacement = join(dirname(first.cached_path), "replacement.wav");
+ writeFileSync(replacement, bytes);
+ appendRecord(join(root, "library"), {
+ ...record,
+ sha: first.sha,
+ reusable: true,
+ cached_path: replacement,
+ });
+
+ assert.equal(findGlobalBySha(first.sha)?.cached_path, replacement);
+ assert.equal(findGlobalBySha(first.sha.slice(0, 16))?.cached_path, replacement);
+});