fix(share): persist refusals and improve CLI retry feedback

This commit is contained in:
Terence Cho
2026-11-09 17:27:45 -08:00
parent 2521b6bb8f
commit e02294232d
15 changed files with 315 additions and 34 deletions
+39 -5
View File
@@ -27,11 +27,26 @@ styles, assets, and supported Studio edit metadata. Known credential filenames
(such as `.env`, `.npmrc`, and `*.pem`), dependency directories, chat
history, local sharing state, and recorded render outputs stay out.
These are filename rules, not a secret scanner. `.gitignore` and
`.hyperframesignore` do not control source capture. Other regular files can be
included even if Git ignores them. Keep private material outside the project,
or use `--video-only` when you do not want to upload project files. Unsupported symlinks and invalid file names stop source
preparation rather than silently producing an incomplete editable project.
These are filename rules, not a secret scanner. `.gitignore` does not control
source capture. Other regular files can be included even if Git ignores them.
Keep private material outside the project, or use `--video-only` when you do not
want to upload project files. Unsupported symlinks and invalid file names stop
source preparation rather than silently producing an incomplete editable project.
To exclude scratch files, add `.hyperframesignore` at the project root:
```text
# Literal paths, relative to the project root
out.json
scratch/
```
Each line excludes that file or folder and its contents from source capture and
sharing change detection. Blank lines and lines starting with `#` are ignored.
Use literal paths with `/` separators; wildcards, negation, absolute paths, and
excluding `index.html` are rejected. Do not exclude assets your composition uses.
These rules can only exclude files, never re-include credentials or other files
blocked by the portable project policy.
The upload uses the workspace's file-count, per-file, project-size and manifest
limits. Large media uploads in parts. Only a verified published snapshot that
@@ -69,6 +84,25 @@ a new video-only version after the earlier upload finishes, use
The upload result uses `ready` only after source verification and attachment
preparation; video readiness remains the separate top-level `ready` field.
## Refused uploads
A refused upload is saved locally so `--status` reports a failure, including
across CLI restarts. Retry an unfinished first share with the same command;
use `--update` to replace a previously shared video. An upload whose result is
still unknown keeps its recovery record to avoid creating duplicate versions.
`export_blocked` means recent content moderation strikes prevent new video
versions in this workspace. Contact HeyGen support to appeal. Rendering again,
changing audience, or having a paid plan does not lift the block.
`can_register_project` describes project quota eligibility, not moderation
permission to upload a video.
`--manage` requires an existing share. Audience flags are for first-share
creation and cannot be combined with `--status`, `--manage`, or `--update`.
Progress is written to stderr once per step; `--json` suppresses progress and
unrelated skill-update notices. Set `HF_DEBUG_RENDER=1` only when diagnosing
render initialization.
## Integrating another local host
`@hyperframes/share` exports `shareSources` and
+2 -2
View File
@@ -411,7 +411,7 @@ describe("CLI lifecycle", () => {
});
describe("stale-skills notice under --json", () => {
it("prints on a --json run while the self-update notices stay off", async () => {
it("suppresses unrelated notices on a --json run", async () => {
const printSkillsUpdateNotice = vi.fn();
const printUpdateNotice = vi.fn();
mockInitCommand(vi.fn());
@@ -431,7 +431,7 @@ describe("stale-skills notice under --json", () => {
process.argv = ["node", "cli.ts", "init", "--json"];
await import("./cli.js");
await vi.waitFor(() => expect(printSkillsUpdateNotice).toHaveBeenCalledTimes(1));
expect(printSkillsUpdateNotice).not.toHaveBeenCalled();
expect(printUpdateNotice).not.toHaveBeenCalled();
});
});
+7 -6
View File
@@ -327,12 +327,13 @@ if (
.catch(() => {});
}
// Skills freshness nudge: stderr only, so it also runs under --json, which agents pass.
import("./utils/skillsUpdateCheck.js")
.then((mod) => {
_printSkillsUpdateNotice = mod.printSkillsUpdateNotice;
})
.catch(() => {});
// Machine-readable commands should not include unrelated update notices.
if (!hasJsonFlag)
import("./utils/skillsUpdateCheck.js")
.then((mod) => {
_printSkillsUpdateNotice = mod.printSkillsUpdateNotice;
})
.catch(() => {});
// The notices read the caches; a detached child refreshes them for the next run.
import("./utils/backgroundChecks.js").then((mod) => mod.launchBackgroundChecks()).catch(() => {});
+48 -2
View File
@@ -1,12 +1,21 @@
import { afterEach, beforeEach, expect, it, vi } from "vitest";
import { runCommand } from "citty";
import { consumeCommandResult } from "../utils/commandResult.js";
const mocks = vi.hoisted(() => ({ run: vi.fn() }));
const mocks = vi.hoisted(() => ({
run: vi.fn(),
progress: undefined as undefined | ((value: { step: string; slow?: boolean } | null) => void),
}));
vi.mock("../utils/project.js", () => ({ resolveProjectOrThrow: () => ({ dir: "/project" }) }));
vi.mock("../share/service.js", () => ({ createShareService: () => ({ run: mocks.run }) }));
vi.mock("../share/service.js", () => ({
createShareService: (_dir: string, progress: typeof mocks.progress) => {
mocks.progress = progress;
return { run: mocks.run };
},
}));
import command from "./share.js";
beforeEach(() => {
consumeCommandResult();
mocks.run.mockReset();
mocks.run.mockResolvedValue({
state: "failed",
ready: false,
@@ -50,3 +59,40 @@ it("still opens management when the latest export failed", async () => {
expect(consumeCommandResult().exitCode).toBe(0);
expect(JSON.parse(String(out.mock.calls[0]?.[0])).ok).toBe(true);
});
it.each(["--status", "--manage", "--update"])(
"rejects ignored audience flags with %s",
async (action) => {
vi.spyOn(console, "log").mockImplementation(() => {});
await runCommand(command, { rawArgs: [action, "--public", "--json"] });
expect(consumeCommandResult().exitCode).toBe(2);
expect(mocks.run).not.toHaveBeenCalled();
},
);
it("says there is nothing to manage before a first share", async () => {
mocks.run.mockResolvedValue({ state: "not_shared" });
const out = vi.spyOn(console, "log").mockImplementation(() => {});
await runCommand(command, { rawArgs: ["--manage", "--json"] });
expect(JSON.parse(String(out.mock.calls[0]?.[0]))).toMatchObject({
ok: false,
error: { code: "not_shared" },
});
});
it("deduplicates progress and terminates each message before the friendly error", async () => {
const err = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
const friendly = vi.spyOn(console, "error").mockImplementation(() => {});
mocks.run.mockImplementation(async () => {
mocks.progress?.({ step: "preparing" });
mocks.progress?.({ step: "preparing" });
mocks.progress?.({ step: "uploading" });
mocks.progress?.(null);
throw new Error("Sharing blocked.");
});
await runCommand(command, { rawArgs: ["--private", "-y"] });
expect(err.mock.calls.map(([message]) => message)).toEqual([
"Sharing: preparing\n",
"Sharing: uploading\n",
]);
expect(friendly).toHaveBeenCalledWith("Sharing blocked.");
});
+23 -4
View File
@@ -61,11 +61,12 @@ export default defineCommand({
try {
const input = parseInput(args);
const project = resolveProjectOrThrow(args.dir);
let lastProgress = "";
const service: ShareService = createShareService(project.dir, (value) => {
if (value && !args.json)
process.stderr.write(
`Sharing: ${value.step}${value.slow ? " (still processing)" : ""}\r`,
);
if (!value || args.json) return;
const message = `Sharing: ${value.step}${value.slow ? " (still processing)" : ""}`;
if (message !== lastProgress) process.stderr.write(`${message}\n`);
lastProgress = message;
});
await chooseAudience(input, args, service);
const result = await service.run(input);
@@ -102,9 +103,23 @@ function parseInput(args: ShareArgs): ShareAction {
const audience = requestedAudience(args);
const action = args.status ? "status" : args.manage ? "manage" : args.update ? "update" : "share";
validateActionOptions(action, audience, args);
return { action, audience, space: args.space, waitSeconds, videoOnly: args["video-only"] };
}
function validateActionOptions(
action: ShareAction["action"],
audience: ShareAction["audience"],
args: ShareArgs,
) {
if (action !== "share" && audience)
throw new CliUsageError(
"Audience flags are only valid for a first share. Use --manage to change access.",
);
if ((action === "status" || action === "manage") && (args.space || args["video-only"]))
throw new CliUsageError("--space and --video-only cannot be used with --status or --manage.");
}
function requestedAudience(args: ShareArgs) {
const audiences: NonNullable<ShareAction["audience"]>[] = [];
if (args.public) audiences.push("public");
@@ -142,6 +157,10 @@ async function chooseAudience(input: ShareAction, args: ShareArgs, service: Shar
}
async function presentResult(result: ShareState, input: ShareAction, json: boolean) {
if (input.action === "manage" && result.state === "not_shared")
throw new CliUsageError("There is no share to manage yet. Create a share first.", {
code: "not_shared",
});
if (!json && result.source.at === "video_only")
console.error(`Sharing video only (${result.source.reason}).`);
if (result.state === "failed" && input.action !== "manage") {
+14
View File
@@ -237,6 +237,7 @@ describe("share operation consent and identity", () => {
mocks.status.mockResolvedValue(shared);
mocks.project.mockResolvedValue({ latest_ready_version_id: null });
mocks.version.mockResolvedValue({ last: null, source: "stale" });
mocks.pending.mockResolvedValue({ projectId: "project", videoId: "upload" });
await expect(createShareService("/project").run({ action: "share" })).rejects.toThrow(
"--update",
);
@@ -409,3 +410,16 @@ it.each([null, "previous-version"])(
expect(mocks.add).not.toHaveBeenCalled();
},
);
it("retries an uncreated first version after refusal even when local files changed", async () => {
mocks.status.mockResolvedValue(shared);
mocks.project.mockResolvedValue({ latest_ready_version_id: null });
mocks.version.mockResolvedValue({ last: null, source: "stale", failure: "Sharing blocked." });
mocks.add.mockResolvedValue("Sharing blocked.");
await expect(
createShareService("/project").run({ action: "share", audience: "public" }),
).rejects.toThrow("Sharing blocked.");
expect(mocks.render).toHaveBeenCalledOnce();
expect(mocks.add).toHaveBeenCalledOnce();
expect(mocks.create).not.toHaveBeenCalled();
});
+16 -3
View File
@@ -85,7 +85,9 @@ function statusLinks(
return {
url: ready ? url : null,
previousUrl: processing && project?.latest_ready_version_id ? url : null,
manageUrl: project?.authenticated_review_url ?? `${shareSite()}/shares`,
manageUrl:
project?.authenticated_review_url ??
`${shareSite() === "https://hyperframes.dev" ? "https://hyperframes.studio" : shareSite()}/shares`,
};
}
function isProcessing(
@@ -117,7 +119,13 @@ function assertExistingIntent(share: ReviewShare | null, input: ShareAction) {
throw new ReviewFailed(409, "manage_existing_audience");
}
function retrievesExisting(current: ShareState, input: ShareAction) {
return current.share && input.action === "share" && current.state !== "processing";
return (
current.share &&
input.action === "share" &&
(current.ready ||
current.state === "link_off" ||
(current.version.last && current.state !== "processing"))
);
}
async function preflightFirst(dir: string, client: ReviewClient, input: ShareAction) {
const audience = input.audience;
@@ -152,7 +160,12 @@ function assertAudience(audience: AccessMode, space: Space) {
throw new ReviewFailed(402, "review_subscription_required");
}
function assertResumeSource(current: ShareState, input: ShareAction) {
if (current.share && input.action === "share" && current.version.source !== "ready")
if (
current.share &&
current.pending &&
input.action === "share" &&
current.version.source !== "ready"
)
throw new Error(
"The shared video is unfinished and local edits have changed. Run hyperframes share --update to explicitly upload the current project.",
);
+6 -3
View File
@@ -1451,8 +1451,10 @@ async function finalizeDrawElementInit(
export async function completeDeferredDrawElementInit(session: CaptureSession): Promise<void> {
if (!session.deInitDeferred || !session.onBeforeCapture) return;
const page = session.page;
const logInitPhase = (phase: string) =>
console.error(`[initSession:${session.captureMode}] ${phase} (deferred drawElement init)`);
const logInitPhase = (phase: string) => {
if (process.env.HF_DEBUG_RENDER === "1")
console.error(`[initSession:${session.captureMode}] ${phase} (deferred drawElement init)`);
};
await finalizeDrawElementInit(session, page, logInitPhase, {
transparent: capturesAlpha(session.options),
forceDE: process.env.HF_FORCE_DRAWELEMENT === "1",
@@ -3143,7 +3145,8 @@ export async function initializeSession(session: CaptureSession): Promise<void>
session.config?.pageNavigationTimeout ?? DEFAULT_CONFIG.pageNavigationTimeout;
const initStart = Date.now();
const logInitPhase = (phase: string) => {
console.error(`[initSession:${session.captureMode}] ${phase} (${Date.now() - initStart}ms)`);
if (process.env.HF_DEBUG_RENDER === "1")
console.error(`[initSession:${session.captureMode}] ${phase} (${Date.now() - initStart}ms)`);
};
const gotoEntryPage = async (): Promise<void> => {
appendBrowserDiagnostic(
+11 -2
View File
@@ -1,6 +1,7 @@
// @ts-check
// A project's files as change detection sees them: every file the film can use (isOutsideFilm), keyed by mtime and
// size, except html, keyed by content without the data-hf-id stamps. A run's change set and the watcher both read it.
import { readSourceIgnore } from "./sourceIgnore.mjs";
import fs from "node:fs/promises";
import { constants } from "node:fs";
import path from "node:path";
@@ -60,6 +61,7 @@ async function entryKind(entry, full, followSymlinks) {
export async function snapshotProject(dir, { byContent = false, followSymlinks = false } = {}) {
/** @type {Snapshot} */
const result = new Map();
const ignored = await readSourceIgnore(dir);
/** @param {string} current @param {Set<string>} ancestors */
async function walk(current, ancestors) {
const real = await fs.realpath(current).catch(() => null);
@@ -74,7 +76,7 @@ export async function snapshotProject(dir, { byContent = false, followSymlinks =
}
for (const entry of entries) {
const full = path.join(current, entry.name);
if (isOutsideFilm(path.relative(dir, full))) continue;
if (excludedFromSnapshot(dir, full, ignored)) continue;
const kind = await entryKind(entry, full, followSymlinks);
if (kind?.isDirectory()) await walk(full, parents);
else if (kind?.isFile()) {
@@ -100,11 +102,12 @@ export function snapshotFingerprint(snapshot) {
export async function snapshotFiles(dir, files) {
/** @type {Map<string, unknown>} */
const result = new Map();
const ignored = await readSourceIgnore(dir);
for (const file of files) {
const full = path.join(dir, file);
const stat = await fs.lstat(full).catch(() => null);
if (stat?.isDirectory()) return null;
const holds = stat?.isFile() && !isOutsideFilm(path.relative(dir, full));
const holds = stat?.isFile() && !excludedFromSnapshot(dir, full, ignored);
result.set(file, holds ? await snapshotKey(full, false) : undefined);
}
return result;
@@ -125,3 +128,9 @@ export function diffChangedFiles(before, after) {
/** @param {string} projectPath @param {{ byContent?: boolean }} [options] */
export const projectFingerprint = async (projectPath, options) =>
snapshotFingerprint(await snapshotProject(projectPath, { ...options, followSymlinks: true }));
/** @param {string} dir @param {string} full @param {(path: string) => boolean} ignored */
function excludedFromSnapshot(dir, full, ignored) {
const relative = path.relative(dir, full);
return isOutsideFilm(relative) || ignored(relative.split(path.sep).join("/"));
}
+11 -4
View File
@@ -705,9 +705,17 @@ async function sendVersion(r, report, source, id, state) {
const done = await watch(r, id, uploaded, size, report, clock);
return finishRun(r, state, pending, id, done, first);
} catch (error) {
if (spent(error, state.pending)) await writeState(r.projectPath, { ...state, pending: null });
console.error("[review] version failed:", error);
return said(error);
const failure = said(error);
await writeState(r.projectPath, {
...state,
pending: spent(error, state.pending) ? null : state.pending,
failure: {
...failure,
projectId: id,
exportKey: await failedExportKey(r.projectPath, pending),
},
});
return failure;
}
}
@@ -773,7 +781,6 @@ export async function addVersion(request) {
if (kept) failures.set(key, { ...failure, exportKey: exportKeyOf(r.projectPath) });
return failure?.sentence ?? null;
} catch (error) {
console.error("[review] version failed:", error);
const sentence =
error instanceof SharingStateError ? error.message : "Couldn't add this version. Try again.";
failures.set(key, {
@@ -14,7 +14,8 @@ const SAID = {
export_daily_limit: (error) =>
`You've added the most versions for today. Try again ${laterIn(error.retryAfterMs)}.`,
content_rejected: "This video can't be shared.",
export_blocked: "Adding videos to review pages isn't available for this account.",
export_blocked:
"Sharing new videos is blocked because of recent content moderation strikes in this workspace. Rendering again will not lift the block. For appeal instructions, visit https://help.heygen.com/en/articles/7842567-the-ethical-use-of-synthetic-media",
feature_unavailable: "Review pages aren't available for your account yet.",
permission_denied: "This account can't add videos to this review page yet.",
upload_expired: "The upload took too long. Try again.",
+58
View File
@@ -0,0 +1,58 @@
// @ts-check
import { constants } from "node:fs";
import { lstat, open } from "node:fs/promises";
import { join } from "node:path";
/** Explicit, project-relative exclusions. This only removes files; it cannot override safety exclusions.
* @param {string} root @returns {Promise<(path: string) => boolean>} */
export async function readSourceIgnore(root) {
const file = join(root, ".hyperframesignore");
const invalid = () =>
new Error(".hyperframesignore must be a regular file inside the project, smaller than 64 KiB.");
const before = await lstat(file).catch((/** @type {NodeJS.ErrnoException} */ error) => {
if (error.code === "ENOENT") return null;
throw invalid();
});
if (!before) return () => false;
if (!before.isFile() || before.size >= 65536) throw invalid();
const handle = await open(
file,
constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0),
).catch(() => {
throw invalid();
});
let text;
try {
const stat = await handle.stat();
if (!stat.isFile() || stat.ino !== before.ino || stat.dev !== before.dev) throw invalid();
const buffer = Buffer.alloc(65536);
let length = 0;
while (length < buffer.length) {
const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
if (!bytesRead) break;
length += bytesRead;
}
if (length === buffer.length) throw invalid();
text = buffer.subarray(0, length).toString("utf8");
} finally {
await handle.close();
}
const paths = text
.split(/\r?\n/)
.map((line) => line.trim())
.filter((line) => line && !line.startsWith("#"));
const entries = paths.map((entry) => {
const path = entry.replace(/\/$/, "");
if (
path === "index.html" ||
/[\\*?![\]:]/.test(path) ||
path.includes("\0") ||
path.split("/").some((part) => !part || part === "." || part === "..")
)
throw new Error(
".hyperframesignore accepts literal project-relative file or folder paths, one per line. Wildcards and excluding index.html are not supported.",
);
return path;
});
return (path) => entries.some((entry) => path === entry || path.startsWith(`${entry}/`));
}
+3 -1
View File
@@ -2,6 +2,7 @@
// Captures a project folder as the canonical manifest the server accepts: every portable regular file with its
// SHA-256 and length. A file that cannot be read, a link, a special file or a name no client can store fails the
// capture with a list of them; it never becomes a deletion. Limits are checked from sizes alone, before any hashing.
import { readSourceIgnore } from "../sourceIgnore.mjs";
import { createHash } from "node:crypto";
import { constants } from "node:fs";
import { lstat, open, readdir, realpath } from "node:fs/promises";
@@ -83,6 +84,7 @@ async function listFolder(root, dir) {
async function walkProject(root, renderOutput) {
/** @type {Walk} */
const walk = { files: [], problems: [], waiting: [], skippedLinks: [] };
const ignored = await readSourceIgnore(root);
const dirs = [""];
for (let dir = dirs.pop(); dir !== undefined; dir = dirs.pop()) {
let entries;
@@ -95,7 +97,7 @@ async function walkProject(root, renderOutput) {
}
for (const entry of entries) {
const rel = dir ? `${dir}/${entry.name}` : entry.name;
if (prefiltered(entry.name) || renderOutput(rel)) continue;
if (prefiltered(entry.name) || renderOutput(rel) || ignored(rel)) continue;
await visit(root, rel, entry, walk, dirs);
}
}
@@ -7,7 +7,7 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { promisify } from "node:util";
import { test } from "node:test";
import { addVersion, bindShareHost, refreshReviewExport } from "../src/index.mjs";
import { addVersion, bindShareHost, refreshReviewExport, ReviewFailed } from "../src/index.mjs";
const run = promisify(execFile);
const moduleUrl = new URL("../src/index.mjs", import.meta.url).href;
@@ -194,3 +194,40 @@ test("malformed optional failure leaves a valid pending upload and previous vers
assert.equal(value.last.exportedAt, "before");
assert.deepEqual(JSON.parse(await readFile(file, "utf8")).pending, pending);
});
for (const update of [false, true]) {
test(`registration 403 for ${update ? "update" : "first share"} persists across processes and allows retry`, async (t) => {
const dir = await fixture(t);
const file = join(dir, ".hyperframes", "review-export.json");
const last = update
? { projectId: "project", versionId: "old", fingerprint: "old", exportedAt: "2026-11-01" }
: null;
await writeFile(file, JSON.stringify({ pending: null, last }));
const request = {
projectPath: dir,
projectId: "project",
title: "Video",
probe: async () => ({ width: 100, height: 100, duration: 1 }),
};
const failure = await addVersion({
...request,
client: {
createExport: async () => {
throw new ReviewFailed(403, "export_blocked");
},
},
});
assert.match(failure, /moderation strikes/);
const fresh = await readFromAnotherProcess(dir);
assert.equal(fresh.failure, failure);
assert.equal(fresh.retryable, false);
const saved = JSON.parse(await readFile(file, "utf8"));
assert.equal(saved.pending, null);
assert.deepEqual(saved.last, last);
assert.equal(
await addVersion({ ...request, client: { createExport: async () => ready } }),
null,
);
assert.equal((await readFromAnotherProcess(dir)).failure, null);
});
}
@@ -243,3 +243,40 @@ test("a file whose folder cannot be resolved once opened is refused, and its han
await assert.rejects(hashListedFile(root, file, gone), /ENOENT/);
assert.equal(await openFiles(), before, "the opened file was left open");
});
test("explicit exclusions remove scratch files from capture and render fingerprints", async (t) => {
const { projectFingerprint } = await import("../src/projectSnapshot.mjs");
const root = await project({
"index.html": "<html></html>",
".hyperframesignore": "# Scratch files\nout.json\nscratch/\n",
"out.json": "private",
"scratch/nested.txt": "private",
"assets/data.json": "asset",
".env": "secret",
});
t.after(() => rm(root, { recursive: true, force: true }));
const first = captured(await captureProject(root));
assert.deepEqual(
first.manifest.document.files.map((file) => file.path),
[".hyperframesignore", "assets/data.json", "index.html"],
);
const before = await projectFingerprint(root);
await rm(join(root, "out.json"));
await writeFile(join(root, "scratch/nested.txt"), "changed");
assert.equal(await projectFingerprint(root), before);
assert.deepEqual(captured(await captureProject(root)).manifest, first.manifest);
await writeFile(join(root, "assets/data.json"), "changed asset");
assert.notEqual(await projectFingerprint(root), before);
});
test("ignore rules fail closed for unsupported patterns, entrypoint exclusions, and symlinks", async (t) => {
const root = await project({ "index.html": "<html></html>" });
t.after(() => rm(root, { recursive: true, force: true }));
for (const rule of ["index.html", "../secret", "*.json", "!out.json"]) {
await writeFile(join(root, ".hyperframesignore"), rule);
await assert.rejects(captureProject(root), /literal project-relative/);
}
await rm(join(root, ".hyperframesignore"));
await symlink(join(root, "index.html"), join(root, ".hyperframesignore"));
await assert.rejects(captureProject(root), /regular file/);
});