import { test } from "node:test";
import assert from "node:assert/strict";
import fs, { mkdtemp, mkdir, readFile, writeFile, rm, symlink, utimes } from "node:fs/promises";
import { tmpdir, hostname } from "node:os";
import { join } from "node:path";
import { realpathSync } from "node:fs";
import { spawn } from "node:child_process";
import { once } from "node:events";
import { randomUUID } from "node:crypto";
import {
bindShareHost,
shareForReview,
reviewClient,
reviewRecord,
addVersion,
pendingReviewExport,
reviewVersion,
refreshReviewExport,
putFile,
projectFingerprint,
snapshotProject,
snapshotFiles,
snapshotFingerprint,
withProjectShareLock,
ShareBusyError,
} from "../src/index.mjs";
const reviewUploadOrigins = [
"https://review-bucket.s3.us-east-1.amazonaws.com",
"https://customer-bucket.s3.us-west-2.amazonaws.com",
];
bindShareHost({
normalize: realpathSync,
channelSite: "https://hyperframes.dev",
signinSites: ["https://hyperframes.dev"],
projectFingerprint,
reviewUploadOrigins,
latestExportFile: (dir) => ({
path: join(dir, ".hyperframes", "video.mp4"),
fingerprint: "rendered",
id: "render",
}),
});
async function folder(t) {
const dir = await mkdtemp(join(tmpdir(), "hf-share-kernel-"));
t.after(() => rm(dir, { recursive: true, force: true }));
return dir;
}
function client() {
let calls = 0;
const body = [];
const dto = {
project_id: "p1",
review_url: "https://hyperframes.dev/r/token",
access_mode: "public",
default_role: "commenter",
comments_enabled: true,
revoked: false,
};
return {
body,
calls: () => calls,
spaces: async () => [{ space_id: "s1", bound: true, can_create_review: true }],
register: async (value) => {
calls++;
body.push(value);
return { project_id: "p1" };
},
signedInEmail: async () => "owner@example.com",
share: async () => dto,
};
}
test("a lost registration response retries the persisted operation and identity", async (t) => {
const dir = await folder(t);
const api = client();
const register = api.register;
let first = true;
api.register = async (value) => {
const result = await register(value);
if (first) {
first = false;
throw new Error("lost reply");
}
return result;
};
await assert.rejects(
shareForReview({ projectPath: dir, title: "Video", client: api, audience: "public" }),
);
await shareForReview({
projectPath: dir,
title: "Changed title",
client: api,
audience: "public",
});
assert.equal(api.calls(), 2);
assert.deepEqual(api.body[0], api.body[1]);
assert.equal((await reviewRecord(dir)).projectId, "p1");
});
test("preparing a review can fail before opening and retry its saved registration", async (t) => {
const dir = await folder(t);
const api = client();
const read = api.share;
api.share = async () => ({ ...(await read()), access_mode: "private" });
const opened = [];
api.updateShare = async (id, body) => {
opened.push(id);
return { ...(await read()), access_mode: body.access_mode };
};
const request = { projectPath: dir, title: "Review", client: api, audience: "public" };
await assert.rejects(
shareForReview({
...request,
beforeOpen: async (id) => {
assert.equal((await reviewRecord(dir)).projectId, id);
throw new Error("Content unavailable");
},
}),
/Content unavailable/,
);
assert.deepEqual(opened, []);
assert.equal((await reviewRecord(dir)).opened, false);
await shareForReview({
...request,
beforeOpen: async (id) => {
assert.equal(id, "p1");
assert.deepEqual(opened, []);
},
});
assert.deepEqual(opened, ["p1"]);
assert.equal(api.calls(), 1);
assert.equal((await reviewRecord(dir)).opened, true);
});
test("an already-open link returns status without rerunning content preparation", async (t) => {
const dir = await folder(t);
const api = client();
const request = { projectPath: dir, title: "Review", client: api, audience: "public" };
const first = await shareForReview(request);
const again = await shareForReview({
...request,
beforeOpen: async () => {
throw new Error("Content temporarily unavailable");
},
});
assert.deepEqual(again, first);
assert.equal(api.calls(), 1);
});
test("reopening a revoked link prepares content before enabling it and retries safely", async (t) => {
const dir = await folder(t);
const api = client();
const request = { projectPath: dir, title: "Review", client: api, audience: "public" };
await shareForReview(request);
const read = api.share;
api.share = async () => ({ ...(await read()), revoked: true, link_generation: 2 });
const events = [];
api.linkOn = async () => {
events.push("open");
return read();
};
await assert.rejects(
shareForReview({
...request,
beforeOpen: async () => {
throw new Error("Content unavailable");
},
}),
/Content unavailable/,
);
assert.deepEqual(events, []);
await shareForReview({
...request,
beforeOpen: async (id) => {
assert.equal(id, "p1");
events.push("prepare");
},
});
assert.deepEqual(events, ["prepare", "open"]);
assert.equal(api.calls(), 1);
});
test("a taken-down review does not prepare content or reopen its link", async (t) => {
const dir = await folder(t);
const api = client();
const read = api.share;
api.share = async () => ({
...(await read()),
moderation_hold: true,
moderation_hold_kind: "takedown",
revoked: true,
});
const status = await shareForReview({
projectPath: dir,
title: "Review",
client: api,
beforeOpen: async () => assert.fail("A taken-down review cannot open"),
});
assert.equal(status.held, true);
assert.equal((await reviewRecord(dir)).opened, false);
});
test("storyboard reads and composition binding use the signed-in review routes", async () => {
const sent = [];
const api = reviewClient({
access: async () => ({ token: "t", heygen: "https://review.test", heygenApi: "" }),
fetchImpl: async (url, init) => {
assert.equal(new Headers(init.headers).get("authorization"), "Bearer t");
sent.push([init.method, new URL(url).pathname, new URL(url).search, init.body]);
return Response.json({ data: {} });
},
});
await api.storyboard("project/id");
await api.bindComposition("project/id", "composition");
assert.deepEqual(sent, [
["GET", "/v1/hyperframes/projects/project%2Fid/storyboard", "", null],
[
"PUT",
"/v1/hyperframes/review-projects/project%2Fid/composition",
"",
'{"composition_id":"composition"}',
],
]);
});
test("corrupt identity fails instead of consuming a new share slot", async (t) => {
const dir = await folder(t);
await mkdir(join(dir, ".hyperframes"));
await writeFile(join(dir, ".hyperframes/review.json"), "{broken");
const api = client();
await assert.rejects(
shareForReview({ projectPath: dir, title: "Video", client: api, audience: "public" }),
/Restore this file from a backup.*Keep the file/,
);
assert.equal(api.calls(), 0);
});
test("a completed identical upload is not added again after another host releases the lock", async (t) => {
const dir = await folder(t);
const api = client();
await shareForReview({ projectPath: dir, title: "Video", client: api, audience: "public" });
await writeFile(join(dir, ".hyperframes/video.mp4"), "video bytes");
bindShareHost({ projectFingerprint: async () => "rendered" });
let exports = 0;
api.createExport = async () => {
exports++;
return {
status: "ready",
video_id: "vid",
version_id: "v1",
exported_at: "2026-11-04T00:00:00Z",
};
};
api.project = async () => ({ latest_ready_version_id: "v1" });
const request = {
projectPath: dir,
title: "Video",
client: api,
probe: async () => ({ width: 1920, height: 1080, duration: 1 }),
};
assert.equal(await addVersion(request), null);
assert.equal(await addVersion(request), null);
assert.equal(exports, 1);
assert.equal((await reviewVersion(dir)).last.current, true);
bindShareHost({ projectFingerprint });
});
test("HTML stamps and generated render metadata do not dirty the shared source", async (t) => {
const dir = await folder(t);
await writeFile(join(dir, "index.html"), "
Hello
");
const before = await projectFingerprint(dir);
await writeFile(join(dir, "index.html"), 'Hello
');
await mkdir(join(dir, ".hyperframes"));
await writeFile(join(dir, ".hyperframes/render.json"), "metadata");
assert.equal(await projectFingerprint(dir), before);
await writeFile(join(dir, "index.html"), 'Changed
');
assert.notEqual(await projectFingerprint(dir), before);
});
test("a host can accept a version that is still screening when it stops waiting", async (t) => {
const dir = await folder(t);
const api = client();
await shareForReview({ projectPath: dir, title: "Video", client: api, audience: "public" });
await writeFile(join(dir, ".hyperframes/video.mp4"), "video bytes");
bindShareHost({ projectFingerprint: async () => "rendered" });
t.after(() => bindShareHost({ projectFingerprint }));
let video = {
status: "screening",
screening_state: "held",
video_id: "vid",
version_id: "v1",
exported_at: "2026-11-04T00:00:00Z",
};
api.createExport = t.mock.fn(async () => video);
api.readExport = async () => video;
const onAdded = t.mock.fn();
const request = {
projectPath: dir,
title: "Video",
client: api,
probe: async () => ({ width: 1920, height: 1080, duration: 1 }),
open: () => false,
onAdded,
};
assert.ok(await addVersion(request));
assert.equal((await reviewVersion(dir)).held, true);
assert.equal(await addVersion({ ...request, allowPending: true }), null);
assert.equal((await pendingReviewExport(dir)).videoId, "vid");
assert.equal((await reviewVersion(dir)).failure, null);
assert.equal(onAdded.mock.callCount(), 0);
assert.equal(api.createExport.mock.callCount(), 1);
video = { ...video, status: "ready" };
await refreshReviewExport(dir, api);
assert.equal(await pendingReviewExport(dir), null);
assert.equal((await reviewVersion(dir)).last.current, true);
});
const moduleUrl = new URL("../src/index.mjs", import.meta.url).href;
function child(script, args) {
return spawn(process.execPath, ["--input-type=module", "-e", script, ...args], {
stdio: ["ignore", "pipe", "pipe"],
});
}
async function success(proc) {
let stderr = "";
proc.stderr.on("data", (chunk) => {
stderr += chunk;
});
const [code] = await once(proc, "exit");
assert.equal(code, 0, stderr);
}
for (const fallback of [false, true])
test(`independent processes serialize registration (exclusive-create=${fallback})`, async (t) => {
const dir = await folder(t);
const script = `import fs from 'node:fs/promises';
if (${fallback}) fs.link = async () => { throw Object.assign(new Error('unsupported'), {code:'EPERM'}); };
import {bindShareHost,shareForReview} from ${JSON.stringify(moduleUrl)};
import {realpathSync} from 'node:fs'; import {appendFile} from 'node:fs/promises';
const dir=process.argv[1]; bindShareHost({normalize:realpathSync,channelSite:'https://hyperframes.dev',signinSites:['https://hyperframes.dev']});
const client={ spaces:async()=>[{space_id:'s1',bound:true,can_create_review:true}], signedInEmail:async()=>null,
register:async()=>{await appendFile(dir+'/registrations','registered\\n');await new Promise(r=>setTimeout(r,80));return {project_id:'p1'}},
share:async()=>({project_id:'p1',review_url:'https://hyperframes.dev/r/t',access_mode:'public',default_role:'commenter',comments_enabled:true,revoked:false})};
await shareForReview({projectPath:dir,title:'Video',client,audience:'public'});`;
await Promise.all([success(child(script, [dir])), success(child(script, [dir]))]);
assert.equal(await readFile(join(dir, "registrations"), "utf8"), "registered\n");
});
test("a dead local owner can resume while a live or foreign owner is never stolen", async (t) => {
const dir = await folder(t);
const script = `import {withProjectShareLock} from ${JSON.stringify(moduleUrl)}; await withProjectShareLock(process.argv[1], 'review', async()=>{console.log('locked');await new Promise(()=>{});setInterval(()=>{},1000)});`;
// Keep the owner alive until the parent deliberately terminates this test process.
const proc = child(
script.replace(
"await new Promise(()=>{});setInterval(()=>{},1000)",
"await new Promise(()=>{setInterval(()=>{},1000)})",
),
[dir],
);
await once(proc.stdout, "data");
await assert.rejects(
withProjectShareLock(dir, "review", async () => true, { timeoutMs: 30 }),
ShareBusyError,
);
const ended = once(proc, "exit");
proc.kill("SIGKILL");
await ended;
assert.equal(await withProjectShareLock(dir, "review", async () => "resumed"), "resumed");
await writeFile(
join(dir, ".hyperframes/review.lock"),
JSON.stringify({ token: randomUUID(), pid: process.pid, hostname: hostname() + "-foreign" }),
);
await assert.rejects(
withProjectShareLock(dir, "review", async () => true, { timeoutMs: 30 }),
ShareBusyError,
);
});
test("status recovery settles distinct video/version IDs without a new upload", async (t) => {
const dir = await folder(t);
const api = client();
await shareForReview({ projectPath: dir, title: "Video", client: api, audience: "public" });
const fingerprint = await projectFingerprint(dir);
const file = join(dir, ".hyperframes/review-export.json");
await writeFile(
file,
JSON.stringify({
last: null,
pending: {
projectId: "p1",
videoId: "video-id",
body: {
title_snapshot: "Video",
coordinate_width: 1920,
coordinate_height: 1080,
duration_seconds: 1,
render_settings: {},
source_revision_id: null,
source_fingerprint: fingerprint,
local_upload: { checksum_sha256: "checksum", content_type: "video/mp4", size_bytes: 42 },
client_operation_id: "stable",
},
},
}),
);
const saved = await readFile(file, "utf8");
let status = "upload_pending";
let reads = 0;
api.readExport = async (project, video) => {
reads++;
assert.equal(project, "p1");
assert.equal(video, "video-id");
return {
status,
video_id: video,
version_id: "version-id",
exported_at: "2026-11-04T00:00:00Z",
};
};
await withProjectShareLock(dir, "export", () => refreshReviewExport(dir, api));
assert.equal(reads, 0);
await refreshReviewExport(dir, api);
assert.equal(reads, 1);
assert.equal(await readFile(file, "utf8"), saved);
status = "ready";
await refreshReviewExport(dir, api);
assert.equal(reads, 2);
assert.equal(JSON.parse(await readFile(file, "utf8")).pending, null);
assert.equal(
(await reviewVersion(dir, { latestReadyVersionId: "version-id" })).last.current,
true,
);
await refreshReviewExport(dir, api);
assert.equal(reads, 2);
});
test("refuses an unconfigured review upload destination before sending the file", async (t) => {
const dir = await folder(t);
const file = join(dir, "video.mp4");
await writeFile(file, "rendered video");
const fetchImpl = t.mock.fn(async () => new Response(null, { status: 200 }));
for (const put_url of [
"https://other-bucket.s3.us-east-1.amazonaws.com/video",
"https://review-bucket.s3.us-east-1.amazonaws.com.example.test/video",
`${reviewUploadOrigins[0]}:8443/video`,
"http://127.0.0.1:8090/video",
"not a URL",
]) {
assert.equal(
await putFile({ put_url, headers: {} }, file, 14, () => {}, { fetchImpl }),
"refused",
put_url,
);
}
assert.equal(fetchImpl.mock.callCount(), 0);
});
test("streams a review video to a configured storage origin without following redirects", async (t) => {
const dir = await folder(t);
const file = join(dir, "video.mp4");
const video = "rendered video";
await writeFile(file, video);
const put_url = `${reviewUploadOrigins[1]}/video?signature=example`;
const fetchImpl = t.mock.fn(async (url, request) => {
assert.equal(url.href, put_url);
assert.equal(request.redirect, "manual");
assert.equal(await new Response(request.body).text(), video);
return new Response(null, {
status: 307,
headers: { location: "https://other.example.test/video" },
});
});
assert.equal(
await putFile({ put_url, headers: {} }, file, video.length, () => {}, { fetchImpl }),
"refused",
);
assert.equal(fetchImpl.mock.callCount(), 1);
});
test("failed upload releases its input even when fetch does not cancel it", async (t) => {
const dir = await folder(t);
const file = join(dir, "video.mp4");
await writeFile(file, Buffer.alloc(200_000));
let reader;
const result = await putFile(
{ put_url: `${reviewUploadOrigins[0]}/video`, headers: {} },
file,
200_000,
() => {},
{
fetchImpl: async (_url, request) => {
reader = request.body.getReader();
await reader.read();
throw new Error("network closed");
},
},
);
assert.equal(result, "offline");
await assert.rejects(
reader.read(),
(error) => error.code === "ERR_STREAM_PREMATURE_CLOSE" || error.code === "ABORT_ERR",
);
});
test("linked media changes invalidate the rendered source and link cycles terminate", async (t) => {
const dir = await folder(t);
const media = await folder(t);
await writeFile(join(media, "clip.mp4"), "first video");
await symlink(media, join(dir, "assets"), "dir");
await symlink(dir, join(media, "cycle"), "dir");
const before = await projectFingerprint(dir);
await writeFile(join(media, "clip.mp4"), "updated video bytes");
assert.notEqual(await projectFingerprint(dir), before);
});
for (const code of ["EPERM", "ENOTSUP", "EXDEV", "EINVAL", "EISDIR", "EACCES"]) {
test(`directory fallback serializes operations when hard links fail with ${code}`, async (t) => {
const dir = await folder(t);
t.mock.method(fs, "link", async () => {
throw Object.assign(new Error("unsupported"), { code });
});
let active = 0;
let completed = 0;
const run = () =>
withProjectShareLock(dir, "review", async () => {
assert.equal(++active, 1);
await new Promise((resolve) => setTimeout(resolve, 40));
active--;
completed++;
});
await Promise.all([run(), run(), run()]);
assert.equal(completed, 3);
await assert.rejects(readFile(join(dir, ".hyperframes/review.lock")), { code: "ENOENT" });
});
}
test("Desktop snapshots retain the original symlink-skipping fingerprint", async (t) => {
const dir = await folder(t);
const media = await folder(t);
await writeFile(join(dir, "index.html"), "Film
");
const before = await snapshotProject(dir);
await writeFile(join(media, "clip.mp4"), "first video");
await symlink(media, join(dir, "footage"), "dir");
await symlink(join(media, "clip.mp4"), join(dir, "clip.mp4"), "file");
assert.deepEqual(await snapshotProject(dir), before);
assert.deepEqual(await snapshotProject(dir, { byContent: true }), before);
assert.equal(snapshotFingerprint(await snapshotProject(dir)), snapshotFingerprint(before));
assert.equal((await snapshotProject(dir, { followSymlinks: true })).size, 3);
assert.deepEqual(
await snapshotFiles(dir, ["clip.mp4", "footage"]),
new Map([
["clip.mp4", undefined],
["footage", undefined],
]),
);
});
for (const name of ["review.json", "review-export.json", "review-switch.json"]) {
test(`corrupt ${name} retains its bytes and explains recovery`, async (t) => {
const { readJsonOr } = await import("../src/storage.mjs");
const dir = await folder(t);
const file = join(dir, name);
await writeFile(file, "");
await assert.rejects(readJsonOr(file, null), (error) => {
assert.ok(error.message.includes(name));
assert.match(error.message, /Restore this file from a backup/);
assert.ok(error.cause instanceof SyntaxError);
return true;
});
assert.equal(await readFile(file, "utf8"), "");
});
}
test("required source never silently degrades after preparation or a server mismatch", async (t) => {
const dir = await folder(t);
await mkdir(join(dir, ".hyperframes"));
await writeFile(join(dir, ".hyperframes/video.mp4"), "video");
bindShareHost({ projectFingerprint: async () => "rendered" });
t.after(() => bindShareHost({ projectFingerprint }));
let creates = 0;
const api = {
createExport: async () => {
creates++;
throw new Error("should not send");
},
};
const request = {
projectPath: dir,
title: "Video",
client: api,
projectId: "project",
requireSource: true,
probe: async () => ({ width: 100, height: 100, duration: 1 }),
filesForExport: async () => null,
};
assert.match(await addVersion(request), /Source changed/);
assert.equal(creates, 0);
const { ReviewFailed } = await import("../src/reviewClient.mjs");
api.createExport = async () => {
creates++;
throw new ReviewFailed(422, "snapshot_mismatch");
};
await addVersion({
...request,
filesForExport: async () => ({
space_id: "space",
composition_id: "comp",
snapshot_id: "snap",
}),
});
assert.equal(creates, 1);
});
test("content fingerprints detect same-size changes with restored timestamps", async (t) => {
const dir = await folder(t);
const file = join(dir, "asset.txt");
const time = new Date("2026-11-01T00:00:00Z");
await writeFile(file, "first");
await utimes(file, time, time);
const metadata = await projectFingerprint(dir);
const content = await projectFingerprint(dir, { byContent: true });
await writeFile(file, "other");
await utimes(file, time, time);
assert.equal(await projectFingerprint(dir), metadata);
assert.notEqual(await projectFingerprint(dir, { byContent: true }), content);
});
test("a video-only retry never replays an unanswered source-bearing export", async (t) => {
const dir = await folder(t);
await mkdir(join(dir, ".hyperframes"));
await writeFile(join(dir, ".hyperframes/video.mp4"), "video bytes");
bindShareHost({ projectFingerprint: async () => "rendered" });
t.after(() => bindShareHost({ projectFingerprint }));
let creates = 0;
const request = {
projectPath: dir,
title: "Video",
client: {
createExport: async () => {
creates++;
throw new Error("lost response");
},
},
projectId: "project",
probe: async () => ({ width: 100, height: 100, duration: 1 }),
filesForExport: async () => ({
space_id: "space",
composition_id: "composition",
snapshot_id: "snapshot",
}),
};
await addVersion({ ...request, requireSource: true });
assert.match(
await addVersion({ ...request, omitSource: true }),
/pending upload includes source/,
);
assert.equal(creates, 1);
});
const lenient = { lenientIgnore: true };
test("change detection keeps working when .hyperframesignore uses gitignore syntax", async (t) => {
for (const rule of ["/renders/", "**/*.mov", "!keep.mp4", "assets/*/raw-*.mp4", "a[bc].png"]) {
const dir = await folder(t);
await mkdir(join(dir, "assets"));
await writeFile(join(dir, "index.html"), "Hello
");
await writeFile(join(dir, "assets/clip.mov"), "clip");
await writeFile(join(dir, ".hyperframesignore"), `${rule}\n`);
// The CLI's syntax is not this reader's: nothing is excluded beyond scratch, so a change still counts.
const files = await snapshotProject(dir, lenient);
assert.deepEqual([...files.keys()].sort(), ["assets/clip.mov", "index.html"], rule);
// snapshotFiles names every file asked for; an excluded one is keyed undefined.
assert.notEqual(
(await snapshotFiles(dir, ["assets/clip.mov"], lenient)).get("assets/clip.mov"),
undefined,
rule,
);
const before = await projectFingerprint(dir);
await writeFile(join(dir, "assets/clip.mov"), "edited clip");
assert.notEqual(await projectFingerprint(dir), before, rule);
}
});
test("change detection keeps working when .hyperframesignore is a link", async (t) => {
const dir = await folder(t);
await writeFile(join(dir, "index.html"), "Hello
");
await symlink(join(dir, "index.html"), join(dir, ".hyperframesignore"));
assert.deepEqual([...(await snapshotProject(dir, lenient)).keys()], ["index.html"]);
await projectFingerprint(dir);
});
test("a snapshot that picks files to send refuses a .hyperframesignore it can't read", async (t) => {
const dir = await folder(t);
await writeFile(join(dir, "index.html"), "Hello
");
await writeFile(join(dir, "private-notes.txt"), "private");
// One valid exclusion and one rule this reader refuses: the whole file is unreadable here.
await writeFile(join(dir, ".hyperframesignore"), "private-notes.txt\n/renders/\n");
await assert.rejects(snapshotProject(dir), { code: "invalid_source_ignore" });
await assert.rejects(snapshotFiles(dir, ["private-notes.txt"]), {
code: "invalid_source_ignore",
});
// Change detection still runs, and sees the file the valid line meant to exclude.
assert.equal((await snapshotProject(dir, lenient)).has("private-notes.txt"), true);
await rm(join(dir, ".hyperframesignore"));
await symlink(join(dir, "index.html"), join(dir, ".hyperframesignore"));
await assert.rejects(snapshotProject(dir), { code: "invalid_source_ignore" });
});
test("change detection still applies a .hyperframesignore it can read", async (t) => {
const dir = await folder(t);
await mkdir(join(dir, "assets"));
await writeFile(join(dir, "index.html"), "Hello
");
await writeFile(join(dir, "assets/raw.mov"), "raw");
await writeFile(join(dir, "debug.log"), "log");
await writeFile(join(dir, ".hyperframesignore"), "assets/raw.mov\n");
for (const options of [undefined, lenient])
assert.deepEqual([...(await snapshotProject(dir, options)).keys()], ["index.html"]);
});