Function run

packages/cli/src/commands/render.ts:368–950

({ args })

  // Full decomposition is tracked separately and out of scope for #1199.
  // fallow-ignore-next-line complexity
  async run({ args }) {
    // ── Resolve project ────────────────────────────────────────────────────
    const project = resolveProject(args.dir);

    // ── Validate fps ───────────────────────────────────────────────────────
    // Accept either integer (`30`) or ffmpeg-style rational (`30000/1001`).
    // The whitelist-based validator was replaced with a sane numeric range so
    // legitimate framerates (NTSC trio, PAL, 120/240 slow-mo) work without
    // CLI gymnastics. The exact rational survives end-to-end into FFmpeg's
    // `-r` / `-framerate` flags via `fpsToFfmpegArg`.
    const fpsParse = parseFps(args.fps ?? "30");
    if (!fpsParse.ok) {
      errorBox("Invalid fps", formatFpsParseError(args.fps ?? "30", fpsParse.reason));
      process.exit(1);
    }
    let fps: Fps = fpsParse.value;

    // ── Validate quality ───────────────────────────────────────────────────
    const qualityRaw = args.quality ?? "standard";
    if (!VALID_QUALITY.has(qualityRaw)) {
      errorBox("Invalid quality", `Got "${qualityRaw}". Must be draft, standard, or high.`);
      process.exit(1);
    }
    const quality = qualityRaw as "draft" | "standard" | "high";

    // ── Authoring skill (telemetry attribution) ────────────────────────────
    // Optional slug naming the workflow skill that drove this render (e.g.
    // "product-launch-video"), tagged onto render telemetry for per-skill usage
    // breakdowns. Slug-gated (shared with the `events` command) so a caller
    // can't push high-cardinality or PII strings into the anonymous event
    // stream; a missing/invalid value is omitted.
    const authoringSkill = normalizeSkillSlug(args.skill);
    if (typeof args.skill === "string" && args.skill.trim() !== "" && !authoringSkill) {
      // Surface a typo (e.g. camelCase) instead of silently losing attribution.
      // Warning only — never fails the render.
      process.stderr.write(
        `hyperframes: ignoring --skill="${args.skill}" — not a valid slug ` +
          "(lowercase letters/digits/hyphens, max 64); this render will be unattributed.\n",
      );
    }

    // ── Validate format ─────────────────────────────────────────────────
    const formatRaw = args.format ?? "mp4";
    const format = parseRenderFormat(formatRaw);
    if (!format) {
      errorBox("Invalid format", `Got "${formatRaw}". Must be ${RENDER_FORMAT_LABEL}.`);
      process.exit(1);
    }

    let gifFpsCapped = false;
    if (format === "gif" && fpsToNumber(fps) > 30) {
      fps = { num: 30, den: 1 };
      gifFpsCapped = true;
    }

    const gifLoopParse = parseGifLoopArg(args["gif-loop"]);
    if (!gifLoopParse.ok) {
      errorBox("Invalid gif-loop", gifLoopParse.message);