framefields 2.11.0 → 2.13.0

package/dist/cloud-Cj1TIme8.mjs

@@ -0,0 +1,685 @@
+import { _ as parseStorage, c as credentialEnvNames, f as hashFile, g as parseAssets, l as credentialsFromEnv, n as Bucket, p as isAssetPath, u as downloadVerified, v as pickRemote, x as readUrl } from "./dist-CiTgmfUw.mjs";
+import { appendFileSync, createWriteStream, existsSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import path, { join, relative, resolve, sep } from "node:path";
+import fs$1 from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+//#region src/cli/config.ts
+/**
+* `framefields.json` at the project root: where installed components live,
+* which fonts `framefields add` / `framefields fonts add` installed, and the
+* project's named renders.
+*
+* ```json
+* {
+*   "components": "src/components",
+*   "renders": {
+*     "film": {
+*       "title": "Launch film",
+*       "entry": "src/film.ts",
+*       "export": "buildFilm",
+*       "workers": "auto"
+*     }
+*   }
+* }
+* ```
+*
+* A named render is what `framefields render film --cloud`, `framefields
+* check film`, `renderCloud({ render: "film" })` and the dashboard's New
+* render dialog pick, so nobody chooses files and exports by hand.
+*
+* `storage` and `assets` pin media by content on an S3-compatible bucket
+* (`framefields assets`; the format lives in `@framefields/storage`).
+*/
+const CONFIG_FILE = "framefields.json";
+const RENDER_NAME = /^[A-Za-z0-9][\w.-]{0,63}$/;
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const QUALITIES = [
+	"very_low",
+	"low",
+	"high",
+	"very_high"
+];
+/**
+* The project's config, or the default it would get: `src/components` when
+* there is a `src`. `saved` is whether the file records a components folder.
+*/
+function readConfig(cwd) {
+	const file = join(cwd, CONFIG_FILE);
+	const fallback = existsSync(join(cwd, "src")) ? "src/components" : "components";
+	if (!existsSync(file)) return {
+		config: { components: fallback },
+		saved: false
+	};
+	let raw;
+	try {
+		raw = JSON.parse(readFileSync(file, "utf8"));
+	} catch (err) {
+		throw new Error(`${CONFIG_FILE} is not valid JSON: ${err.message}`);
+	}
+	if (!isRecord(raw)) throw new Error(`${CONFIG_FILE} must be a JSON object`);
+	const { components, fonts, renders, storage, assets } = raw;
+	if (components !== void 0 && typeof components !== "string") throw new Error(`${CONFIG_FILE}: "components" must be a directory path`);
+	if (fonts !== void 0 && (!isRecord(fonts) || Object.values(fonts).some((v) => typeof v !== "string"))) throw new Error(`${CONFIG_FILE}: "fonts" must map roles to font file paths, e.g. { "emoji": "assets/fonts/NotoColorEmoji.ttf" }`);
+	const parsedStorage = storage === void 0 ? void 0 : parseStorage(storage);
+	return {
+		config: {
+			...raw,
+			components: components ?? fallback,
+			...renders !== void 0 && { renders: parseRenders(renders) },
+			...parsedStorage && { storage: parsedStorage },
+			...assets !== void 0 && { assets: parseAssets(assets, parsedStorage) }
+		},
+		saved: components !== void 0
+	};
+}
+function writeConfig(cwd, config) {
+	writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify(config, null, "	")}\n`);
+}
+/** Validates the `renders` map; errors name the render and field at fault. */
+function parseRenders(value) {
+	if (!isRecord(value)) throw new Error(`${CONFIG_FILE}: "renders" must map names to renders, e.g. { "film": { "entry": "src/film.ts" } }`);
+	const out = {};
+	for (const [name, spec] of Object.entries(value)) {
+		const fail = (message) => {
+			throw new Error(`${CONFIG_FILE}: renders.${name} ${message}`);
+		};
+		if (!RENDER_NAME.test(name)) fail("has an invalid name: use letters, digits, -, _ and . (at most 64)");
+		if (!isRecord(spec)) fail("must be an object with an entry");
+		const s = spec;
+		if (!isRelativePath(s.entry)) fail("needs \"entry\": the module path inside the project, e.g. \"src/film.ts\"");
+		if (s.export !== void 0 && !(typeof s.export === "string" && IDENTIFIER.test(s.export))) fail("\"export\" must be a JavaScript identifier");
+		for (const key of [
+			"title",
+			"description",
+			"select"
+		]) if (s[key] !== void 0 && typeof s[key] !== "string") fail(`"${key}" must be a string`);
+		if (s.workers !== void 0 && s.workers !== "auto" && !isCount(s.workers)) fail("\"workers\" must be \"auto\" or a positive whole number");
+		if (s.maxWorkers !== void 0 && !isCount(s.maxWorkers)) fail("\"maxWorkers\" must be a positive whole number");
+		if (s.codec !== void 0 && s.codec !== "h264" && s.codec !== "vp9") fail("\"codec\" must be \"h264\" or \"vp9\"");
+		if (s.quality !== void 0 && !QUALITIES.includes(s.quality)) fail(`"quality" must be one of ${QUALITIES.join(", ")}`);
+		if (s.output !== void 0 && typeof s.output !== "string") fail("\"output\" must be a file path");
+		out[name] = s;
+	}
+	return out;
+}
+/**
+* The named render `name` of the project at `cwd`, or undefined when there
+* is no render by that name (an entry path, say).
+*/
+function findRender(cwd, name) {
+	const spec = readConfig(cwd).config.renders?.[name];
+	return spec && {
+		...spec,
+		name
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCount(value) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 1;
+}
+function isRelativePath(value) {
+	return typeof value === "string" && value.length > 0 && !value.startsWith("/") && !value.split(/[/\\]/).includes("..");
+}
+
+//#endregion
+//#region src/cli/assets.ts
+/**
+* `framefields assets`: media kept out of git, on an S3-compatible bucket
+* (R2, S3, B2, MinIO), pinned by content in `framefields.json`.
+*
+*   add <path...>   hash, upload what the bucket lacks, record, gitignore
+*   push            upload recorded assets the bucket lacks
+*   pull            download missing assets, verified byte for byte
+*   status          which assets are here, missing, or changed
+*
+* Reads need no keys when the remote has a `publicUrl` (a custom domain or
+* CDN in front of the bucket); otherwise they're signed with the remote's
+* keys. Cloud renders get signed URLs for private assets from the CLI, so
+* the keys never leave the machine.
+*/
+var AssetsError = class extends Error {
+	name = "AssetsError";
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+	}
+};
+/** Hashes and uploads files (folders: every file in them), and records them. */
+async function addAssets(paths, options) {
+	const { cwd } = options;
+	const { config } = readConfig(cwd);
+	const { name, remote } = pickRemote(config.storage, options.remote);
+	const bucket = openBucket(config.storage, name, options);
+	const files = paths.flatMap((p) => expand(cwd, p));
+	if (files.length === 0) throw new AssetsError(`No files in ${paths.join(", ")}.`, "not_found");
+	const added = [];
+	const assets = { ...config.assets };
+	for (const file of files) {
+		const digest = await hashFile(join(cwd, file));
+		const uploaded = !await bucket.has(digest.sha256, digest.size);
+		if (uploaded) await upload(bucket, cwd, file, digest, options.log);
+		const isDefault = name === pickRemote(config.storage).name;
+		assets[file] = {
+			...digest,
+			...!isDefault && { remote: name }
+		};
+		added.push({
+			path: file,
+			size: digest.size,
+			uploaded
+		});
+	}
+	writeConfig(cwd, {
+		...config,
+		assets: sortKeys(assets)
+	});
+	ignore(cwd, files);
+	const tracked = trackedByGit(cwd, files);
+	if (tracked.length) options.log?.(`Already committed to git: ${tracked.join(", ")}. Stop tracking them with \`git rm --cached ${tracked.join(" ")}\` (the files stay here).`);
+	if (remote.publicUrl === void 0) options.log?.(`${name} has no publicUrl: cloud renders from the CLI sign reads, dashboard renders can't read it.`);
+	return added;
+}
+/** Uploads every recorded asset its bucket lacks, from the local file. */
+async function pushAssets(options) {
+	const { config } = readConfig(options.cwd);
+	const uploaded = [];
+	const present = [];
+	const problems = [];
+	for (const [path$1, entry] of storedAssets(config.assets)) {
+		const bucket = openBucket(config.storage, entry.remote, options);
+		if (await bucket.has(entry.sha256, entry.size)) {
+			present.push(path$1);
+			continue;
+		}
+		const state = await localState(options.cwd, path$1, entry);
+		if (state !== "ok") {
+			problems.push(`${path$1} (${state} here)`);
+			continue;
+		}
+		await upload(bucket, options.cwd, path$1, entry, options.log);
+		uploaded.push(path$1);
+	}
+	if (problems.length) throw new AssetsError(`Not on the bucket, and the local file doesn't match ${CONFIG_FILE}: ${problems.join(", ")}. Restore the file, or record the new version with \`framefields assets add\`.`, "not_uploaded");
+	return {
+		uploaded,
+		present
+	};
+}
+/**
+* Downloads every asset that's missing here. Files changed locally are
+* left alone (and reported) unless `overwrite`.
+*/
+async function pullAssets(options) {
+	const { config } = readConfig(options.cwd);
+	const result = {
+		downloaded: [],
+		present: [],
+		changed: []
+	};
+	for (const [path$1, entry] of Object.entries(config.assets ?? {})) {
+		const state = await localState(options.cwd, path$1, entry);
+		if (state === "ok") {
+			result.present.push(path$1);
+			continue;
+		}
+		if (state === "changed" && !options.overwrite) {
+			result.changed.push(path$1);
+			continue;
+		}
+		const url = await readableUrl(entry, config.storage, options);
+		options.log?.(`Downloading ${path$1} (${megabytes(entry.size)})`);
+		await downloadVerified(url, join(options.cwd, path$1), entry, {
+			fetch: options.fetch,
+			signal: options.signal
+		});
+		result.downloaded.push(path$1);
+	}
+	return result;
+}
+/** Each recorded asset's state here: present and matching, missing, or changed. */
+async function assetStatus(cwd) {
+	const { config } = readConfig(cwd);
+	return Promise.all(Object.entries(config.assets ?? {}).map(async ([path$1, entry]) => ({
+		path: path$1,
+		size: entry.size,
+		state: await localState(cwd, path$1, entry)
+	})));
+}
+/**
+* Before a cloud render: uploads assets the bucket lacks (when there are
+* keys), checks public ones are reachable, and signs reads of private ones.
+* Returns the signed URLs by sha256, for the render request.
+*/
+async function prepareCloudAssets(options) {
+	const { config } = readConfig(options.cwd);
+	const signed = {};
+	const missing = [];
+	for (const [path$1, entry] of storedAssets(config.assets)) {
+		const { name, remote } = pickRemote(config.storage, entry.remote);
+		const keys = credentialsFromEnv(name, options.env);
+		if (!keys) {
+			if (!remote.publicUrl) throw noCredentials(name, path$1);
+			if (!await reachable(readUrl(entry, config.storage), options.fetch)) missing.push(path$1);
+			continue;
+		}
+		const bucket = new Bucket(remote, keys, { fetch: options.fetch });
+		if (!await bucket.has(entry.sha256, entry.size)) {
+			if (await localState(options.cwd, path$1, entry) !== "ok") {
+				missing.push(path$1);
+				continue;
+			}
+			await upload(bucket, options.cwd, path$1, entry, options.log);
+		}
+		if (!remote.publicUrl) signed[entry.sha256] = await bucket.presign(entry.sha256, options.expiresSec ?? 86400);
+	}
+	if (missing.length) throw new AssetsError(`Not on the bucket: ${missing.join(", ")}. Run \`framefields assets push\` from a machine that has them (and the remote's keys).`, "not_uploaded");
+	return signed;
+}
+/** Assets kept on a remote (not pinned to a fixed `url`). */
+function storedAssets(assets) {
+	return Object.entries(assets ?? {}).filter(([, entry]) => !entry.url);
+}
+async function localState(cwd, path$1, entry) {
+	const file = join(cwd, path$1);
+	if (!existsSync(file)) return "missing";
+	if (statSync(file).size !== entry.size) return "changed";
+	return (await hashFile(file)).sha256 === entry.sha256 ? "ok" : "changed";
+}
+async function readableUrl(entry, storage, options) {
+	const url = readUrl(entry, storage);
+	if (url) return url;
+	return openBucket(storage, entry.remote, options).presign(entry.sha256, 3600);
+}
+function openBucket(storage, remoteName, options) {
+	const { name, remote } = pickRemote(storage, remoteName);
+	const keys = credentialsFromEnv(name, options.env);
+	if (!keys) throw noCredentials(name);
+	return new Bucket(remote, keys, { fetch: options.fetch });
+}
+function noCredentials(remote, path$1) {
+	const [id, secret] = credentialEnvNames(remote);
+	return new AssetsError(`${path$1 ? `${path$1} is on ${remote}, which` : `Remote ${remote}`} needs keys: set ${id} and ${secret} (or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)${path$1 ? ", or give it a publicUrl" : ""}.`, "no_credentials");
+}
+async function upload(bucket, cwd, path$1, digest, log) {
+	log?.(`Uploading ${path$1} (${megabytes(digest.size)})`);
+	let shown = 0;
+	await bucket.upload(join(cwd, path$1), digest, ({ sent, total }) => {
+		const percent = Math.floor(sent / total * 10) * 10;
+		if (total > 64e6 && percent > shown && percent < 100) {
+			shown = percent;
+			log?.(`  ${percent}%`);
+		}
+	});
+}
+async function reachable(url, fetchImpl = fetch) {
+	return (await fetchImpl(url, { method: "HEAD" }).catch(() => void 0))?.ok ?? false;
+}
+/** Project-relative POSIX paths of `path`, or of every file under it. */
+function expand(cwd, path$1) {
+	const abs = resolve(cwd, path$1);
+	const rel = relative(cwd, abs).split(sep).join("/");
+	if (!isAssetPath(rel) || rel.startsWith("../")) throw new AssetsError(`${path$1} is outside the project.`, "outside_project");
+	if (!existsSync(abs)) throw new AssetsError(`${path$1} does not exist.`, "not_found");
+	if (!statSync(abs).isDirectory()) return [rel];
+	return readdirSync(abs, { withFileTypes: true }).filter((d) => !d.name.startsWith(".")).flatMap((d) => expand(cwd, `${rel}/${d.name}`)).sort();
+}
+const IGNORE_HEADER = "# framefields assets: on the bucket, pinned in framefields.json";
+/** Adds the files to .gitignore, under one marked block. */
+function ignore(cwd, files) {
+	const file = join(cwd, ".gitignore");
+	const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+	const lines = new Set(text.split("\n"));
+	const fresh = files.map((f) => `/${f}`).filter((l) => !lines.has(l));
+	if (fresh.length === 0) return;
+	const header = lines.has(IGNORE_HEADER) ? [] : [IGNORE_HEADER];
+	appendFileSync(file, `${text && !text.endsWith("\n") ? "\n" : ""}${[...header, ...fresh].join("\n")}\n`);
+}
+function trackedByGit(cwd, files) {
+	try {
+		return execFileSync("git", [
+			"ls-files",
+			"--",
+			...files
+		], {
+			cwd,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).split("\n").filter(Boolean);
+	} catch {
+		return [];
+	}
+}
+function sortKeys(assets) {
+	return Object.fromEntries(Object.entries(assets).sort(([a], [b]) => a.localeCompare(b)));
+}
+function megabytes(bytes) {
+	return `${(bytes / 1e6).toFixed(bytes < 1e7 ? 1 : 0)} MB`;
+}
+const ASSETS_USAGE = `Usage: framefields assets add <path...> [--remote <name>]
+       framefields assets push | pull [--overwrite] | status [--json]
+`;
+/** The `framefields assets` command. */
+async function runAssets([sub, ...paths], options) {
+	const log = options.log ?? (() => {});
+	if (sub === "add" && paths.length > 0) {
+		const added = await addAssets(paths, options);
+		const sent = added.filter((a) => a.uploaded).length;
+		log(`Recorded ${added.length} asset${added.length === 1 ? "" : "s"} in ${CONFIG_FILE} (${sent} uploaded, ${added.length - sent} already on the bucket). Commit ${CONFIG_FILE} and .gitignore.`);
+		return 0;
+	}
+	if (sub === "push") {
+		const { uploaded, present } = await pushAssets(options);
+		log(`Uploaded ${uploaded.length}; ${present.length} already on the bucket.`);
+		return 0;
+	}
+	if (sub === "pull") {
+		const { downloaded, present, changed } = await pullAssets(options);
+		log(`Downloaded ${downloaded.length}; ${present.length} already here.`);
+		if (changed.length) log(`Changed here, left alone: ${changed.join(", ")}. \`framefields assets add\` records them, --overwrite restores them.`);
+		return changed.length ? 1 : 0;
+	}
+	if (sub === "status") {
+		const entries = await assetStatus(options.cwd);
+		if (options.json) log(JSON.stringify({ assets: entries }));
+		else if (entries.length === 0) log(`No assets in ${CONFIG_FILE}.`);
+		else for (const e of entries) log(`${e.state.padEnd(8)} ${e.path} (${megabytes(e.size)})`);
+		return entries.some((e) => e.state !== "ok") ? 1 : 0;
+	}
+	process.stderr.write(ASSETS_USAGE);
+	return 2;
+}
+
+//#endregion
+//#region src/cloud/git-source.ts
+/**
+* Where a cloud render gets the project from: the git repo the working
+* directory is in, at the commit checked out now. Cloud workers fetch from
+* the remote, so that commit has to be pushed; uncommitted changes are not
+* rendered.
+*/
+/** Reads repo, branch, commit and folder from git, and checks the commit is pushed. */
+function resolveGitSource(cwd, entry) {
+	const git = (...args) => execFileSync("git", args, {
+		cwd,
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	}).trim();
+	let root;
+	try {
+		root = git("rev-parse", "--show-toplevel");
+	} catch {
+		throw new Error(`${cwd} is not in a git repository. Cloud renders fetch the project from git: commit it and push it to a remote first.`);
+	}
+	const workdir = path.relative(realpathSync(root), realpathSync(cwd)).split(path.sep).join("/") || ".";
+	const relEntry = path.relative(cwd, path.resolve(cwd, entry)).split(path.sep).join("/");
+	if (relEntry.startsWith("../") || path.isAbsolute(relEntry)) throw new Error(`${entry} is outside ${cwd}; run from the project folder that contains it.`);
+	const branch = git("rev-parse", "--abbrev-ref", "HEAD");
+	const commit = git("rev-parse", "HEAD");
+	const remoteName = upstreamRemote(git, branch) ?? "origin";
+	let remoteUrl;
+	try {
+		remoteUrl = git("remote", "get-url", remoteName);
+	} catch {
+		throw new Error(`The repository has no "${remoteName}" remote. Push the project to a git host first.`);
+	}
+	if (!git("branch", "-r", "--contains", commit)) throw new Error(`Commit ${commit.slice(0, 7)} is not on ${remoteName}. Push it first (\`git push\`): cloud workers fetch the project from the remote.`);
+	const dirty = git("status", "--porcelain", "--untracked-files=no", "--", ".");
+	return {
+		source: {
+			repo: toHttps(remoteUrl),
+			...branch !== "HEAD" && { ref: branch },
+			commit,
+			workdir
+		},
+		entry: relEntry,
+		warnings: dirty ? [`Uncommitted changes are not rendered: the cloud renders commit ${commit.slice(0, 7)}.`] : []
+	};
+}
+function upstreamRemote(git, branch) {
+	if (branch === "HEAD") return void 0;
+	try {
+		return git("config", `branch.${branch}.remote`) || void 0;
+	} catch {
+		return;
+	}
+}
+/** `git@github.com:acme/films.git` → `https://github.com/acme/films.git`; credentials dropped. */
+function toHttps(url) {
+	const scp = /^[\w.-]+@([^:/]+):(.+)$/.exec(url);
+	if (scp) return `https://${scp[1]}/${scp[2]}`;
+	const parsed = URL.canParse(url) ? new URL(url) : void 0;
+	if (parsed && (parsed.protocol === "ssh:" || parsed.protocol === "git:")) return `https://${parsed.hostname}${parsed.pathname}`;
+	if (parsed?.protocol === "https:" || parsed?.protocol === "http:") {
+		parsed.username = "";
+		parsed.password = "";
+		return parsed.toString();
+	}
+	return url;
+}
+
+//#endregion
+//#region src/cloud/index.ts
+/**
+* Cloud renders on api.framefields.dev: the project renders from git on
+* framefields' GPU workers, billed to the account that owns the API key.
+*
+* ```ts
+* import { renderCloud } from "framefields/cloud";
+*
+* const result = await renderCloud({
+*   render: "film", // a render named in framefields.json
+*   outputPath: "output/film.mp4",
+*   onProgress: (s) => console.log(s.status, s.progress.frames),
+* });
+* ```
+*
+* Without a framefields.json, name the module instead: `entry: "src/film.ts"`
+* (and `export`, `workers`, …). Options passed here override the named
+* render's.
+*
+* `workers: "auto"` probes the film on one worker first, then splits it into
+* as many chunks as stay efficient: short films stay on one worker, long ones
+* spread out up to `maxWorkers`. `dryRun: true` returns that plan with the
+* estimated cost and renders nothing. Aborting `signal` cancels the render;
+* GPU time already used is charged.
+*/
+const FRAMEFIELDS_API_URL = "https://api.framefields.dev";
+/** A cloud render that failed, was cancelled, or was refused by the API. */
+var CloudRenderError = class extends Error {
+	constructor(message, code, status) {
+		super(message);
+		this.code = code;
+		this.status = status;
+		this.name = "CloudRenderError";
+	}
+};
+const DONE = new Set([
+	"planned",
+	"completed",
+	"failed",
+	"cancelled"
+]);
+/** Starts a cloud render and waits for it; resolves when it completed (or was planned). */
+async function renderCloud(options) {
+	const api = cloudClient(options);
+	const cwd = options.cwd ?? process.cwd();
+	const o = withNamedRender(cwd, options);
+	const resolved = options.source ? {
+		source: options.source,
+		entry: o.entry,
+		warnings: []
+	} : resolveGitSource(cwd, o.entry);
+	const warn = options.onWarning ?? ((m) => process.stderr.write(`framefields: ${m}\n`));
+	for (const w of resolved.warnings) warn(w);
+	const assets = await cloudAssets(cwd, options);
+	let status = await api.start({
+		source: Object.keys(assets).length ? {
+			...resolved.source,
+			assets
+		} : resolved.source,
+		target: {
+			entry: resolved.entry,
+			export: o.export ?? "buildFilm",
+			...o.args !== void 0 && { args: o.args },
+			...o.select && { select: [o.select] }
+		},
+		render: {
+			codec: o.codec ?? "h264",
+			...o.quality && { quality: o.quality }
+		},
+		workers: o.workers ?? 1,
+		...o.maxWorkers && { max_workers: o.maxWorkers },
+		dry_run: options.dryRun ?? false,
+		...o.name && { name: o.name },
+		...o.title && { title: o.title }
+	});
+	options.onProgress?.(status);
+	try {
+		while (!DONE.has(status.status)) {
+			await sleep(options.pollMs ?? 3e3, options.signal);
+			status = await api.status(status.id);
+			options.onProgress?.(status);
+		}
+	} catch (err) {
+		if (options.signal?.aborted) throw new CloudRenderError("The cloud render was cancelled.", "cancelled", await api.cancel(status.id).catch(() => status));
+		throw err;
+	}
+	if (status.status === "failed" || status.status === "cancelled") throw new CloudRenderError(status.error ? `Cloud render ${status.status}: ${status.error.message} (${status.error.code})` : `Cloud render ${status.status}.`, status.error?.code ?? status.status, status);
+	if (status.status === "completed" && options.outputPath && status.output) {
+		await download(status.output.url, options.outputPath, options.signal);
+		return {
+			...status,
+			filePath: options.outputPath
+		};
+	}
+	return status;
+}
+/**
+* Uploads assets the bucket lacks and signs reads of private ones: the
+* workers download each asset framefields.json pins at the commit.
+*/
+async function cloudAssets(cwd, options) {
+	try {
+		return await prepareCloudAssets({
+			cwd,
+			signal: options.signal,
+			log: options.onLog ?? ((m) => process.stderr.write(`framefields: ${m}\n`))
+		});
+	} catch (err) {
+		if (err instanceof AssetsError) throw new CloudRenderError(err.message, `assets_${err.code}`);
+		throw err;
+	}
+}
+/**
+* The options with a named render's fields filled in where the caller left
+* them out, plus the name and title the dashboard shows.
+*/
+function withNamedRender(cwd, options) {
+	if (!options.render) {
+		if (!options.entry) throw new CloudRenderError("Name a render from framefields.json (render) or a module (entry).", "invalid_request");
+		return {
+			...options,
+			entry: options.entry
+		};
+	}
+	const spec = findRender(cwd, options.render);
+	if (!spec) {
+		const names = Object.keys(readConfig(cwd).config.renders ?? {});
+		throw new CloudRenderError(names.length ? `No render named "${options.render}" in ${CONFIG_FILE}. Renders: ${names.join(", ")}.` : `No render named "${options.render}": ${CONFIG_FILE} has no "renders".`, "render_not_found");
+	}
+	const defined = Object.fromEntries(Object.entries(options).filter(([, v]) => v !== void 0));
+	return {
+		entry: spec.entry,
+		export: spec.export,
+		args: spec.args,
+		select: spec.select,
+		workers: spec.workers,
+		maxWorkers: spec.maxWorkers,
+		codec: spec.codec,
+		quality: spec.quality,
+		...defined,
+		name: spec.name,
+		title: spec.title ?? spec.name
+	};
+}
+/** The API calls behind `renderCloud`, for callers who track renders themselves. */
+function cloudClient(options) {
+	const key = options.apiKey ?? process.env.FRAMEFIELDS_API_KEY;
+	if (!key) throw new CloudRenderError("No API key. Set FRAMEFIELDS_API_KEY (keys at https://framefields.dev/dashboard/keys) or pass apiKey.", "invalid_api_key");
+	const base = (options.apiUrl ?? process.env.FRAMEFIELDS_API_URL ?? FRAMEFIELDS_API_URL).replace(/\/+$/, "");
+	const call = async (method, route, body) => {
+		const res = await fetch(`${base}/v1/render${route}`, {
+			method,
+			headers: {
+				Authorization: `Bearer ${key}`,
+				"Content-Type": "application/json"
+			},
+			...body !== void 0 && { body: JSON.stringify(body) }
+		});
+		const json = await res.json().catch(() => ({}));
+		if (!res.ok) throw new CloudRenderError(json.error?.message ?? `api.framefields.dev answered HTTP ${res.status}`, json.error?.type ?? `http_${res.status}`);
+		return fromApi(json);
+	};
+	return {
+		start: (body) => call("POST", "", body),
+		status: (id) => call("GET", `/${encodeURIComponent(id)}`),
+		cancel: (id) => call("DELETE", `/${encodeURIComponent(id)}`)
+	};
+}
+function fromApi(s) {
+	return {
+		id: s.id,
+		status: s.status,
+		workers: s.workers ?? 1,
+		...s.plan && { plan: {
+			workers: s.plan.workers,
+			workSec: s.plan.work_sec,
+			etaSec: s.plan.eta_sec,
+			chunks: s.plan.chunks
+		} },
+		progress: {
+			frames: s.progress?.frames ?? 0,
+			totalFrames: s.progress?.total_frames ?? null,
+			etaSec: s.progress?.eta_sec ?? null
+		},
+		costUsd: s.cost_usd ?? 0,
+		gpuSeconds: s.gpu_seconds ?? 0,
+		...s.estimate_usd !== void 0 && { estimateUsd: s.estimate_usd },
+		...s.sha && { sha: s.sha },
+		...s.output && { output: s.output },
+		...s.error && { error: s.error }
+	};
+}
+async function download(url, file, signal) {
+	const res = await fetch(url, { signal });
+	if (!res.ok || !res.body) throw new CloudRenderError(`Downloading the render failed: HTTP ${res.status}`, "download_failed");
+	await fs$1.mkdir(path.dirname(path.resolve(file)), { recursive: true });
+	await pipeline(Readable.fromWeb(res.body), createWriteStream(file));
+}
+function sleep(ms, signal) {
+	return new Promise((resolve$1, reject) => {
+		if (signal?.aborted) return reject(signal.reason);
+		const timer = setTimeout(resolve$1, ms);
+		signal?.addEventListener("abort", () => {
+			clearTimeout(timer);
+			reject(signal.reason);
+		}, { once: true });
+	});
+}
+
+//#endregion
+export { withNamedRender as a, AssetsError as c, runAssets as d, CONFIG_FILE as f, writeConfig as h, renderCloud as i, megabytes as l, readConfig as m, FRAMEFIELDS_API_URL as n, resolveGitSource as o, findRender as p, cloudClient as r, toHttps as s, CloudRenderError as t, pullAssets as u };
+//# sourceMappingURL=cloud-Cj1TIme8.mjs.map