framefields 2.10.0-canary.0 → 2.12.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as renderCloud, t as CloudRenderError } from "./cloud-xcfV4J03.mjs";
+import { c as CONFIG_FILE, d as writeConfig, i as renderCloud, l as findRender, t as CloudRenderError, u as readConfig } from "./cloud-COid1Ipa.mjs";
 import { t as failedCheck } from "./check-result-Culfu7Nx.mjs";
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -9,34 +9,6 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 
-//#region src/cli/config.ts
-/**
-* `framefields.json` at the project root: where installed components live,
-* and which fonts `framefields add` / `framefields fonts add` installed.
-*/
-const CONFIG_FILE = "framefields.json";
-/** The project's config, or the default it would get: `src/components` when there is a `src`. */
-function readConfig(cwd) {
-	const file = join(cwd, CONFIG_FILE);
-	if (existsSync(file)) {
-		const config = JSON.parse(readFileSync(file, "utf8"));
-		if (typeof config.components !== "string") throw new Error(`${CONFIG_FILE}: "components" must be a directory path`);
-		if (config.fonts !== void 0 && (typeof config.fonts !== "object" || Object.values(config.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" }`);
-		return {
-			config,
-			saved: true
-		};
-	}
-	return {
-		config: { components: existsSync(join(cwd, "src")) ? "src/components" : "components" },
-		saved: false
-	};
-}
-function writeConfig(cwd, config) {
-	writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify(config, null, "	")}\n`);
-}
-
-//#endregion
 //#region src/cli/fonts.ts
 /**
 * Fonts the CLI installs into a project: a catalog of pinned files (URL,
@@ -308,7 +280,10 @@ async function add(names, options) {
 		report.written.push(shown);
 	}
 	if (!saved) {
-		writeConfig(cwd, { components: relative(cwd, dir) || "." });
+		writeConfig(cwd, {
+			...config,
+			components: relative(cwd, dir) || "."
+		});
 		report.configWritten = true;
 	}
 	const needs = /* @__PURE__ */ new Map();
@@ -344,11 +319,6 @@ async function add(names, options) {
 //#endregion
 //#region src/cli/templates.ts
 /**
-* The files `framefields init` writes: the project layout the framefields
-* setup skill describes. `film.ts` only builds; `render.ts` renders frames,
-* a grid, the live preview or the video; `theme.ts` holds the numbers.
-*/
-/**
 * Packages with install scripts. framefields needs exactly one (skia-canvas
 * downloads its native binary); the others work without theirs.
 */
@@ -369,14 +339,24 @@ const DEV_DEPENDENCIES = {
 };
 const SCRIPTS = {
 	typecheck: "tsc --noEmit -p .",
-	check: "tsc --noEmit -p . && framefields check src/film.ts --json",
-	"check:render": "tsc --noEmit -p . && framefields check src/film.ts --render --json",
+	check: "tsc --noEmit -p . && framefields check film --json",
+	"check:render": "tsc --noEmit -p . && framefields check film --render --json",
 	frames: "tsx src/render.ts frames",
 	grid: "tsx src/render.ts grid",
 	preview: "tsx src/render.ts preview",
 	render: "tsx src/render.ts",
-	"render:cloud": "framefields render src/film.ts --cloud --workers auto"
+	"render:cloud": "framefields render film --cloud"
 };
+/** The named render `init` records in framefields.json. */
+function defaultRenders(name) {
+	return { film: {
+		title: name,
+		entry: "src/film.ts",
+		export: "buildFilm",
+		workers: "auto",
+		output: "output/film.mp4"
+	} };
+}
 /**
 * The `package.json` fields a framefields project needs. npm reads
 * `allowScripts`, pnpm its `pnpm` block, bun `trustedDependencies`.
@@ -575,6 +555,9 @@ ${run("render")}              # output/output.mp4
 ${run("render:cloud")}        # on cloud GPUs, from the pushed commit
 \`\`\`
 
+- \`framefields.json\` names the renders: \`film\` is \`buildFilm\` in \`src/film.ts\`. Add an
+  entry under \`renders\` for each cut (a teaser, a vertical edit) and render or check it by
+  name: \`npx framefields render teaser --cloud\`, \`npx framefields check teaser\`.
 - \`src/film.ts\` builds the composition, \`src/theme.ts\` holds sizes, colors and fonts,
   \`src/render.ts\` renders it.
 - \`npx framefields list\` shows ready-made components; \`npx framefields add <name>\` copies
@@ -687,10 +670,14 @@ async function init(options) {
 		}
 	}
 	for (const [path$1, lines] of [[".gitignore", GITIGNORE], [".gitattributes", GITATTRIBUTES]]) record(report, path$1, appendLines(join(root, path$1), lines));
+	const configExisted = existsSync(join(root, CONFIG_FILE));
 	const { config, saved } = readConfig(root);
-	if (!saved) {
-		writeConfig(root, config);
-		report.written.push("framefields.json");
+	if (!saved || !config.renders) {
+		writeConfig(root, {
+			...config,
+			renders: config.renders ?? defaultRenders(basename(root))
+		});
+		record(report, CONFIG_FILE, configExisted || "written");
 	}
 	const installFonts = options.fonts !== false;
 	const installEmoji = options.emoji ?? installFonts;
@@ -872,14 +859,17 @@ function isCheckReport(value) {
 //#endregion
 //#region src/cli/cloud.ts
 /**
-* `framefields render <entry> --cloud`: renders the project on
-* api.framefields.dev and downloads the video. Prints one plain line per
-* phase, and a progress line at most every 10 seconds while frames render.
+* `framefields render <name|entry> --cloud`: renders the project on
+* api.framefields.dev and downloads the video. `name` is a render in
+* framefields.json; a module path renders without one. Prints one plain
+* line per phase, and a progress line at most every 10 seconds while
+* frames render.
 */
 const PROGRESS_EVERY_MS = 1e4;
 async function runCloudRender(o, log, render = renderCloud) {
+	const cwd = o.cwd ?? process.cwd();
 	const workers = parseWorkers(o.workers);
-	if (workers === void 0) {
+	if (workers === null) {
 		log(`--workers must be "auto" or a positive whole number, not "${o.workers}".`);
 		return 2;
 	}
@@ -887,8 +877,15 @@ async function runCloudRender(o, log, render = renderCloud) {
 		log(`--codec must be h264 or vp9, not "${o.codec}".`);
 		return 2;
 	}
-	const codec = o.codec ?? "h264";
-	const outputPath = o.output ?? path.join("output", `${path.basename(o.entry).replace(/\.[^.]+$/, "")}.${codec === "vp9" ? "webm" : "mp4"}`);
+	const target = pickRender(o.entry, cwd);
+	if ("error" in target) {
+		log(target.error);
+		return 2;
+	}
+	const spec = target.name ? findRender(cwd, target.name) : void 0;
+	const codec = o.codec ?? spec?.codec ?? "h264";
+	const outputPath = o.output ?? spec?.output ?? path.join("output", `${target.name ?? path.basename(target.entry ?? "").replace(/\.[^.]+$/, "")}.${codec === "vp9" ? "webm" : "mp4"}`);
+	const planWorkers = o.plan && (workers ?? spec?.workers ?? 1) === 1 ? "auto" : workers;
 	const controller = new AbortController();
 	const onSigint = () => {
 		log("Cancelling the cloud render…");
@@ -899,12 +896,14 @@ async function runCloudRender(o, log, render = renderCloud) {
 	const narrate = narrator(o.json ? () => {} : log, Date.now);
 	try {
 		const result = await render({
-			entry: o.entry,
+			cwd,
+			render: target.name,
+			entry: target.entry,
 			export: o.export,
 			select: o.select,
-			workers: o.plan && workers === 1 ? "auto" : workers,
+			workers: planWorkers,
 			maxWorkers: o.maxWorkers ? Number(o.maxWorkers) : void 0,
-			codec,
+			codec: o.codec,
 			quality: o.quality,
 			dryRun: o.plan,
 			outputPath: o.plan ? void 0 : outputPath,
@@ -917,7 +916,12 @@ async function runCloudRender(o, log, render = renderCloud) {
 			return 0;
 		}
 		if (result.status === "planned") {
-			log(`Render it: framefields render ${o.entry} --cloud --workers ${o.workers ?? "auto"}`);
+			const planned = planWorkers === "auto" && spec?.workers !== "auto";
+			log(`Render it: ${renderCommand({
+				...o,
+				entry: target.name ?? target.entry,
+				workers: o.workers ?? (planned ? "auto" : void 0)
+			})}`);
 			return 0;
 		}
 		const bytes = result.output?.bytes;
@@ -935,11 +939,40 @@ async function runCloudRender(o, log, render = renderCloud) {
 		process.removeListener("SIGINT", onSigint);
 	}
 }
+/** The command that renders what `--plan` just planned: the same options, without `--plan`. */
+function renderCommand(o) {
+	const flags = [
+		["--export", o.export],
+		["--select", o.select],
+		["--workers", o.workers],
+		["--max-workers", o.maxWorkers],
+		["--codec", o.codec],
+		["--quality", o.quality],
+		["--output", o.output]
+	];
+	return [`framefields render ${o.entry ?? ""} --cloud`.replace("  ", " "), ...flags.filter(([, v]) => v !== void 0).map(([f, v]) => `${f} ${v}`)].join(" ");
+}
+/**
+* What `framefields render [arg]` renders: a render named in framefields.json,
+* or a module path; with no argument, the project's only named render.
+*/
+function pickRender(arg, cwd) {
+	const renders = readConfig(cwd).config.renders ?? {};
+	const names = Object.keys(renders);
+	if (arg === void 0) {
+		if (names.length === 1) return { name: names[0] };
+		return { error: names.length ? `Name the render: ${names.join(", ")}. \`framefields renders\` lists them.` : `Name a module, e.g. \`framefields render src/film.ts --cloud\`, or add "renders" to ${CONFIG_FILE}.` };
+	}
+	if (renders[arg]) return { name: arg };
+	if (existsSync(path.resolve(cwd, arg))) return { entry: arg };
+	return { error: names.length ? `"${arg}" is neither a render in ${CONFIG_FILE} (${names.join(", ")}) nor a file.` : `"${arg}" is not a file, and ${CONFIG_FILE} names no renders.` };
+}
+/** --workers: undefined when not given, null when invalid. */
 function parseWorkers(value) {
-	if (value === void 0) return 1;
+	if (value === void 0) return void 0;
 	if (value === "auto") return "auto";
 	const n = Number(value);
-	return Number.isInteger(n) && n >= 1 ? n : void 0;
+	return Number.isInteger(n) && n >= 1 ? n : null;
 }
 /** Turns status polls into log lines: one per phase, throttled frame progress. */
 function narrator(log, now) {
@@ -1044,14 +1077,18 @@ function openRegistry(source, cwd = process.cwd()) {
 *   npx framefields list                 the components you can add
 *   npx framefields fonts add <role...>  install fonts (emoji)
 *   npx framefields fonts list           the fonts you can install
-*   npx framefields render <entry> --cloud   render on api.framefields.dev
+*   npx framefields renders              the renders named in framefields.json
+*   npx framefields render <name> --cloud    render on api.framefields.dev
 */
 const HELP = `Usage: framefields <command> [options]
 
 Commands:
   api             JSON reference generated from timing, grid and check types.
-  check <entry>   Build, validate and lint a composition; --render also writes a
-                  representative frame and grid. --export defaults to buildFilm.
+  check [name|entry]
+                  Build, validate and lint a composition; --render also writes a
+                  representative frame and grid. A render named in
+                  framefields.json, or a module (--export defaults to
+                  buildFilm); with neither, every named render.
   init [dir]      Start a framefields project in dir (default: here), or add
                   framefields to the project there: package.json, tsconfig,
                   src/theme.ts, film.ts, render.ts, assets/, .gitignore,
@@ -1064,10 +1101,14 @@ Commands:
                   Install fonts (pinned, hash-checked, with their license)
                   and register them in the generated <components>/fonts.ts.
   fonts list      List the fonts you can install.
-  render <entry> --cloud
+  renders         List the renders named in framefields.json.
+  render [name|entry] --cloud
                   Render on api.framefields.dev from the pushed commit of
                   this git repo, and download the video. Needs
-                  FRAMEFIELDS_API_KEY. --export defaults to buildFilm.
+                  FRAMEFIELDS_API_KEY. A render named in framefields.json
+                  (its fields are the defaults; flags override them), or a
+                  module (--export defaults to buildFilm). Without either,
+                  the project's only named render.
 
 Options for check:
   --export <name>   Composition or builder export (default buildFilm).
@@ -1084,7 +1125,7 @@ Options for render --cloud:
   --max-workers <n> Upper bound for auto.
   --plan            Measure and plan only: prints workers, time and the
                     estimated cost, renders nothing.
-  --output <file>   Where the video goes (default output/<entry>.mp4).
+  --output <file>   Where the video goes (default output/<name>.mp4).
   --codec <codec>   h264 (default) or vp9.
   --quality <q>     very_low, low, high or very_high (default).
   --select <name>   When the export returns several compositions.
@@ -1118,7 +1159,7 @@ Examples:
   npx framefields init my-film --install
   npx framefields add mouse-pointer focus-zoom
   npx framefields fonts add emoji
-  npx framefields render src/film.ts --cloud --workers auto --plan
+  npx framefields render film --cloud --plan
 `;
 async function main(argv) {
 	const { values, positionals } = parseArgs({
@@ -1171,30 +1212,11 @@ async function main(argv) {
 		}));
 		return 0;
 	}
-	if (command === "check") {
-		if (names.length !== 1) {
-			process.stderr.write("Usage: framefields check <entry> [--export buildFilm] [--render] [--json]\n");
-			return 2;
-		}
-		const report$1 = await runCheck({
-			entry: names[0],
-			exportName: values.export,
-			render: values.render,
-			outputDir: values.output,
-			timeoutMs: values.timeout === void 0 ? void 0 : Number(values.timeout),
-			warningsAsErrors: values["warnings-as-errors"]
-		});
-		if (values.json) log(JSON.stringify(report$1));
-		else {
-			log(`Check ${report$1.status}: ${report$1.entry} (${report$1.exportName})`);
-			for (const d of report$1.diagnostics) log(`${d.severity} ${d.code}${d.path ? ` at ${d.path}` : ""}: ${d.message}`);
-			for (const file of report$1.artifacts) log(`Wrote ${file}`);
-		}
-		return report$1.status === "passed" ? 0 : 1;
-	}
+	if (command === "check") return check(names, cwd, values, log);
+	if (command === "renders") return listRenders(cwd, values.json, log);
 	if (command === "render") {
-		if (names.length !== 1 || !values.cloud) {
-			process.stderr.write("Usage: framefields render <entry> --cloud [--workers auto] [--plan]\nLocal renders run your project's render script (`npm run render`).\n");
+		if (names.length > 1 || !values.cloud) {
+			process.stderr.write("Usage: framefields render [name|entry] --cloud [--workers auto] [--plan]\nLocal renders run your project's render script (`npm run render`).\n");
 			return 2;
 		}
 		return runCloudRender({
@@ -1284,6 +1306,75 @@ async function main(argv) {
 }
 const onDownload = (spec) => process.stdout.write(`  fetching   ${spec.file} (${(spec.font.bytes / 1e6).toFixed(1)} MB, ${spec.license.id})\n`);
 /** What `add` did about fonts, and how to use them. */
+/** `check [name|entry]`: a named render, a module, or every named render. */
+async function check(names, cwd, values, log) {
+	const renders = readConfig(cwd).config.renders ?? {};
+	const usage = () => {
+		process.stderr.write("Usage: framefields check [name|entry] [--export buildFilm] [--render] [--json]\n");
+		return 2;
+	};
+	if (names.length > 1) return usage();
+	const targets = names.length === 0 ? Object.entries(renders).map(([name, spec]) => ({
+		name,
+		entry: spec.entry,
+		exportName: spec.export
+	})) : renders[names[0]] ? [{
+		name: names[0],
+		entry: renders[names[0]].entry,
+		exportName: values.export ?? renders[names[0]].export
+	}] : [{
+		entry: names[0],
+		exportName: values.export
+	}];
+	if (targets.length === 0) return usage();
+	const reports = [];
+	for (const t of targets) {
+		const report = await runCheck({
+			entry: t.entry,
+			exportName: t.exportName,
+			render: values.render,
+			outputDir: values.output ?? (targets.length > 1 ? join("output", "check", t.name ?? "") : void 0),
+			timeoutMs: values.timeout === void 0 ? void 0 : Number(values.timeout),
+			warningsAsErrors: values["warnings-as-errors"]
+		});
+		reports.push({
+			...t.name && { name: t.name },
+			...report
+		});
+		if (values.json) continue;
+		log(`Check ${report.status}: ${t.name ? `${t.name} (${t.entry}, ${report.exportName})` : `${report.entry} (${report.exportName})`}`);
+		for (const d of report.diagnostics) log(`${d.severity} ${d.code}${d.path ? ` at ${d.path}` : ""}: ${d.message}`);
+		for (const file of report.artifacts) log(`Wrote ${file}`);
+	}
+	const passed = reports.every((r) => r.status === "passed");
+	if (values.json) log(JSON.stringify(names.length === 0 ? {
+		status: passed ? "passed" : "failed",
+		checks: reports
+	} : reports[0]));
+	return passed ? 0 : 1;
+}
+/** `renders`: what framefields.json names, as the dashboard shows it. */
+function listRenders(cwd, json, log) {
+	const renders = readConfig(cwd).config.renders ?? {};
+	if (json) {
+		log(JSON.stringify({
+			schemaVersion: 1,
+			renders
+		}));
+		return 0;
+	}
+	const entries = Object.entries(renders);
+	if (entries.length === 0) {
+		log("framefields.json names no renders. Add one: \"renders\": { \"film\": { \"entry\": \"src/film.ts\", \"export\": \"buildFilm\" } }");
+		return 0;
+	}
+	for (const [name, spec] of entries) {
+		const title = spec.title && spec.title !== name ? `  ${spec.title}` : "";
+		const opts = [spec.workers !== void 0 && `workers ${spec.workers}`, spec.codec].filter(Boolean);
+		log(`${name}${title}\n  ${spec.entry} · ${spec.export ?? "buildFilm"}${spec.select ? ` · ${spec.select}` : ""}${opts.length ? ` · ${opts.join(", ")}` : ""}${spec.description ? `\n  ${spec.description}` : ""}`);
+	}
+	return 0;
+}
 function logFonts(report, cwd, log) {
 	for (const f of report.fonts) log(`  ${f.status === "installed" ? "font      " : "font ok   "} ${f.path} (${f.role}, for ${f.by}: ${f.why})`);
 	for (const f of report.fontsSkipped) log(`  no font    ${f.role} for ${f.by} (--no-fonts): ${f.why} Install later with \`framefields fonts add ${f.role}\`.`);