Skip to content

Code-first video & image, rendered natively on WebGPU.

21.5 KB
Raw Blame
#!/usr/bin/env node
/**
 * The `framefields` command.
 *
 *   npx framefields init [dir]           start a project (or add framefields to one)
 *   npx framefields add <name...>        copy components into this project
 *   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 assets add|push|pull|status   media on your own bucket
 *   npx framefields renders              the renders named in framefields.json
 *   npx framefields render <name>        render on this machine's GPU
 *   npx framefields render <name> --cloud    render on api.framefields.dev
 *   npx framefields preview <name>       play it in the browser
 */
import { existsSync, readFileSync } from "node:fs";
import { join, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { parseArgs } from "node:util";
import { type AddReport, add } from "./cli/add.js";
import { runAssets } from "./cli/assets.js";
import { runCheck } from "./cli/check.js";
import { runCloudRender } from "./cli/cloud.js";
import { readConfig } from "./cli/config.js";
import {
	FONTS,
	type FontSpec,
	installFont,
	lfsHint,
	writeFontsModule,
} from "./cli/fonts.js";
import {
	type InitReport,
	init,
	ownVersion,
	PACKAGE_MANAGERS,
	type PackageManager,
	shownPath,
} from "./cli/init.js";
import { runLocal } from "./cli/local.js";
import { openRegistry } from "./cli/registry.js";
import { AI_DASHBOARD } from "./cli/templates.js";

const HELP = `Usage: framefields <command> [options]

Commands:
  api             JSON reference generated from timing, grid and check types.
  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,
                  LFS .gitattributes, and the themes' fonts. Never
                  overwrites; existing files only gain what they lack.
  add <name...>   Copy components' source into this project (and the
                  components they build on). The code is yours to edit.
  list            List the components you can add.
  fonts add <role...>
                  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.
  assets add <path...>
                  Keep media out of git: hash files (or every file in a
                  folder), upload them to the project's bucket (R2, S3, any
                  S3-compatible storage) and pin them in framefields.json.
  assets push     Upload recorded assets the bucket lacks.
  assets pull     Download missing assets, checked against their sha256.
  assets status   Which assets are here, missing or changed.
  renders         List the renders named in framefields.json.
  render [name|entry]
                  Render on this machine: 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. Pinned assets missing
                  here are downloaded first.
  render [name|entry] --cloud
                  The same render on api.framefields.dev, from the pushed
                  commit of this git repo, downloaded to the same file.
                  Needs FRAMEFIELDS_API_KEY.
  preview [name|entry]
                  Play it in the browser (localhost, WebGPU). Pinned assets
                  that aren't here stream from their bucket.

Options for check:
  --export <name>   Composition or builder export (default buildFilm).
  --render          Also verify the GPU and render a small frame/grid.
  --output <dir>    Inspection artifacts (default output/check).
  --timeout <ms>    Worker timeout in milliseconds (default 60000).
  --warnings-as-errors  Fail on lint warnings.
  --json            Machine-readable check, component list, or font list result.

Options for render and preview:
  --export, --select, --codec, --quality and --output (render) override the
  named render's fields, locally and with --cloud.

Options for render --cloud:
  --workers <n|auto>  1 (default) renders on one GPU. auto measures the film
                    first and splits it across as many GPUs as stay
                    efficient; a number splits it into that many.
  --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/<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.
  --json            Print the final status as JSON.
  Ctrl-C cancels the render; GPU time already used is charged.

Options for assets:
  --remote <name>   The remote in framefields.json "storage" (default: its
                    default, or its only one).
  --overwrite       pull: replace files changed locally.
  Keys: FRAMEFIELDS_STORAGE_<REMOTE>_ACCESS_KEY_ID and _SECRET_ACCESS_KEY,
  or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Reads need none when the
  remote has a publicUrl (a custom domain or CDN in front of the bucket).

Options for init:
  --name <name>     Package name (default: the folder's name).
  --pm <manager>    npm, pnpm, yarn or bun (default: the one running this).
  --install         Install dependencies afterwards.
  --no-fonts        Skip fonts (Inter, JetBrains Mono, Noto Color Emoji).
  --no-emoji        Skip the color emoji font.
  --no-git          Don't run \`git init\`.

Options for add:
  --all             Add every component.
  --dir <path>      Components directory (default: from framefields.json,
                    else src/components or components). Saved the first time.
  --overwrite       Replace files you have changed.
  --no-fonts        Don't install the fonts components ask for (emoji).

Options for add and fonts add:
  --fonts-dir <path>  Where downloaded fonts go (default assets/fonts).

Options for add and list:
  --registry <src>  A registry folder or http(s) URL instead of the one
                    shipped with this version of framefields.
  -h, --help        Show this help.

Examples:
  npx framefields init my-film --install
  npx framefields add mouse-pointer focus-zoom
  npx framefields fonts add emoji
  npx framefields assets add assets/footage
  npx framefields preview film
  npx framefields render film
  npx framefields render film --cloud --plan
`;

async function main(argv: string[]): Promise<number> {
	const { values, positionals } = parseArgs({
		args: argv,
		allowPositionals: true,
		options: {
			all: { type: "boolean" },
			dir: { type: "string" },
			overwrite: { type: "boolean" },
			"no-fonts": { type: "boolean" },
			"no-emoji": { type: "boolean" },
			"fonts-dir": { type: "string" },
			name: { type: "string" },
			pm: { type: "string" },
			install: { type: "boolean" },
			emoji: { type: "boolean" },
			"no-git": { type: "boolean" },
			registry: { type: "string" },
			json: { type: "boolean" },
			export: { type: "string" },
			render: { type: "boolean" },
			output: { type: "string" },
			timeout: { type: "string" },
			"warnings-as-errors": { type: "boolean" },
			cloud: { type: "boolean" },
			workers: { type: "string" },
			"max-workers": { type: "string" },
			plan: { type: "boolean" },
			codec: { type: "string" },
			quality: { type: "string" },
			select: { type: "string" },
			remote: { type: "string" },
			help: { type: "boolean", short: "h" },
		},
	});
	const [command, ...names] = positionals;
	if (values.help || !command) {
		process.stdout.write(HELP);
		return command || values.help ? 0 : 1;
	}
	const cwd = process.cwd();
	// The project's settings (FRAMEFIELDS_API_KEY, storage keys), as its own
	// scripts load them; variables already set win.
	if (existsSync(join(cwd, ".env"))) process.loadEnvFile(join(cwd, ".env"));
	const log = (line: string) => process.stdout.write(`${line}\n`);
	if (command === "api") {
		const catalog = JSON.parse(
			readFileSync(
				fileURLToPath(
					new URL(
						import.meta.url.endsWith(".ts") ? "../dist/api.json" : "./api.json",
						import.meta.url,
					),
				),
				"utf8",
			),
		) as object;
		log(JSON.stringify({ ...catalog, sdkVersion: ownVersion() }));
		return 0;
	}
	if (command === "check") return check(names, cwd, values, log);
	if (command === "renders") return listRenders(cwd, values.json, log);
	if (command === "assets")
		return runAssets(names, {
			cwd,
			log,
			remote: values.remote,
			overwrite: values.overwrite,
			json: values.json,
		});
	if (command === "preview" || (command === "render" && !values.cloud)) {
		if (names.length > 1) {
			process.stderr.write(
				`Usage: framefields ${command} [name|entry] [--export <name>]\n`,
			);
			return 2;
		}
		return runLocal(
			command === "preview" ? "preview" : "render",
			{
				entry: names[0],
				export: values.export,
				select: values.select,
				codec: values.codec,
				quality: values.quality,
				output: values.output,
			},
			log,
		);
	}
	if (command === "render") {
		if (names.length > 1) {
			process.stderr.write(
				"Usage: framefields render [name|entry] --cloud [--workers auto] [--plan]\n",
			);
			return 2;
		}
		return runCloudRender(
			{
				entry: names[0],
				export: values.export,
				select: values.select,
				workers: values.workers,
				maxWorkers: values["max-workers"],
				codec: values.codec,
				quality: values.quality,
				output: values.output,
				plan: values.plan,
				json: values.json,
			},
			log,
		);
	}
	if (command === "fonts") return fonts(names, cwd, values, log);
	if (command === "init") {
		if (names.length > 1) {
			process.stderr.write(
				"init takes one folder: `framefields init my-film`.\n",
			);
			return 1;
		}
		if (values.pm && !PACKAGE_MANAGERS.includes(values.pm as PackageManager)) {
			process.stderr.write(
				`--pm must be one of ${PACKAGE_MANAGERS.join(", ")}.\n`,
			);
			return 1;
		}
		const report = await init({
			cwd,
			dir: names[0],
			name: values.name,
			packageManager: values.pm as PackageManager | undefined,
			userAgent: process.env.npm_config_user_agent,
			fonts: !values["no-fonts"],
			emoji: values["no-emoji"] ? false : values.emoji,
			git: !values["no-git"],
			install: values.install,
			onDownload,
		});
		logInit(report, cwd, log);
		return 0;
	}
	const registry = openRegistry(values.registry, cwd);

	if (command === "list") {
		const index = await registry.index();
		if (values.json) {
			log(
				JSON.stringify({
					schemaVersion: 1,
					sdkVersion: ownVersion(),
					components: await Promise.all(
						index.map(async (entry) => {
							const { files: _files, ...item } = await registry.item(
								entry.name,
							);
							return item;
						}),
					),
				}),
			);
			return 0;
		}
		const width = Math.max(...index.map((e) => e.name.length));
		for (const e of index)
			process.stdout.write(`${e.name.padEnd(width)}  ${e.summary}\n`);
		return 0;
	}
	if (command !== "add") {
		process.stderr.write(`Unknown command "${command}".\n\n${HELP}`);
		return 1;
	}

	const wanted = values.all
		? (await registry.index()).map((e) => e.name)
		: names;
	if (wanted.length === 0) {
		process.stderr.write(
			"Name the components to add, e.g. `framefields add mouse-pointer`.\nRun `framefields list` to see them all.\n",
		);
		return 1;
	}
	const report = await add(wanted, {
		cwd,
		registry,
		dir: values.dir,
		overwrite: values.overwrite,
		fonts: !values["no-fonts"],
		fontsDir: values["fonts-dir"],
		onDownload,
	});
	for (const f of report.written) log(`  wrote      ${f}`);
	for (const f of report.unchanged) log(`  unchanged  ${f}`);
	for (const f of report.skipped)
		log(`  skipped    ${f} (yours differs; --overwrite replaces it)`);
	if (report.configWritten) log("  wrote      framefields.json");
	logFonts(report, cwd, log);
	const extra = report.components.filter((c) => !wanted.includes(c.name));
	if (extra.length > 0)
		log(`\nWith what they build on: ${extra.map((c) => c.name).join(", ")}.`);
	warnIfMissingFramefields(cwd, log);
	const first = report.components.find((c) => wanted.includes(c.name));
	if (first)
		log(
			`\nimport { ${first.title} } from "./${first.name}/index.js"; // from ${relative(cwd, report.dir) || "."}`,
		);
	return 0;
}

const onDownload = (spec: FontSpec) =>
	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: string[],
	cwd: string,
	values: {
		export?: string;
		render?: boolean;
		output?: string;
		timeout?: string;
		"warnings-as-errors"?: boolean;
		json?: boolean;
	},
	log: (s: string) => void,
): Promise<number> {
	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: { name?: string; entry: string; exportName?: string }[] =
		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 ?? "")
					: undefined),
			timeoutMs:
				values.timeout === undefined ? undefined : 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: string,
	json: boolean | undefined,
	log: (s: string) => void,
): number {
	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 !== undefined && `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: AddReport, cwd: string, log: (s: string) => void) {
	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}\`.`,
		);
	if (report.fontsModule) logFontsModule(report.fontsModule, log);
	const installed = report.fonts.find((f) => f.status === "installed");
	const hint = installed && lfsHint(cwd, installed.path);
	if (hint) log(`\n${hint}`);
	if (report.fonts.some((f) => f.status !== "configured") && report.fontsModule)
		log(
			`\nRegister them once before rendering: \`await registerFonts()\` from ${report.fontsModule.path.replace(/\.ts$/, ".js")}.`,
		);
}

function logFontsModule(
	m: NonNullable<AddReport["fontsModule"]>,
	log: (s: string) => void,
) {
	if (m.status === "written") log(`  wrote      ${m.path}`);
	else if (m.status === "unchanged") log(`  unchanged  ${m.path}`);
	else
		log(
			`  skipped    ${m.path} (not generated by framefields). Register the fonts yourself:\n${m.calls.map((c) => `    ${c}`).join("\n")}`,
		);
}

/** `framefields fonts add <role...>` and `framefields fonts list`. */
async function fonts(
	[sub, ...roles]: string[],
	cwd: string,
	values: {
		overwrite?: boolean;
		"fonts-dir"?: string;
		dir?: string;
		json?: boolean;
	},
	log: (s: string) => void,
): Promise<number> {
	if (sub === "list") {
		const { config } = readConfig(cwd);
		if (values.json) {
			log(
				JSON.stringify({
					schemaVersion: 1,
					sdkVersion: ownVersion(),
					fonts: Object.entries(FONTS).map(([role, spec]) => ({
						role,
						...spec,
						configuredPath: config.fonts?.[role],
					})),
				}),
			);
			return 0;
		}
		for (const [role, spec] of Object.entries(FONTS))
			log(
				`${role.padEnd(6)}  ${spec.label}${config.fonts?.[role] ? `  (installed: ${config.fonts[role]})` : ""}`,
			);
		return 0;
	}
	if (sub !== "add" || roles.length === 0) {
		process.stderr.write(
			`Usage: framefields fonts add <role...>   (roles: ${Object.keys(FONTS).join(", ")})\n       framefields fonts list\n`,
		);
		return 1;
	}
	const unknown = roles.filter((r) => !FONTS[r]);
	if (unknown.length > 0) {
		process.stderr.write(
			`Unknown font ${unknown.map((r) => `"${r}"`).join(", ")}. Fonts framefields can install: ${Object.keys(FONTS).join(", ")}.\n`,
		);
		return 1;
	}
	const { config, saved } = readConfig(cwd);
	const installs = [];
	for (const role of roles)
		installs.push(
			await installFont(role, {
				cwd,
				dir: values["fonts-dir"],
				overwrite: values.overwrite,
				onDownload,
			}),
		);
	for (const f of installs)
		log(
			`  ${f.status === "installed" ? "font      " : "font ok   "} ${f.path} (${f.role})`,
		);
	if (!saved) log("  wrote      framefields.json");
	const module = writeFontsModule(
		cwd,
		resolve(cwd, values.dir ?? config.components),
	);
	logFontsModule(module, log);
	const installed = installs.find((f) => f.status === "installed");
	const hint = installed && lfsHint(cwd, installed.path);
	if (hint) log(`\n${hint}`);
	log(
		`\nRegister them once before rendering: \`await registerFonts()\` from ${module.path.replace(/\.ts$/, ".js")}.`,
	);
	return 0;
}

function logInit(report: InitReport, cwd: string, log: (s: string) => void) {
	const at = shownPath(cwd, report.root);
	for (const f of report.written) log(`  wrote      ${f}`);
	for (const f of report.merged)
		log(`  merged     ${f} (added what it lacked)`);
	for (const f of report.unchanged) log(`  unchanged  ${f}`);
	for (const f of report.fonts)
		log(
			`  ${f.status === "installed" ? "font      " : "font ok   "} ${f.path} (${f.role})`,
		);
	logFontsModule(report.fontsModule, log);
	if (report.git === "initialized")
		log("  git        initialized a repository");
	if (report.git === "unavailable")
		log("  git        not found: skipped `git init`");
	if (report.lfs === false)
		log(
			"\nGit LFS isn't installed. Footage and fonts are tracked with it: install it (https://git-lfs.com), then run `git lfs install` once.",
		);
	else if (report.lfs)
		log("\nRun `git lfs install` once on this machine if you haven't yet.");
	const steps = [
		...(at === "." ? [] : [`cd ${/\s/.test(at) ? JSON.stringify(at) : at}`]),
		...(report.installed ? [] : [`${report.packageManager} install`]),
		`${report.runScript("frames")} -- 0 30 60`,
	];
	log(
		`\n${report.name} is ready. Next:\n${steps.map((s) => `  ${s}`).join("\n")}`,
	);
	log(
		"\nThen edit src/film.ts, and run `npx framefields list` for ready-made components.",
	);
	log(
		`\nOptional: to generate images, video, music, voice and 3D with the framefields AI gateway, get a key at ${AI_DASHBOARD} and put it in .env as FRAMEFIELDS_API_KEY (see .env.example).`,
	);
}

/** Installed components import `framefields`; say so if the project lacks it. */
function warnIfMissingFramefields(cwd: string, log: (s: string) => void) {
	try {
		const pkg = JSON.parse(readFileSync(`${cwd}/package.json`, "utf8")) as {
			dependencies?: Record<string, string>;
			devDependencies?: Record<string, string>;
		};
		if (!pkg.dependencies?.framefields && !pkg.devDependencies?.framefields)
			log(
				"\nThese components import `framefields`: add it with `npm i framefields`.",
			);
	} catch {
		// No package.json: nothing to check.
	}
}

main(process.argv.slice(2)).then(
	(code) => process.exit(code),
	(error: unknown) => {
		process.stderr.write(
			`framefields: ${error instanceof Error ? error.message : String(error)}\n`,
		);
		process.exit(1);
	},
);