Files
hyperframes/packages/cli/src/utils/publishProxyBake.ts
T
James RussoandClaude Opus 5.5 a810a8b002 fix(cli): publish leaves out outside files that came in with an imported project (#7598)
* fix(cli): publish leaves out outside files that came in with an imported project

When the desktop app brings in someone else's project (a Cutroom link, a
sync of a teammate's version, a reference's source), it lists those files
in .hyperframes/received-files.json. Publish, cloud render and feedback
now leave out every file outside the project that a listed file
references or links to, and warn naming the file and the reference. Files
the person wrote keep copying their outside references into _ext/ as
before. A record that cannot be read counts every file as received.

A project inside a hidden or app-data folder now only shares that folder
with assets in the folder it sits in: an outside file further up, in a
hidden or app-data location, is left out with the existing warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): bake proxies only for media publish kept

A video that staging left out of the upload could still reach the
archive as a transcoded proxy. Skip any hostile source whose archive
key staging did not keep.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 00:28:05 +00:00

168 lines
6.9 KiB
TypeScript

/**
* Publish-time proxy baking (U6 of
* docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md).
*
* Published pages are static (no server), so the on-demand `?hf-proxy=`
* negotiation the preview/play surfaces use (U3/U4) isn't possible there.
* Instead this scans the archive's HTML entries for local `<video src>`
* references to browser-hostile codecs (HEVC, ProRes, ...), transcodes each
* one via the shared studio-server proxy transcoder, adds the proxy bytes to
* the archive under a `_proxy/` prefix, and rewrites ONLY the matching
* `<video src>` attributes in the archive's HTML copies to point at the
* proxy.
*
* `<audio>` elements are never rewritten: verified (per the plan's Key
* Technical Decisions) that AAC demuxes fine from an HEVC container in an
* HEVC-less browser, so an `<audio>` sharing a hostile video's src plays the
* original untouched. On-disk project files are never modified — only the
* in-memory archive file map passed in by `publish.ts` (built via
* `buildPublishFileMap`, baked here, then zipped via `zipPublishFileMap`).
* `cloud render` never calls this: it builds and zips the file map without an
* intermediate baking transform (R2 in the plan).
*
* Alpha-bearing sources bake as VP8/WebM so transparency survives. A failed
* hostile transcode aborts publish with a
* structured manifest rather than silently shipping an unplayable asset.
*/
import { existsSync } from "node:fs";
import { readFile } from "node:fs/promises";
import { basename, dirname, resolve } from "node:path";
import { parseHTML } from "linkedom";
import { rewriteAssetPath } from "@hyperframes/parsers/asset-paths";
import {
cleanAssetUrl,
isRemoteOrInlineUrl,
resolveLocalAssetCandidates,
} from "@hyperframes/parsers/asset-resolution";
import {
proxyVariantFor,
scanProjectMediaCodecMap,
type HtmlSourceLike,
} from "@hyperframes/studio-server/media-codec-map";
import { ProxyTranscodeError, resolveProxies } from "@hyperframes/studio-server/proxy-transcoder";
import { archiveKey, rewriteHtmlAttributes } from "./publishProject.js";
/** Archive-path prefix for baked proxy files, mirroring `localizeExternalAssets`'s `_ext/`. */
export const PROXY_ARCHIVE_PREFIX = "_proxy";
export interface ProxyBakeManifest {
proxied: string[];
/** @deprecated Alpha sources are proxied as VP8; retained as an always-empty compatibility field. */
skippedAlpha: string[];
failed: Array<{ path: string; error: string }>;
}
class ProxyBakeError extends Error {
readonly manifest: ProxyBakeManifest;
constructor(manifest: ProxyBakeManifest) {
const summary = manifest.failed.map((entry) => `${entry.path}: ${entry.error}`).join("; ");
super(`Unable to bake required browser media proxies (${summary})`);
this.name = "ProxyBakeError";
this.manifest = manifest;
}
}
function emptyManifest(): ProxyBakeManifest {
return { proxied: [], skippedAlpha: [], failed: [] };
}
function isHtmlEntry(path: string): boolean {
return path.endsWith(".html") || path.endsWith(".htm");
}
/**
* Mutates `fileContents` in place: adds a variant-specific `_proxy/<hash>` entry for every
* browser-hostile local video asset referenced from the archive's HTML, and
* rewrites those HTML entries' matching `<video src>` attributes to point at
* the proxy. Returns a structured manifest; throws ProxyBakeError when any
* required proxy cannot be prepared.
*/
export async function bakeMediaProxies(
projectDir: string,
fileContents: Map<string, Buffer>,
): Promise<ProxyBakeManifest> {
const manifest = emptyManifest();
const absProjectDir = resolve(projectDir);
const htmlEntries = [...fileContents.entries()].filter(([path]) => isHtmlEntry(path));
if (htmlEntries.length === 0) return manifest;
const htmlSources: HtmlSourceLike[] = htmlEntries.map(([entryPath, content]) => ({
html: content.toString("utf-8"),
compSrcPath: entryPath,
}));
const codecMap = await scanProjectMediaCodecMap(absProjectDir, htmlSources);
const keptByStaging = (pathname: string) =>
fileContents.has(archiveKey(pathname.replace(/^\/+/, "")));
const hostileEntries = Object.entries(codecMap).filter(
([pathname, facts]) => facts.browserHostile && keptByStaging(pathname),
);
if (hostileEntries.length === 0) return manifest;
// Absolute source path -> archive path of its baked proxy. Built by
// resolving each map key back to an absolute path the same way
// `compositionServer.ts`'s `injectMediaCodecMap` does, since the map is
// keyed by project-root-relative URL pathname (per the plan's KTD), not a
// filesystem path.
const proxyByAbsolutePath = new Map<string, string>();
const sources = hostileEntries.map(([pathname, facts]) => ({
pathname,
sourcePath: resolve(absProjectDir, pathname.replace(/^\/+/, "")),
variant: proxyVariantFor(facts),
}));
const results = await resolveProxies(absProjectDir, sources);
await Promise.all(
sources.map(async ({ pathname, sourcePath }, index) => {
const result = results[index]!;
try {
if (result.status === "rejected") throw result.reason;
const archivePath = `${PROXY_ARCHIVE_PREFIX}/${basename(result.value)}`;
fileContents.set(archivePath, await readFile(result.value));
proxyByAbsolutePath.set(sourcePath, archivePath);
manifest.proxied.push(pathname);
} catch (err) {
const reason = err instanceof ProxyTranscodeError ? err.message : String(err);
manifest.failed.push({ path: pathname, error: reason });
}
}),
);
manifest.proxied.sort();
manifest.skippedAlpha.sort();
manifest.failed.sort((a, b) => a.path.localeCompare(b.path));
if (manifest.failed.length > 0) throw new ProxyBakeError(manifest);
if (proxyByAbsolutePath.size === 0) return manifest;
for (const [entryPath, content] of htmlEntries) {
const { document } = parseHTML(content.toString("utf-8"));
const referrerAbsDir = resolve(absProjectDir, dirname(entryPath));
const modified = rewriteHtmlAttributes(
document,
referrerAbsDir,
entryPath,
(rawValue) => {
const cleaned = cleanAssetUrl(rawValue);
if (!cleaned || isRemoteOrInlineUrl(cleaned)) return null;
// Resolve the raw attribute value the same way the scan did
// (rewriteAssetPath to root-relative, then decodeUrlPathVariants via
// resolveLocalAssetCandidates) so percent-encoded and root-absolute
// srcs match the map keys the scan produced.
const rootRelativeSrc = rewriteAssetPath(entryPath, cleaned, (path) =>
existsSync(resolve(absProjectDir, path)),
);
for (const candidate of resolveLocalAssetCandidates(absProjectDir, rootRelativeSrc)) {
const archivePath = proxyByAbsolutePath.get(candidate);
if (archivePath) return archivePath;
}
return null;
},
{ selector: "video[src]", attrs: ["src"] },
);
if (modified) fileContents.set(entryPath, Buffer.from(document.toString(), "utf-8"));
}
return manifest;
}