From 0e0a0e40d0e640e06f6bc0141a33105d9f112e9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 7 May 2026 01:17:39 +0200
Subject: [PATCH] feat(cli): add --composition flag to render specific
 compositions (#631)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(cli): add --composition flag to render specific compositions

Expose the existing entryFile config in the producer through
a new --composition / -c CLI flag. This lets users render
individual composition files without restructuring their project:

  hyperframes render -c compositions/intro.html -o intro.mp4

The flag validates the file exists before starting the render,
threads through both local and Docker render paths, and is
documented in the CLI help, examples, and docs.

* fix(cli): address PR review — path traversal guard, forward tests, tripwire

- Add path-containment check mirroring hyperframeLint.ts: reject
  --composition paths that escape the project directory
- Normalize leading ./ from composition paths for clean render plan output
- Improve error message: suggest .html file path instead of compositions command
- Add description note about <template> sub-composition constraint
- Add render.test.ts: entryFile forwarded to createRenderJob (forward + omit)
- Update dockerRunArgs tripwire test with entryFile coverage
---
 docs/packages/cli.mdx                        |  4 ++
 packages/cli/src/commands/render.test.ts     | 31 ++++++++++++++
 packages/cli/src/commands/render.ts          | 43 ++++++++++++++++++--
 packages/cli/src/utils/dockerRunArgs.test.ts | 18 ++++++++
 packages/cli/src/utils/dockerRunArgs.ts      |  2 +
 5 files changed, 94 insertions(+), 4 deletions(-)

diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index f9ae12f72..0e24c119b 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -129,6 +129,10 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     ```bash
     npx hyperframes render --output output.mp4
     ```
+    Render a specific composition instead of `index.html`:
+    ```bash
+    npx hyperframes render -c compositions/intro.html -o intro.mp4
+    ```
     For deterministic output, add `--docker`:
     ```bash
     npx hyperframes render --docker --output output.mp4
diff --git a/packages/cli/src/commands/render.test.ts b/packages/cli/src/commands/render.test.ts
index b3ff435d6..b74860fb3 100644
--- a/packages/cli/src/commands/render.test.ts
+++ b/packages/cli/src/commands/render.test.ts
@@ -158,6 +158,37 @@ describe("renderLocal browser GPU config", () => {
     expect(producerState.createdJobs[0]?.variables).toBeUndefined();
   });
 
+  it("forwards entryFile to createRenderJob when --composition is set", async () => {
+    const { renderLocal } = await import("./render.js");
+    await renderLocal("/tmp/project", "/tmp/out.mp4", {
+      fps: 30,
+      quality: "standard",
+      format: "mp4",
+      gpu: false,
+      browserGpu: false,
+      hdrMode: "auto",
+      quiet: true,
+      entryFile: "compositions/intro.html",
+    });
+
+    expect(producerState.createdJobs[0]?.entryFile).toBe("compositions/intro.html");
+  });
+
+  it("omits entryFile from createRenderJob when --composition is not set", async () => {
+    const { renderLocal } = await import("./render.js");
+    await renderLocal("/tmp/project", "/tmp/out.mp4", {
+      fps: 30,
+      quality: "standard",
+      format: "mp4",
+      gpu: false,
+      browserGpu: false,
+      hdrMode: "auto",
+      quiet: true,
+    });
+
+    expect(producerState.createdJobs[0]?.entryFile).toBeUndefined();
+  });
+
   it("can force the CLI process to exit after a successful local render", async () => {
     vi.useFakeTimers();
     const exit = vi
diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts
index ae2c8df8f..02b495ba3 100644
--- a/packages/cli/src/commands/render.ts
+++ b/packages/cli/src/commands/render.ts
@@ -4,6 +4,7 @@ import { mkdirSync, readFileSync, statSync, writeFileSync, rmSync } from "node:f
 
 export const examples: Example[] = [
   ["Render to MP4", "hyperframes render --output output.mp4"],
+  ["Render a specific composition", "hyperframes render -c compositions/intro.html -o intro.mp4"],
   ["Render transparent overlay (ProRes)", "hyperframes render --format mov --output overlay.mov"],
   ["Render transparent WebM overlay", "hyperframes render --format webm --output overlay.webm"],
   ["High quality at 60fps", "hyperframes render --fps 60 --quality high --output hd.mp4"],
@@ -62,6 +63,13 @@ export default defineCommand({
       description: "Project directory",
       required: false,
     },
+    composition: {
+      type: "string",
+      alias: "c",
+      description:
+        "Render a specific composition file instead of index.html (e.g. compositions/intro.html). " +
+        "Sub-compositions using <template> wrappers must be referenced from index.html via data-composition-src.",
+    },
     output: {
       type: "string",
       alias: "o",
@@ -263,16 +271,38 @@ export default defineCommand({
       process.exit(1);
     }
 
+    // ── Validate composition entry file ──────────────────────────────────
+    const entryFile = args.composition?.trim().replace(/^\.\//, "") || undefined;
+    if (entryFile) {
+      const absProjectDir = resolve(project.dir);
+      const entryPath = resolve(absProjectDir, entryFile);
+      if (!entryPath.startsWith(absProjectDir)) {
+        errorBox(
+          "Invalid composition path",
+          `Entry file must stay inside the project directory: ${entryFile}`,
+        );
+        process.exit(1);
+      }
+      try {
+        statSync(entryPath);
+      } catch {
+        errorBox(
+          "Composition not found",
+          `"${entryFile}" does not exist in the project directory.`,
+          "Pass a path to a .html file relative to the project root (e.g. compositions/intro.html).",
+        );
+        process.exit(1);
+      }
+    }
+
     // ── Print render plan ─────────────────────────────────────────────────
     if (!quiet) {
       const workerLabel =
         workers != null ? `${workers} workers` : `auto workers (${CPU_CORE_COUNT} cores detected)`;
       console.log("");
+      const nameLabel = entryFile ? project.name + "/" + entryFile : project.name;
       console.log(
-        c.accent("\u25C6") +
-          "  Rendering " +
-          c.accent(project.name) +
-          c.dim(" \u2192 " + outputPath),
+        c.accent("\u25C6") + "  Rendering " + c.accent(nameLabel) + c.dim(" \u2192 " + outputPath),
       );
       console.log(c.dim("   " + fps + "fps \u00B7 " + quality + " \u00B7 " + workerLabel));
       if (useGpu || browserGpuMode !== "software") {
@@ -407,6 +437,7 @@ export default defineCommand({
         videoBitrate,
         quiet,
         variables,
+        entryFile,
         exitAfterComplete: true,
       });
     } else {
@@ -423,6 +454,7 @@ export default defineCommand({
         quiet,
         browserPath,
         variables,
+        entryFile,
         exitAfterComplete: true,
       });
     }
@@ -447,6 +479,7 @@ interface RenderOptions {
   quiet: boolean;
   browserPath?: string;
   variables?: Record<string, unknown>;
+  entryFile?: string;
   exitAfterComplete?: boolean;
 }
 
@@ -740,6 +773,7 @@ async function renderDocker(
       videoBitrate: options.videoBitrate,
       quiet: options.quiet,
       variables: options.variables,
+      entryFile: options.entryFile,
     },
   });
 
@@ -810,6 +844,7 @@ export async function renderLocal(
     crf: options.crf,
     videoBitrate: options.videoBitrate,
     variables: options.variables,
+    entryFile: options.entryFile,
   });
 
   const onProgress = options.quiet
diff --git a/packages/cli/src/utils/dockerRunArgs.test.ts b/packages/cli/src/utils/dockerRunArgs.test.ts
index 5877985f1..ac3029d3e 100644
--- a/packages/cli/src/utils/dockerRunArgs.test.ts
+++ b/packages/cli/src/utils/dockerRunArgs.test.ts
@@ -161,6 +161,7 @@ describe("buildDockerRunArgs", () => {
         crf: 16,
         videoBitrate: undefined,
         quiet: true,
+        entryFile: "compositions/intro.html",
       },
     });
     // Each value must reach the container exactly once. If a future option
@@ -176,6 +177,8 @@ describe("buildDockerRunArgs", () => {
     expect(args).toContain("--gpu");
     expect(args).toContain("--no-browser-gpu");
     expect(args).toContain("--hdr");
+    expect(args).toContain("--composition");
+    expect(args).toContain("compositions/intro.html");
   });
 
   it("forwards --video-bitrate to the container when set", () => {
@@ -210,4 +213,19 @@ describe("buildDockerRunArgs", () => {
     });
     expect(args).not.toContain("--variables");
   });
+
+  it("forwards --composition to the container when entryFile is set", () => {
+    const args = buildDockerRunArgs({
+      ...FIXED_INPUT,
+      options: { ...BASE, entryFile: "compositions/intro.html" },
+    });
+    const idx = args.indexOf("--composition");
+    expect(idx).toBeGreaterThan(-1);
+    expect(args[idx + 1]).toBe("compositions/intro.html");
+  });
+
+  it("omits --composition when entryFile is not set", () => {
+    const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
+    expect(args).not.toContain("--composition");
+  });
 });
diff --git a/packages/cli/src/utils/dockerRunArgs.ts b/packages/cli/src/utils/dockerRunArgs.ts
index 5e6303b52..dd913d17f 100644
--- a/packages/cli/src/utils/dockerRunArgs.ts
+++ b/packages/cli/src/utils/dockerRunArgs.ts
@@ -30,6 +30,7 @@ export interface DockerRenderOptions {
   videoBitrate?: string;
   quiet: boolean;
   variables?: Record<string, unknown>;
+  entryFile?: string;
 }
 
 export function buildDockerRunArgs(input: DockerRunArgsInput): string[] {
@@ -67,5 +68,6 @@ export function buildDockerRunArgs(input: DockerRunArgsInput): string[] {
     ...(options.variables && Object.keys(options.variables).length > 0
       ? ["--variables", JSON.stringify(options.variables)]
       : []),
+    ...(options.entryFile ? ["--composition", options.entryFile] : []),
   ];
 }