2 Commits

Include renames

Author	SHA1	Message	Date
James RussoandClaude Opus 4.7	5d264e146c	docs(lambda): document webm support + simplify-review fixes (#953) ... * docs(lambda): document webm support in distributed mode PR 8.4 of the WebM distributed-rendering plan (v1.5 backlog #1; see DISTRIBUTED-RENDERING-PLAN.md §7.2). User-facing docs catch up with the shipped capability. Updates docs/deploy/migrating-to-hyperframes-lambda.mdx: - "Output format" row in the migration table now lists `webm` alongside mp4 / mov / png-sequence with a note that webm uses libvpx-vp9 + closed-GOP concat-copy. HDR mp4 remains the only refused format. - "No webm distributed" caveat replaced with "webm uses closed-GOP VP9" explainer covering the encoder args (`-g <chunkSize>`, `-keyint_min <chunkSize>`, `-auto-alt-ref 0`, `-cpu-used 2`), why alt-ref disable is load-bearing, and that the output preserves alpha via yuva420p with Opus audio. - Migration checklist no longer asks adopters to filter out webm compositions; only HDR-dependent renders need to stay on the previous framework. aws-lambda.mdx doesn't currently call out webm as unsupported (only HDR in the v1 surface list), so it gets no copy edits beyond the migration guide. The internal planning doc (DISTRIBUTED-RENDERING-PLAN.md §7.2, §8, §12 — kept outside the repo) gets matching updates: format support matrix flipped ✓, v1.5 backlog #1 marked shipped, HDR promoted to the new top item, and the rev-12 → rev-13 status line. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor: address simplify-review findings on webm stack Folds in cleanups identified by a multi-agent code-review pass over the 4-PR webm-distributed stack: - plan.ts: `resolveEncoderTriple()` webm case now calls `getEncoderPreset(quality, "webm")` for its preset string instead of hardcoding "good". The hardcode was wrong for `quality: "draft"` (`getEncoderPreset` returns "realtime" for that tier) — would have silently overridden the draft → realtime mapping for distributed webm renders. - chunkEncoder.ts: trim the new VP9 closed-GOP comment block from ~18 lines of WHY narration down to the 6 lines that actually explain why (alt-ref + cpu-used drift). Match the alpha branch's idempotent-push comment to the same standard. - chunkEncoder.test.ts: drop the duplicate WHY comment that restated the implementation comment in plain words. - webm-concat-copy.test.ts: rewrite the file-header docstring to describe the contract being tested instead of the PR-8.1-gating history; strip "PR 8.2 / Path A / Path B" references from error messages (they belong in PR bodies, not in test output). Consolidate the yuva420p alpha smoke into a single `it()` block (was a full 4-test describe with duplicated setup) — the yuv420p block already covers the probe/decode/frame-count contract; the alpha smoke only needs to prove the alpha args don't break concat-copy. - plan.test.ts: drop the "PR 8.1 proved the contract" comment. - webm-vp9 fixture: drop the aspirational "Other webm-with-audio fixtures cover the mux path separately when added" sentence (no other fixtures exist). Regenerated the baseline via `docker:test:update webm-vp9` to reflect the updated comment. - migrating-to-hyperframes-lambda.mdx: add a paragraph about distributed webm's perf cost — ~10-25% larger files at constant CRF due to forced keyframes, and slower per-chunk encode due to `-cpu-used 2` being more conservative than the libvpx default. All unit tests + the webm-vp9 distributed-simulated regression still pass after these changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(cli): accept --format=webm in `hyperframes lambda render` The CLI's `lambda render` subcommand's FORMATS allowlist and the `RenderArgs.format` type still narrowed to `mp4 | mov | png-sequence`, so even though the producer + aws-lambda packages now support webm end-to-end, the CLI surface rejected it with `--format must be mp4|mov| png-sequence`. Add webm to both spots and update the --help description. Surfaced during real-AWS deploy prep — the local lambda-local / distributed-simulated tests didn't go through the CLI so the gap went unnoticed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(producer): font cache writes to /tmp on Lambda (read-only \$HOME) The deterministic Google Fonts cache was rooted at `\$HOME/.cache/hyperframes/fonts`, which fails on AWS Lambda — the runtime's `\$HOME` resolves to a `/home/sbx_*` directory tree that's read-only. `mkdirSync(..., { recursive: true })` can't create that path and the plan stage trips with `ENOENT: no such file or directory, mkdir '/home/sbx_user1051/.cache/hyperframes/fonts/space-mono'` on every Lambda render that pulls a Google Font (i.e. every distributed fixture using `@import url("https://fonts.googleapis.com/...")`). Detect Lambda via `\$AWS_LAMBDA_FUNCTION_NAME` and route the cache to `tmpdir()/hyperframes/fonts` in that case. Lambda's `/tmp` survives across invocations on a warm container, so cache hit rate is the same as non-Lambda runs. Also honor an explicit `\$HYPERFRAMES_FONT_CACHE_DIR` override for adopters who want a different location regardless of the runtime. Surfaced while verifying webm distributed end-to-end on real AWS — the same bug affects mp4 fixtures using Google Fonts; webm just happened to be the one I tried first. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor: extract DistributedFormat type + trim font-cache resolver Second simplify-review pass on the webm stack flagged two cleanups: 1. **`DistributedFormat` type duplicated 10 times.** Every file in the distributed pipeline carried its own copy of `"mp4" | "mov" | "png-sequence" | "webm"` — adding a new format meant a 10-place edit with no compile-time guarantee they stayed in sync. Extract a single source of truth in `packages/producer/src/services/distributed/shared.ts`, re-export from `@hyperframes/producer/distributed` and `@hyperframes/aws-lambda/sdk`, and have all callers pull from there. The aws-lambda `ALLOWED_FORMATS` runtime tuple and the CLI's `FORMATS` tuple now both use `satisfies readonly DistributedFormat[]` so the compiler enforces the runtime allowlist stays in sync with the type. 2. **`deterministicFonts.ts` font-cache resolver was over-commented.** Trim the 7-line block to 4 lines (drop the aspirational "and other read-only-FS execution environments" — only Lambda is detected — and the warm-container `/tmp` persistence narration — anyone reading already knows Lambda /tmp semantics). Collapse the two-step `if (explicit && explicit.length > 0)` into a single nullish-coalesce expression now that the empty-string defensive check is gone (`process.env.X` is `string | undefined`, no third shape to guard against). Out-of-scope skips (called out by the agents, deferred): - In-process `RenderConfig.format` and the in-process CLI's `render.ts` format union still carry their own inline copies. The union happens to coincide today but they're separate concerns — leaving them alone limits this PR's blast radius. - `fontCacheDir(slug)` / `resolveFontCacheRoot()` naming asymmetry flagged as taste; skipping. - Pre-existing redundant `existsSync` before `mkdirSync({ recursive: true })` in `fontCacheDir` — out of scope. All tests + typecheck still pass. Lambda render still works end-to-end (no functional changes). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(lambda): drop plan-doc reference from migration checklist PR review feedback: source/docs should not mention the distributed-rendering planning doc. Tighten the migration checklist sentence to describe the webm path directly rather than referencing the doc's version label. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(producer): split resolveEncoderTriple into mp4 + non-mp4 helpers CI Fallow audit on PR #953 flagged `resolveEncoderTriple` at CRAP 31.6 — the function interleaved (a) mp4 codec validation + dispatch, (b) the non-mp4 codec-rejection throw, and (c) per-format dispatch. Splitting into `resolveMp4EncoderTriple` + `resolveNonMp4EncoderTriple` drops the top-level function's cyclomatic complexity below the threshold while preserving every error message and code path. Behavior unchanged. Also extracts an `EncoderTriple` type alias so the three functions share the return shape declaratively rather than repeating it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-19 04:11:26 -04:00
James Russo	e90ad2da61	feat(cli): add hyperframes lambda deploy/render/progress/destroy (#910) ... * feat(cli): add hyperframes lambda deploy/render/progress/destroy Wraps the @hyperframes/aws-lambda SDK + the Phase 6a SAM template behind a single CLI surface so an end-to-end render is three commands instead of the ~8 manual bun+sam+aws steps the smoke script does today: hyperframes lambda deploy hyperframes lambda render ./my-project --width 1920 --height 1080 --wait hyperframes lambda destroy Subcommands: - deploy: build handler.zip + sam-deploy + persist stack outputs to <cwd>/.hyperframes/lambda-stack-<name>.json - sites create: pre-upload a project to S3 with a stable content hash so re-renders skip the tar+PUT pass - render: start a Step Functions execution; --wait blocks and streams per-chunk progress + accrued cost - progress: one-shot snapshot — status, frames, cost breakdown, errors. Accepts renderId or executionArn - destroy: sam-delete + drop the local state file (S3 bucket is Retain'd by the template; documented in --help and in docs/packages/cli.mdx) To keep @sparticuz/chromium out of the CLI's transitive deps, this also adds a dedicated ./sdk subpath export to @hyperframes/aws-lambda; the CLI imports from @hyperframes/aws-lambda/sdk exclusively. The existing . barrel still re-exports both handler + SDK for adopters who want one entry point. Defaults are deliberately cost-conservative for first-time users: --concurrency=8 (low enough to never surprise) and --memory=10240 (the common case; documented for adopters who want to tune down). Tests: 5 unit tests on the state-file round-trip. CLI integration against sam local invoke is part of the upcoming PR 6.6 (lambda-local regression harness). * refactor(cli): /simplify pass on the lambda command group Two small cleanups on top of the lambda CLI: - Replace parseFormat / parseCodec / parseQuality / parseChromeSource (four near-identical helpers) with a single generic parseEnum() + typed const-tuple lookups. The four callers now read as one-line arrow functions that lift the allowed values out of the function body so they're easy to extend. - DEFAULT_STACK_NAME was const-declared then re-exported at the bottom of state.ts; just mark the const export inline. No behavior changes. All CLI tests still pass. * fix(cli): keep @hyperframes/aws-lambda external in the tsup bundle esbuild can't bundle @hyperframes/aws-lambda's transitive AWS SDK deps (@aws-sdk/* + @smithy/*) cleanly into a node binary — the SDK's .browser.js conditional re-exports break the resolver: ESM Build failed No matching export in "splitStream.browser.js" for import "splitStream" (and ~10 similar errors) Mark aws-lambda as `external` so esbuild doesn't follow it, and move it from devDependencies to dependencies so the published CLI can resolve it from node_modules at runtime. The lambda subverb files dynamic-import only on `hyperframes lambda *` invocation, so the CLI cold-start cost is unchanged. The install-size hit (AWS SDK + @sparticuz/chromium ≈ 200 MiB) is documented as a v1 tradeoff; a future split into a lambda-sdk-only subpackage can pare this back. * fix(cli): address PR review on lambda CLI Two blockers + four important items from Vai's review: - `--memory` was parsed and recorded in the local state file but never forwarded to `sam deploy` as a parameter override. Worse, `progress.ts` then read the *recorded* value for cost math, so `--memory 5120` produced wrong cost numbers downstream. Thread `LambdaMemoryMb` through samDeploy's --parameter-overrides. - `--profile` was only consumed by deploy / destroy. render and progress fell back to the default credentials chain — a user with `--profile prod` would silently render against their default account (wrong-account billing footgun). Set `process.env.AWS_PROFILE` (and `AWS_REGION`) in the dispatcher before any subverb runs; the AWS SDK reads them natively, so render / progress / sites all benefit without each subverb threading the flag through the SDK call. - `--profile` + destroy now also reads `process.env.AWS_PROFILE` as a fallback (matching deploy's existing env fallback). - `--wait --json` printed both the start handle AND the final progress snapshot, producing two concatenated JSON blobs that `jq` rejected. Now emits a single document: handle (without --wait) OR final progress (with --wait). - Negative integers on `--width` / `--height` / `--chunk-size` / `--max-parallel-chunks` / `--memory` / `--concurrency` now fail loudly via a new `parsePositiveInt` wrapper instead of flowing into the SDK and producing opaque AWS validation errors mid- render. - `DEFAULT_STACK_NAME` is now centralized to the literal `"hyperframes-default"` and consumed from one place. Previously the value was assembled as `hyperframes-${"default"}` in three sites and hardcoded as `"hyperframes-default"` in a fourth. `requireStack`'s hint now matches the dispatcher's default. The faked `SiteHandle` for `--site-id` keeps the documented placeholder fields but also surfaces `bucketName` (from PR 909's extended SiteHandle interface), matching the SDK contract. All CLI unit tests + the full bundler build still pass. * fix(cli): keep aws-lambda out of CLI runtime deps The "Smoke: global install" CI step packs the CLI via `npm pack` and installs it globally via `npm install -g <tgz>`. npm doesn't understand the workspace: protocol, so a runtime `dependencies` entry of `@hyperframes/aws-lambda: workspace:*` blows up with: npm error code EUNSUPPORTEDPROTOCOL npm error Unsupported URL Type "workspace:": workspace:* (pnpm rewrites workspace:* on publish; npm pack doesn't.) Three changes to unblock the smoke + keep the published CLI install small for users who don't deploy to Lambda: - Move `@hyperframes/aws-lambda` from CLI's `dependencies` back to `devDependencies`. It's already external in tsup.config.ts; the bundle references it via runtime resolution only. - Convert the static `import { … } from "@hyperframes/aws-lambda/sdk"` in sites.ts / render.ts / progress.ts to `await import()` inside each function. tsup with `splitting: false` was inlining those static imports at the top of the bundle, which made Node eagerly resolve them at CLI startup (MODULE_NOT_FOUND before any lambda subcommand even runs). Dynamic imports stay dynamic in the bundle. - Add a friendly missing-module check in the lambda dispatcher. When a user runs `hyperframes lambda deploy / render / sites / progress / destroy` without aws-lambda installed, they now see: @hyperframes/aws-lambda is not installed. The `hyperframes lambda deploy` command needs it at runtime. Install it alongside the CLI: npm install -g @hyperframes/aws-lambda Verified locally: pack + global install + `hyperframes init --example blank` now succeeds end-to-end (was the same scenario the CI smoke job runs).	2026-05-17 13:06:00 -04:00