@odori/cli 0.0.2

package/src/formats.ts

@@ -0,0 +1,119 @@
+/**
+ * What an export can produce.
+ *
+ * One codec is enough until it is not: an overlay needs an alpha channel that
+ * H.264 cannot carry, an editor wants ProRes, a README wants a GIF, and a
+ * thumbnail sheet wants frames. Each of those is a different container and a
+ * different pixel format, so the choice belongs in one table rather than in a
+ * flag that quietly means five things.
+ *
+ * Chunked capture is how a render stays fast, and only some codecs can be
+ * concatenated without re-encoding. `chunked: false` says a format has to be
+ * encoded in one pass, which is slower and correct.
+ */
+export type VideoFormat = {
+  name: string;
+  extension: string;
+  /** Whether the codec supports an alpha channel. */
+  alpha: boolean;
+  /** Whether chunks can be joined with a stream copy. */
+  chunked: boolean;
+  /** Whether the container carries an audio track at all. */
+  audio: boolean;
+  /** FFmpeg arguments for the video stream, given the requested preset. */
+  args: (preset: string) => string[];
+  description: string;
+};
+
+export const FORMATS: Record<string, VideoFormat> = {
+  mp4: {
+    name: "mp4",
+    extension: ".mp4",
+    alpha: false,
+    chunked: true,
+    audio: true,
+    description: "H.264 in MP4. Plays everywhere; the default.",
+    args: (preset) => ["-c:v", "libx264", "-crf", "17", "-preset", preset, "-pix_fmt", "yuv420p"],
+  },
+  webm: {
+    name: "webm",
+    extension: ".webm",
+    alpha: true,
+    // VP9 in WebM concatenates cleanly through the demuxer, same as H.264.
+    chunked: true,
+    audio: true,
+    description: "VP9 in WebM, with alpha. For the web, and for overlays.",
+    args: () => ["-c:v", "libvpx-vp9", "-crf", "24", "-b:v", "0", "-pix_fmt", "yuva420p", "-row-mt", "1"],
+  },
+  prores: {
+    name: "prores",
+    extension: ".mov",
+    alpha: true,
+    chunked: true,
+    audio: true,
+    description: "ProRes 4444 in MOV, with alpha. For handing to an editor.",
+    args: () => ["-c:v", "prores_ks", "-profile:v", "4444", "-pix_fmt", "yuva444p10le", "-alpha_bits", "8"],
+  },
+  gif: {
+    name: "gif",
+    extension: ".gif",
+    alpha: false,
+    // A GIF's palette is computed across the whole animation, so chunks would
+    // each invent their own and the result would flicker between them.
+    chunked: false,
+    audio: false,
+    description: "An animated GIF, palette optimised. Silent, by the format.",
+    args: () => [
+      "-vf",
+      "split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=3",
+      "-loop",
+      "0",
+    ],
+  },
+  png: {
+    name: "png",
+    extension: ".png",
+    alpha: true,
+    chunked: false,
+    audio: false,
+    description: "A numbered PNG sequence, with alpha. For a compositor.",
+    args: () => ["-c:v", "png", "-pix_fmt", "rgba"],
+  },
+};
+
+export const formatNames = (): string[] => Object.keys(FORMATS);
+
+/**
+ * The format for an export.
+ *
+ * An explicit `--format` wins. Otherwise the output's extension decides, so
+ * `--output cut.webm` does what it looks like it does rather than writing
+ * H.264 into a file named `.webm`.
+ */
+export const resolveFormat = (requested: string | undefined, output: string | undefined): VideoFormat => {
+  if (requested) {
+    const format = FORMATS[requested.toLowerCase()];
+    if (!format) {
+      throw new Error(`Unknown format "${requested}". Available: ${formatNames().join(", ")}`);
+    }
+    return format;
+  }
+  if (output) {
+    const extension = output.slice(output.lastIndexOf(".")).toLowerCase();
+    const matched = Object.values(FORMATS).find((format) => format.extension === extension);
+    if (matched) return matched;
+  }
+  return FORMATS.mp4;
+};
+
+/**
+ * Whether a composition's transparency can survive into the file.
+ *
+ * A video with a transparent background exported to MP4 is not an error, it is
+ * a black rectangle — the alpha is composited away by the pixel format. Worth
+ * saying out loud at the point the choice is made.
+ */
+export const alphaWarning = (format: VideoFormat, transparent: boolean): string | null =>
+  transparent && !format.alpha
+    ? `${format.name} has no alpha channel, so the transparent background will render black. Use webm, prores, or png.`
+    : null;

package/src/index.ts

@@ -0,0 +1,58 @@
+export {defineConfig, loadConfig, resolveChromePath, type ResolvedConfig, type OdoriConfig} from "./config";
+export {discoverProject, generateImports, writeGenerated, type ProjectGraph} from "./discovery";
+export {startStudioServer, type StudioServer} from "./server";
+export {loadVideos, findVideo, freezeManifest, runPrepare, type LoadedVideo} from "./project";
+export {fileKey, outputName} from "./paths";
+export {
+  defaultConcurrency,
+  ensureFfmpeg,
+  openRenderPage,
+  readAudio,
+  readTimeline,
+  renderMovie,
+  renderStill,
+  seekTo,
+  probeSignatures,
+  type RenderOptions,
+  type RenderTarget,
+  type RenderTimings,
+} from "./render";
+export {compileInBrowser, createContext, targetFor, withServer, type CompileResult, type Context} from "./commands/shared";
+export {
+  JobQueue,
+  appendJobLog,
+  createJob,
+  listJobs,
+  readJob,
+  reconcileJobs,
+  updateJob,
+  type JobRecord,
+} from "./jobs";
+export {buildAudioFilter, resolveCueFile, type MixInput} from "./audio-mix";
+export {checkDeterminism, type DeterminismFinding} from "./determinism";
+export {FORMATS, alphaWarning, formatNames, resolveFormat, type VideoFormat} from "./formats";
+export {
+  CHROME_BUILD,
+  cacheRoot,
+  installBrowser,
+  installFfmpeg,
+  renderToolchain,
+  resolveBrowser,
+  resolveFfmpeg,
+  type ResolvedBinary,
+} from "./binaries";
+export {createIntegrityResolver, localCandidates} from "./integrity";
+export {clearPrepareCache, prepareCacheKey, readPrepareCache, writePrepareCache} from "./prepare-cache";
+export {devCommand} from "./commands/dev";
+export {cancelJob, exportCommand, jobsCommand, runJob, exportQueue} from "./commands/exportVideo";
+export {chunkFrames, planChunks, type ChunkPlan, type FrameChunk} from "./chunks";
+export {stillCommand} from "./commands/still";
+export {testCommand} from "./commands/test";
+export {listCommand} from "./commands/list";
+export {inspectCommand} from "./commands/inspect";
+export {addCommand} from "./commands/add";
+export {componentStatus, diffCommand, updateCommand, type ComponentStatus} from "./commands/update";
+export {countChanges, diffLines, formatDiff, type DiffLine} from "./diff";
+export {newCommand} from "./commands/new";
+export {initCommand} from "./commands/init";
+export {parseArgs, run} from "./cli";

package/src/integrity.ts

@@ -0,0 +1,101 @@
+import {createHash} from "node:crypto";
+import {existsSync} from "node:fs";
+import {mkdir, readFile, writeFile} from "node:fs/promises";
+import {dirname, resolve} from "node:path";
+import type {ResolvedConfig} from "./config";
+import {log} from "./log";
+
+type IntegrityCache = Record<string, {integrity: string; size: number; mtimeMs?: number}>;
+
+const cacheFile = (config: ResolvedConfig) => resolve(config.root, config.outDir, "cache", "integrity.json");
+
+const readCache = async (config: ResolvedConfig): Promise<IntegrityCache> => {
+  const file = cacheFile(config);
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(await readFile(file, "utf8")) as IntegrityCache;
+  } catch {
+    return {};
+  }
+};
+
+const writeCache = async (config: ResolvedConfig, cache: IntegrityCache) => {
+  const file = cacheFile(config);
+  await mkdir(dirname(file), {recursive: true});
+  await writeFile(file, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+};
+
+const sha256 = (bytes: Uint8Array) => `sha256-${createHash("sha256").update(bytes).digest("base64")}`;
+
+/** Local candidates for a project-relative or public-relative URL. */
+export const localCandidates = (config: ResolvedConfig, url: string): string[] => [
+  resolve(config.root, "public", url.replace(/^\//, "")),
+  resolve(config.root, url.replace(/^\//, "")),
+];
+
+/**
+ * Only `public/` is served, by the dev server and by the render worker alike.
+ * A file found anywhere else still hashes, which would otherwise produce a
+ * manifest that looks verified for a URL the browser answers with a 404.
+ */
+export const isServed = (config: ResolvedConfig, file: string): boolean =>
+  file.startsWith(resolve(config.root, "public") + "/");
+
+/**
+ * Content addressing for everything a render depends on.
+ *
+ * Local files hash their bytes. Remote files are fetched once and cached by
+ * URL, so a manifest stays comparable across runs without refetching on every
+ * export. A source that cannot be read is recorded as unresolved rather than
+ * silently pretending to be verified.
+ */
+export const createIntegrityResolver = async (config: ResolvedConfig) => {
+  const cache = await readCache(config);
+  const warned = new Set<string>();
+  let dirty = false;
+
+  const resolveIntegrity = async (url: string): Promise<string> => {
+    // A generated cue names itself by the hash of the score that produces it,
+    // so the URL is already its integrity. There is no file to read until the
+    // render materializes one, and reading it would only restate the name.
+    if (url.startsWith("/__odori/cue/")) return `cue-${url.slice(url.lastIndexOf("-") + 1).replace(/\.wav$/, "")}`;
+
+    const local = localCandidates(config, url).find((candidate) => existsSync(candidate));
+    if (local) {
+      if (!isServed(config, local) && !warned.has(url)) {
+        warned.add(url);
+        log.warn(`${url} resolves to ${local}, which is outside public/ and will not be served. Move it into public/.`);
+      }
+      const bytes = await readFile(local);
+      const {mtimeMs} = await import("node:fs/promises").then((fs) => fs.stat(local));
+      const hit = cache[url];
+      if (hit && hit.mtimeMs === mtimeMs && hit.size === bytes.byteLength) return hit.integrity;
+      const integrity = sha256(bytes);
+      cache[url] = {integrity, size: bytes.byteLength, mtimeMs};
+      dirty = true;
+      return integrity;
+    }
+
+    if (!/^https?:\/\//.test(url)) return "unresolved";
+    if (cache[url]) return cache[url].integrity;
+
+    try {
+      const response = await fetch(url, {signal: AbortSignal.timeout(10_000)});
+      if (!response.ok) return "unresolved";
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      const integrity = sha256(bytes);
+      cache[url] = {integrity, size: bytes.byteLength};
+      dirty = true;
+      return integrity;
+    } catch {
+      return "unresolved";
+    }
+  };
+
+  return {
+    resolve: resolveIntegrity,
+    flush: async () => {
+      if (dirty) await writeCache(config, cache);
+    },
+  };
+};

package/src/jobs.ts

@@ -0,0 +1,151 @@
+import {mkdir, readFile, readdir, rename, writeFile} from "node:fs/promises";
+import {existsSync} from "node:fs";
+import {join, resolve} from "node:path";
+import type {ExportJob, RenderManifest} from "odori";
+import type {ResolvedConfig} from "./config";
+
+export type JobRecord = {job: ExportJob; manifest: RenderManifest; output: string};
+
+const buildsDir = (config: ResolvedConfig) => resolve(config.root, config.outDir, "builds");
+const jobFile = (config: ResolvedConfig, id: string) => join(buildsDir(config), `${id}.json`);
+
+/**
+ * An export job records the frozen manifest, progress, attempts, and result,
+ * so a retry reuses the approved inputs instead of resolving them again.
+ */
+export const createJob = async (
+  config: ResolvedConfig,
+  manifest: RenderManifest,
+  output: string,
+): Promise<JobRecord> => {
+  await mkdir(buildsDir(config), {recursive: true});
+  const now = new Date().toISOString();
+  const job: ExportJob = {
+    id: `job-${manifest.manifestHash.slice(0, 10)}-${Date.now().toString(36)}`,
+    videoId: manifest.videoId,
+    manifestHash: manifest.manifestHash,
+    status: "queued",
+    progress: 0,
+    attempts: 0,
+    logs: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+  const record: JobRecord = {job, manifest, output};
+  await writeFile(jobFile(config, job.id), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  return record;
+};
+
+export const readJob = async (config: ResolvedConfig, id: string): Promise<JobRecord> => {
+  const file = jobFile(config, id);
+  if (!existsSync(file)) throw new Error(`Unknown job "${id}". Run odori jobs to list them.`);
+  return JSON.parse(await readFile(file, "utf8")) as JobRecord;
+};
+
+/**
+ * Job records are updated from the render loop, the log writer, and the HTTP
+ * handler at once, so every write is serialized per job and lands atomically
+ * through a rename. Otherwise progress updates interleave and corrupt the file.
+ */
+const writeLocks = new Map<string, Promise<unknown>>();
+
+const withJobLock = <Value>(id: string, task: () => Promise<Value>): Promise<Value> => {
+  const previous = writeLocks.get(id) ?? Promise.resolve();
+  const next = previous.then(task, task);
+  writeLocks.set(
+    id,
+    next.catch(() => undefined),
+  );
+  return next;
+};
+
+const writeRecord = async (config: ResolvedConfig, record: JobRecord) => {
+  const file = jobFile(config, record.job.id);
+  const temporary = `${file}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  await rename(temporary, file);
+};
+
+export const updateJob = async (config: ResolvedConfig, job: ExportJob): Promise<ExportJob> =>
+  withJobLock(job.id, async () => {
+    const record = await readJob(config, job.id);
+    const next = {...job, logs: record.job.logs, updatedAt: new Date().toISOString()};
+    await writeRecord(config, {...record, job: next});
+    return next;
+  });
+
+export const appendJobLog = async (config: ResolvedConfig, id: string, message: string): Promise<ExportJob> =>
+  withJobLock(id, async () => {
+    const record = await readJob(config, id);
+    const next = {
+      ...record.job,
+      logs: [...record.job.logs.slice(-49), `${new Date().toISOString()} ${message}`],
+      updatedAt: new Date().toISOString(),
+    };
+    await writeRecord(config, {...record, job: next});
+    return next;
+  });
+
+const alive = (pid?: number): boolean => {
+  if (!pid) return false;
+  try {
+    // Signal 0 tests for existence without touching the process.
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * A killed process leaves its job claiming to be rendering forever. Anything
+ * that reads job state reconciles first, so `odori jobs` never reports a lie.
+ */
+export const reconcileJobs = async (config: ResolvedConfig): Promise<number> => {
+  const stale = (await listJobs(config, {reconcile: false})).filter(
+    (job) => (job.status === "rendering" || job.status === "encoding") && !alive(job.pid),
+  );
+  for (const job of stale) {
+    await updateJob(config, {
+      ...job,
+      status: "failed",
+      error: "The render process exited before the job finished.",
+    });
+  }
+  return stale.length;
+};
+
+export const listJobs = async (config: ResolvedConfig, options: {reconcile?: boolean} = {}): Promise<ExportJob[]> => {
+  if (!existsSync(buildsDir(config))) return [];
+  if (options.reconcile !== false) await reconcileJobs(config);
+  const files = (await readdir(buildsDir(config))).filter((file) => file.endsWith(".json"));
+  const jobs: ExportJob[] = [];
+
+  // One unreadable record must not hide every other job.
+  for (const file of files) {
+    try {
+      const raw = await readFile(join(buildsDir(config), file), "utf8");
+      jobs.push((JSON.parse(raw) as JobRecord).job);
+    } catch {
+      continue;
+    }
+  }
+  return jobs.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+};
+
+/**
+ * A single-lane queue.
+ *
+ * Rendering saturates the machine's cores already, so jobs run one at a time
+ * in submission order. The queue is a promise chain rather than a daemon, which
+ * keeps `odori export` and the Studio export button on exactly the same path.
+ */
+export class JobQueue {
+  private chain: Promise<unknown> = Promise.resolve();
+
+  enqueue<Value>(task: () => Promise<Value>): Promise<Value> {
+    const result = this.chain.then(task, task);
+    this.chain = result.catch(() => undefined);
+    return result;
+  }
+}

package/src/log.ts

@@ -0,0 +1,17 @@
+const ESC = String.fromCharCode(27);
+const wrap = (code: string, value: string) => `${ESC}[${code}m${value}${ESC}[0m`;
+
+export const log = {
+  info: (message: string) => console.log(message),
+  detail: (message: string) => console.log(wrap("2", message)),
+  title: (message: string) => console.log(wrap("1", message)),
+  success: (message: string) => console.log(`${wrap("32", "ok")} ${message}`),
+  warn: (message: string) => console.warn(`${wrap("33", "!")} ${message}`),
+  error: (message: string) => console.error(`${wrap("31", "x")} ${message}`),
+  progress: (message: string) => {
+    if (process.stdout.isTTY) process.stdout.write(`\r${wrap("2", message)}${ESC}[K`);
+  },
+  progressDone: () => {
+    if (process.stdout.isTTY) process.stdout.write(`\r${ESC}[K`);
+  },
+};

package/src/open.ts

@@ -0,0 +1,32 @@
+import {spawn} from "node:child_process";
+
+const command = (): {bin: string; args: string[]} | undefined => {
+  if (process.platform === "darwin") return {bin: "open", args: []};
+  if (process.platform === "win32") return {bin: "cmd", args: ["/c", "start", ""]};
+  if (process.platform === "linux") return {bin: "xdg-open", args: []};
+  return undefined;
+};
+
+/**
+ * Studio is a browser workspace, so `odori dev` opens it. Automation should
+ * not steal focus: CI and non-interactive shells are left alone, and the URL
+ * is always printed so the browser is a convenience rather than the interface.
+ */
+export const shouldOpenBrowser = (flag?: boolean): boolean => {
+  if (flag !== undefined) return flag;
+  if (process.env.ODORI_OPEN === "0" || process.env.ODORI_OPEN === "false") return false;
+  if (process.env.CI) return false;
+  return process.stdout.isTTY === true;
+};
+
+export const openInBrowser = (url: string): void => {
+  const resolved = command();
+  if (!resolved) return;
+  try {
+    const child = spawn(resolved.bin, [...resolved.args, url], {stdio: "ignore", detached: true});
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // A missing browser opener is never worth failing the dev server over.
+  }
+};

package/src/paths.ts

@@ -0,0 +1,12 @@
+/**
+ * Video ids are paths under `videos/`; files on disk are flat.
+ *
+ * Two encodings, deliberately different. An output file is something a person
+ * hands to someone else, so `social/announcement` becomes the readable
+ * `social-announcement`. A cache file is addressed, not read, so it encodes
+ * the separator instead of replacing it: `social+announcement` cannot collide
+ * with a video genuinely named `social-announcement`.
+ */
+export const outputName = (id: string): string => id.split("/").join("-");
+
+export const fileKey = (id: string): string => id.split("/").join("+");

package/src/prepare-cache.ts

@@ -0,0 +1,58 @@
+import {existsSync} from "node:fs";
+import {mkdir, readFile, readdir, rm, writeFile} from "node:fs/promises";
+import {join, resolve} from "node:path";
+import {hashValue} from "odori";
+import type {ResolvedConfig} from "./config";
+import {fileKey} from "./paths";
+
+export type PrepareCacheKey = {
+  videoId: string;
+  sourceHash: string;
+  input: unknown;
+  version: string;
+  dependencies?: unknown;
+};
+
+export type PrepareCacheEntry = {key: PrepareCacheKey; value: unknown; createdAt: string};
+
+const directory = (config: ResolvedConfig) => resolve(config.root, config.outDir, "cache", "prepare");
+
+/**
+ * Prepared data is cached by video source hash, validated input, prepare
+ * version, and declared dependencies. Changing scene styling does not refetch
+ * source data, and changing a data dependency invalidates deterministically.
+ */
+export const prepareCacheKey = (key: PrepareCacheKey): string => `${fileKey(key.videoId)}__${hashValue(key)}`;
+
+export const readPrepareCache = async (
+  config: ResolvedConfig,
+  key: PrepareCacheKey,
+): Promise<{hit: boolean; value: unknown}> => {
+  const file = join(directory(config), `${prepareCacheKey(key)}.json`);
+  if (!existsSync(file)) return {hit: false, value: undefined};
+  try {
+    const entry = JSON.parse(await readFile(file, "utf8")) as PrepareCacheEntry;
+    return {hit: true, value: entry.value};
+  } catch {
+    return {hit: false, value: undefined};
+  }
+};
+
+export const writePrepareCache = async (config: ResolvedConfig, key: PrepareCacheKey, value: unknown) => {
+  if (value === undefined) return;
+  const target = directory(config);
+  await mkdir(target, {recursive: true});
+  const entry: PrepareCacheEntry = {key, value, createdAt: new Date().toISOString()};
+  await writeFile(join(target, `${prepareCacheKey(key)}.json`), `${JSON.stringify(entry, null, 2)}\n`, "utf8");
+};
+
+/** Remove cached preparations for a video, or for the whole project. */
+export const clearPrepareCache = async (config: ResolvedConfig, videoId?: string): Promise<number> => {
+  const target = directory(config);
+  if (!existsSync(target)) return 0;
+  const files = await readdir(target);
+  // The separator cannot appear in an id, so "launch" never clears "launch-extra".
+  const matches = files.filter((file) => (videoId ? file.startsWith(`${fileKey(videoId)}__`) : file.endsWith(".json")));
+  await Promise.all(matches.map((file) => rm(join(target, file), {force: true})));
+  return matches.length;
+};