Files
hyperframes/packages/cli/src/commands/lambda.ts
T
James RussoandClaude Opus 5.5 2d3033c719 fix(cli): exit 2 for remaining flag validation errors (#6639)
* fix(cli): exit 2 for remaining flag validation errors

Flag and argument checks that commands make themselves still exited 1 and
reported runtime_error under --json. They now take the existing usage-error
path (failUsage / CliUsageError): exit 2 and a usage_error envelope. This
covers lambda and cloudrun render/render-batch (--width/--height, --fps,
positive-number, enum and --output-resolution flags, unknown subcommands),
capture, feedback, benchmark --runs, tts, init, snapshot, compare,
grade-compare, check, normalize-audio, media-treatment, play/present --port,
models, docs, browser and telemetry unknown subcommands, cloud render
conflicting inputs, cloud delete without --no-confirm, and inline --variables.
A few checks now run before project or stack lookup so a bad flag is reported
first. Runtime failures (missing files, network, render errors) still exit 1.

An unattended spinner now writes its start and progress text as plain stderr
lines, not only the outcome, so tools watching init can see "Transcoding".

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): reject a bad snapshot --frames, quiet spinner progress, drop added comments

- `snapshot --frames abc` (or 0, -3, 2.5) is now a usage error: exit 2, and a
  usage_error envelope under --json. It used to fall back to 5 frames silently.
- An unattended spinner prints its start line once and its outcome, but no
  longer one line per progress update, which flooded stderr during
  remove-background and the Chrome download.
- Removes the comment lines this branch added, so the comment ratchet passes.
- The render --json test now expects exit 2 and usage_error for bad inline
  --variables.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-28 11:27:49 +00:00

534 lines
22 KiB
TypeScript

import { CliUsageError, failCommand, failUsage } from "../utils/commandResult.js";
/**
* `hyperframes lambda` — top-level dispatcher for AWS Lambda subcommands.
*
* Each subverb lives in `./lambda/<name>.ts` and exports a single
* `runXxx(args)` async function. The subcommand surface is intentionally
* thin glue: argument parsing + help text here; the actual work
* (`renderToLambda` / `getRenderProgress` / `deploySite` / SAM driver)
* lives in `@hyperframes/aws-lambda/sdk`.
*/
import { defineCommand } from "../utils/defineCommand.js";
import type { DistributedFormat } from "@hyperframes/aws-lambda/sdk";
import { type CanvasResolution, DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";
import { parseOutputResolutionFlag } from "../utils/parseOutputResolution.js";
import type { Example } from "./_examples.js";
import type { VideoArch } from "./lambda/videoImage.js";
import { c } from "../ui/colors.js";
import { deliveryFlagArgs, parseDeliveryFlags } from "../utils/deliveryFlags.js";
import { defaultCloudFps } from "../utils/compositionFps.js";
import { isMissingPackageError, missingPackageMessage } from "../utils/missingPackage.js";
export const examples: Example[] = [
["Deploy the Lambda render stack to AWS", "hyperframes lambda deploy"],
[
"Render a composition on the deployed stack",
"hyperframes lambda render ./my-project --width 1920 --height 1080",
],
[
"Render and stream progress until done",
"hyperframes lambda render ./my-project --width 1920 --height 1080 --wait",
],
[
"Supersample a 1080p composition to 4K via Chrome deviceScaleFactor",
"hyperframes lambda render ./my-project --width 1920 --height 1080 --output-resolution 4k --wait",
],
[
"Render with composition variables (personalised template)",
'hyperframes lambda render ./my-template --site-id abc1234deadbeef0 --width 1920 --height 1080 --variables \'{"title":"Hello Alice","accent":"#ff0000"}\'',
],
[
"Render with variables from a JSON file",
"hyperframes lambda render ./my-template --site-id abc1234deadbeef0 --width 1920 --height 1080 --variables-file ./alice.json",
],
[
"Batch-render N personalised videos from a JSONL file (deploys the site once)",
"hyperframes lambda render-batch ./my-template --batch ./users.jsonl --width 1920 --height 1080 --max-concurrent 10",
],
["Check progress for a started render", "hyperframes lambda progress hf-render-abcd1234"],
[
"Pre-upload a project so multiple renders share the upload",
"hyperframes lambda sites create ./my-project",
],
["Tear the stack down", "hyperframes lambda destroy"],
["Print the IAM policy the CLI needs", "hyperframes lambda policies user"],
[
"Validate a checked-in IAM policy still covers the CLI",
"hyperframes lambda policies validate ./infra/iam/hyperframes.json",
],
];
const HELP = `
${c.bold("hyperframes lambda")} ${c.dim("<subcommand> [args]")}
Deploy + drive distributed video renders on AWS Lambda.
${c.bold("SUBCOMMANDS:")}
${c.accent("deploy")} ${c.dim("Provision the Lambda + Step Functions + S3 stack via SAM")}
${c.accent("sites create")} ${c.dim("Tar + upload a project to S3 (reusable across renders)")}
${c.accent("render")} ${c.dim("Start a distributed render (returns a renderId)")}
${c.accent("render-batch")} ${c.dim("Fan out N personalised renders from a JSONL batch file")}
${c.accent("progress")} ${c.dim("Print progress + cost for an in-flight or finished render")}
${c.accent("destroy")} ${c.dim("Tear the stack down (S3 bucket is retained)")}
${c.accent("policies")} ${c.dim("Print or validate the IAM permissions the CLI needs")}
${c.bold("FIRST RUN:")}
${c.accent("hyperframes lambda deploy")}
${c.accent("hyperframes lambda render ./my-project --width 1920 --height 1080 --wait")}
${c.bold("REQUIREMENTS:")}
• AWS CLI configured (env vars, ~/.aws/credentials, or SSO)
• AWS SAM CLI installed (https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)
• bun on PATH (used to build the handler ZIP)
`;
export default defineCommand({
meta: { name: "lambda", description: "Deploy and drive renders on AWS Lambda" },
args: {
subcommand: {
type: "positional",
required: false,
description: "deploy | sites | render | progress | destroy | policies",
},
target: {
type: "positional",
required: false,
description: "Subcommand-specific positional (project dir, render id, policies verb, etc.)",
},
extra: {
type: "positional",
required: false,
description:
"Extra positional (e.g. `sites create <projectDir>` or `policies validate <policy.json>`)",
},
// Stack identity
"stack-name": {
type: "string",
description: "CloudFormation stack name (default: hyperframes-default)",
},
region: { type: "string", description: "AWS region (default: AWS_REGION env or us-east-1)" },
profile: { type: "string", description: "AWS profile name (default: AWS_PROFILE env)" },
// deploy
concurrency: {
type: "string",
description:
"Lambda reserved concurrency, or none to remove it (default: keep the stack's; a new stack reserves none and each render runs up to 90% of the account's unreserved concurrency)",
},
"chrome-source": {
type: "string",
description: "sparticuz | chrome-headless-shell (default: sparticuz)",
},
memory: { type: "string", description: "Lambda memory MB (default: 10240)" },
"video-arch": {
type: "string",
description:
"arm64 | x86_64: where the plan and chunks run; arm64 adds a container-image function (default: arm64)",
},
"skip-build": { type: "boolean", description: "Reuse existing handler.zip (deploy)" },
warm: {
type: "boolean",
default: true,
description: "Warm the video function once after deploy (--no-warm skips it)",
},
// sites / render
"site-id": { type: "string", description: "Explicit site id (overrides content hash)" },
width: {
type: "string",
description:
"Output width in pixels: the composition's width, or a whole-number multiple of it (3840 on a 1920x1080 composition renders at scale 2)",
},
height: {
type: "string",
description: "Output height in pixels, at the same multiple as --width",
},
"output-resolution": {
type: "string",
description:
"Output resolution preset that engages Chrome deviceScaleFactor supersampling. Accepts canonical names (landscape, landscape-4k, portrait, portrait-4k, square, square-4k) and aliases (1080p, 4k, uhd, hd). When set, the composition's authored data-width/data-height is supersampled to the target preset without changing the layout.",
},
fps: { type: "string", description: `Render fps (${DISTRIBUTED_FPS.join(" | ")})` },
format: { type: "string", description: "mp4 | mov | png-sequence | webm (default: mp4)" },
codec: { type: "string", description: "h264 | h265 (mp4 only)" },
quality: { type: "string", description: "draft | standard | high" },
...deliveryFlagArgs,
"chunk-size": {
type: "string",
description:
"Frames per chunk (default: sized so each chunk fits the Lambda timeout, one wave across --concurrency)",
},
"max-parallel-chunks": {
type: "string",
description:
"Max chunks per render (default: one wave across the deploy's --concurrency, widened to fit the Lambda timeout)",
},
"target-chunk-frames": {
type: "string",
description:
"Cap per-chunk frames; auto-adds chunks (up to --max-parallel-chunks) to keep each under this. Ignored if --chunk-size is set.",
},
"execution-name": {
type: "string",
description: "Step Functions execution name (default: hf-render-<uuid>)",
},
"output-key": {
type: "string",
description: "Final output S3 key (default: renders/<exec>/output.<ext>)",
},
// Variables — mirrors the local `hyperframes render` UX. Inline JSON or
// file path, plus --strict-variables for type-checked validation against
// the composition's `data-composition-variables` declaration.
variables: {
type: "string",
description:
'JSON object of variable values for the composition. Example: --variables \'{"title":"Hello"}\'. Values flow into window.__hfVariables on the Lambda chunk workers.',
},
"variables-file": {
type: "string",
description:
"Path to a JSON file with variable values (alternative to --variables). The file must contain a single JSON object.",
},
"strict-variables": {
type: "boolean",
description:
"Fail the render command if any --variables key is undeclared or has a wrong type vs the composition's data-composition-variables. Without this flag, mismatches are warnings.",
default: false,
},
// render-batch
batch: {
type: "string",
description:
'Path to a JSONL batch file for `render-batch`. Each line: {"outputKey":"...","variables":{...}}',
},
"max-concurrent": {
type: "string",
description:
"Max in-flight Step Functions executions for `render-batch` (default: 50). Distinct from --max-parallel-chunks (which caps chunks per render).",
},
"dry-run": {
type: "boolean",
description:
"For `render-batch`: parse the batch file and print the manifest without invoking AWS. Every entry's status becomes `would-invoke`.",
default: false,
},
wait: { type: "boolean", description: "Block until the render finishes" },
"wait-interval-ms": {
type: "string",
description: "Poll cadence in ms when --wait is set (default: 5000)",
},
// shared
json: { type: "boolean", description: "Emit machine-readable JSON" },
},
async run({ args }) {
const subcommand = args.subcommand;
if (!subcommand) {
console.log(HELP);
return;
}
const stackName =
(args["stack-name"] as string | undefined) ??
// Lazy-imported so the dispatcher doesn't pull state.ts (and its
// node:fs deps) on every CLI invocation — only on lambda runs.
(await import("./lambda/state.js")).DEFAULT_STACK_NAME;
// Apply --profile globally before any AWS-SDK / `aws` / `sam` call runs.
// The AWS SDK + the SAM CLI both read AWS_PROFILE from the environment,
// so setting it here threads the value through render / progress / sites
// (which don't take an explicit awsProfile arg) without each subverb
// having to know about it. Region gets the same treatment so the SDK
// clients constructed inside the SDK pick it up too.
const profileFlag = args.profile as string | undefined;
if (profileFlag) process.env.AWS_PROFILE = profileFlag;
const regionFlag = args.region as string | undefined;
if (regionFlag) process.env.AWS_REGION = regionFlag;
// The lambda subverbs dynamic-import `@hyperframes/aws-lambda` at call
// time. We keep aws-lambda as a workspace devDependency (not a runtime
// dep) so the published CLI install stays small for users who don't
// deploy to Lambda. These subverbs need it and get a friendly hint when it
// is missing; `deploy` reports that itself and `destroy` needs only SAM.
const verbsNeedingSDK = new Set(["sites", "render", "render-batch", "progress"]);
if (verbsNeedingSDK.has(subcommand)) {
try {
await import("@hyperframes/aws-lambda/sdk");
} catch (err) {
if (isMissingPackageError(err, "@hyperframes/aws-lambda")) {
console.error(
missingPackageMessage("@hyperframes/aws-lambda", `hyperframes lambda ${subcommand}`),
);
failCommand();
}
throw err;
}
}
switch (subcommand) {
case "deploy": {
const { runDeploy } = await import("./lambda/deploy.js");
const { parseReservedConcurrency } = await import("./lambda/sam.js");
await runDeploy({
stackName,
region: args.region as string | undefined,
awsProfile: args.profile as string | undefined,
reservedConcurrency: parseReservedConcurrency(args.concurrency),
chromeSource: parseChromeSource(args["chrome-source"]),
lambdaMemoryMb: parsePositiveInt(args.memory, "--memory"),
videoArch: parseVideoArch(args["video-arch"]),
skipBuild: Boolean(args["skip-build"]),
warm: args.warm !== false,
});
return;
}
case "sites": {
if (args.target !== "create") {
console.error(
`[lambda sites] unknown verb "${String(args.target)}". Only "create" is supported.`,
);
failUsage();
}
const projectDir = args.extra as string | undefined;
if (!projectDir) {
console.error(
"[lambda sites create] usage: hyperframes lambda sites create <projectDir>",
);
failUsage();
}
const { runSitesCreate } = await import("./lambda/sites.js");
await runSitesCreate({
projectDir,
stackName,
siteId: args["site-id"] as string | undefined,
json: Boolean(args.json),
});
return;
}
case "render": {
const projectDir = args.target as string | undefined;
if (!projectDir) {
console.error(
"[lambda render] usage: hyperframes lambda render <projectDir> --width <px> --height <px>",
);
failUsage();
}
const width = parsePositiveInt(args.width, "--width");
const height = parsePositiveInt(args.height, "--height");
if (width === undefined || height === undefined) {
console.error("[lambda render] --width and --height are required.");
failUsage();
}
const fpsRaw = parseIntFlag(args.fps) ?? defaultCloudFps(projectDir);
if (!isDistributedFps(fpsRaw)) {
console.error(
`[lambda render] --fps must be one of ${DISTRIBUTED_FPS.join(", ")}; got ${fpsRaw}.`,
);
failUsage();
}
const { runRender } = await import("./lambda/render.js");
const renderResolution = parseOutputResolution(args["output-resolution"]);
await runRender({
projectDir,
stackName,
siteId: args["site-id"] as string | undefined,
fps: fpsRaw,
width,
height,
outputResolution: renderResolution.outputResolution,
outputResolutionAspectAgnostic: renderResolution.outputResolutionAspectAgnostic,
format: parseFormat(args.format),
codec: parseCodec(args.codec),
quality: parseQuality(args.quality),
...parseDeliveryFlags(args),
chunkSize: parsePositiveInt(args["chunk-size"], "--chunk-size"),
maxParallelChunks: parsePositiveInt(args["max-parallel-chunks"], "--max-parallel-chunks"),
targetChunkFrames: parsePositiveInt(args["target-chunk-frames"], "--target-chunk-frames"),
executionName: args["execution-name"] as string | undefined,
outputKey: args["output-key"] as string | undefined,
variables: args.variables as string | undefined,
variablesFile: args["variables-file"] as string | undefined,
strictVariables: Boolean(args["strict-variables"]),
json: Boolean(args.json),
wait: Boolean(args.wait),
waitIntervalMs: parsePositiveInt(args["wait-interval-ms"], "--wait-interval-ms") ?? 5000,
});
return;
}
case "render-batch": {
const projectDir = args.target as string | undefined;
if (!projectDir) {
console.error(
"[lambda render-batch] usage: hyperframes lambda render-batch <projectDir> --batch <path.jsonl> --width <px> --height <px>",
);
failUsage();
}
const batch = args.batch as string | undefined;
if (!batch) {
console.error(
"[lambda render-batch] --batch <path.jsonl> is required. Each line is a JSON object with at least { outputKey: '...' }.",
);
failUsage();
}
const width = parsePositiveInt(args.width, "--width");
const height = parsePositiveInt(args.height, "--height");
if (width === undefined || height === undefined) {
console.error("[lambda render-batch] --width and --height are required.");
failUsage();
}
const fpsRaw = parseIntFlag(args.fps) ?? defaultCloudFps(projectDir);
if (!isDistributedFps(fpsRaw)) {
console.error(
`[lambda render-batch] --fps must be one of ${DISTRIBUTED_FPS.join(", ")}; got ${fpsRaw}.`,
);
failUsage();
}
const { runRenderBatch } = await import("./lambda/render-batch.js");
const batchResolution = parseOutputResolution(args["output-resolution"]);
await runRenderBatch({
projectDir,
stackName,
batch,
siteId: args["site-id"] as string | undefined,
fps: fpsRaw,
width,
height,
outputResolution: batchResolution.outputResolution,
outputResolutionAspectAgnostic: batchResolution.outputResolutionAspectAgnostic,
format: parseFormat(args.format),
codec: parseCodec(args.codec),
quality: parseQuality(args.quality),
...parseDeliveryFlags(args),
chunkSize: parsePositiveInt(args["chunk-size"], "--chunk-size"),
maxParallelChunks: parsePositiveInt(args["max-parallel-chunks"], "--max-parallel-chunks"),
targetChunkFrames: parsePositiveInt(args["target-chunk-frames"], "--target-chunk-frames"),
maxConcurrent: parsePositiveInt(args["max-concurrent"], "--max-concurrent"),
strictVariables: Boolean(args["strict-variables"]),
dryRun: Boolean(args["dry-run"]),
json: Boolean(args.json),
});
return;
}
case "progress": {
const target = args.target as string | undefined;
if (!target) {
console.error(
"[lambda progress] usage: hyperframes lambda progress <renderId | executionArn>",
);
failUsage();
}
const { runProgress } = await import("./lambda/progress.js");
await runProgress({ target, stackName, json: Boolean(args.json) });
return;
}
case "destroy": {
const { runDestroy } = await import("./lambda/destroy.js");
await runDestroy({ stackName, awsProfile: args.profile as string | undefined });
return;
}
case "policies": {
const verb = args.target as string | undefined;
if (verb !== "role" && verb !== "user" && verb !== "validate") {
console.error(
`[lambda policies] usage: hyperframes lambda policies <role|user|validate> [args]`,
);
failUsage();
}
const { runPolicies } = await import("./lambda/policies.js");
await runPolicies({
verb,
inputPath: args.extra as string | undefined,
json: Boolean(args.json),
});
return;
}
default:
console.error(`${c.error("Unknown subcommand:")} ${subcommand}\n${HELP}`);
failUsage();
}
},
});
function parseIntFlag(raw: unknown): number | undefined {
if (raw === undefined || raw === null || raw === "") return undefined;
const n = Number.parseInt(String(raw), 10);
return Number.isFinite(n) ? n : undefined;
}
/**
* Parse a flag that must be a positive integer (>= 1) when supplied.
* Negative values or non-integers fail loudly instead of flowing into
* the SDK and producing opaque AWS validation errors mid-render.
*/
function parsePositiveInt(raw: unknown, flagName: string): number | undefined {
const n = parseIntFlag(raw);
if (n === undefined) return undefined;
if (!Number.isInteger(n) || n < 1) {
throw new CliUsageError(`[lambda] ${flagName} must be a positive integer; got ${n}`);
}
return n;
}
/**
* Parse a string-union flag against a closed set of allowed values.
* Returns `defaultValue` (which may be `undefined`) when the input is
* empty; throws with a flag-specific message when the value is set
* but unrecognised.
*/
function parseEnum<T extends string>(
raw: unknown,
allowed: readonly T[],
errorPrefix: string,
defaultValue: T | undefined,
): T | undefined {
if (raw === undefined || raw === null || raw === "") return defaultValue;
const s = String(raw);
if ((allowed as readonly string[]).includes(s)) return s as T;
throw new CliUsageError(`${errorPrefix} must be ${allowed.join("|")}; got ${s}`);
}
const FORMATS = [
"mp4",
"mov",
"png-sequence",
"webm",
] as const satisfies readonly DistributedFormat[];
const CODECS = ["h264", "h265"] as const;
const QUALITIES = ["draft", "standard", "high"] as const;
const CHROME_SOURCES = ["sparticuz", "chrome-headless-shell"] as const;
const parseFormat = (raw: unknown): (typeof FORMATS)[number] =>
parseEnum(raw, FORMATS, "[lambda render] --format", "mp4")!;
const parseCodec = (raw: unknown): (typeof CODECS)[number] | undefined =>
parseEnum(raw, CODECS, "[lambda render] --codec", undefined);
const parseQuality = (raw: unknown): (typeof QUALITIES)[number] | undefined =>
parseEnum(raw, QUALITIES, "[lambda render] --quality", undefined);
const parseChromeSource = (raw: unknown): (typeof CHROME_SOURCES)[number] =>
parseEnum(raw, CHROME_SOURCES, "[lambda deploy] --chrome-source", "sparticuz")!;
const VIDEO_ARCHS = ["x86_64", "arm64"] as const satisfies readonly VideoArch[];
const parseVideoArch = (raw: unknown): (typeof VIDEO_ARCHS)[number] | undefined =>
parseEnum(raw, VIDEO_ARCHS, "[lambda deploy] --video-arch", undefined);
/**
* Lambda flavor of the shared {@link parseOutputResolutionFlag} — same wire
* contract as the Cloud Run counterpart. Runtime work lives in the shared
* util; wire-config-level coverage lives at `./lambda/render.test.ts` /
* `./lambda/render-batch.test.ts`, and full input-space coverage at
* `../utils/parseOutputResolution.test.ts`.
*/
function parseOutputResolution(raw: unknown): {
outputResolution: CanvasResolution | undefined;
outputResolutionAspectAgnostic: boolean;
} {
return parseOutputResolutionFlag(raw, {
surfaceLabel: "[lambda render]",
// The Lambda `--output-resolution` help text advertises the full alias
// list (tier-only + orientation-suffixed) — keep the error message
// faithful to that surface's docs.
aliasHint:
"1080p, 4k, uhd, hd, 1080p-portrait, portrait-1080p, 4k-portrait, 1080p-square, square-1080p, 4k-square",
});
}