feat(client+core): CLI side of direct bucket upload for Percy resources (PPLT-5303)

[Manoj-Katta]

What this changes

CLI side of PPLT-5303 — GCS network cost reduction. Implements the client end of the Direct Bucket Upload tech spec.

Today every Percy resource (HTML / CSS / JS / fonts / inline images) goes CLI → base64 JSON → percy-api → GCS. percy-api decodes, re-hashes, streams to GCS — pure byte brokerage on the hot path. This PR teaches the CLI to upload resources directly to GCS via a per-resource V4 signed URL minted by percy-api in the missing-resources response. Integrity is preserved at the GCS layer via Content-MD5 + Content-Length baked into the signed URL.

Rollout is Strategy A (locked by review comment on the tech spec): per-org LD flag, legacy POST /resources path stays live indefinitely as the per-resource fallback. Nothing in this PR breaks any existing customer — old API ignores the new header and the CLI uses the legacy path; new API + new CLI start using the direct path once the LD flag is on for the org.

Wire contract added

CLI → API on POST /builds/:id/snapshots:

• Request header: X-Percy-Capabilities: direct-upload-v1
• Each entry in relationships.resources.data[].attributes gains:
  • content-md5 — base64-encoded MD5 of the resource bytes (RFC 1864)
  • content-length — byte count

API → CLI in the missing-resources response, each entry may now carry:

• signed-upload-url — V4-signed PUT URL
• signed-upload-expires — ISO 8601 expiry timestamp

CLI → GCS when a signed URL is returned:

PUT <signed-upload-url>
Content-MD5:    <same base64 we declared>
Content-Length: <same length we declared>
Content-Type:   <resource mimetype>
Body:           <raw bytes — not base64, not JSON>

Failure handling

Per-resource decision, not per-build:

• Transport-class (network errors, 5xx after retries, 403 expired, 429) → resource falls back to the legacy POST /resources path silently. Build still succeeds.
• Correctness-class (400 BadDigest, 412 Precondition Failed) → thrown. These indicate a real bug (wrong md5/length declared, or single-use URL replayed). Falling back here would mask the regression; fail-loud surfaces it.

Customer escape hatch

PERCY_DISABLE_DIRECT_UPLOAD=1 suppresses the capability header and forces every resource through the legacy path. Lets a latency-sensitive customer self-serve back to the old behavior without waiting on an LD flag flip. Strict parsing — only "1" or "true" (case-insensitive) count as enabled; "0"/"false" do NOT silently enable like a naive !!process.env.X would.

Commits (6, in a clean bottom-up order)

#	SHA	What
1	b09794a	createResource attaches md5 + contentLength to every resource (incl. PERCY_GZIP lockstep)
2	ebaeeb7	request() accepts rawBody: true to send raw Buffer bodies
3	c36c538	createSnapshot sends capability header + new attrs
4	3fc4608	uploadResourceDirect / uploadResourcesDirect primitives + failure classification
5	821c402	sendSnapshot partitions missing-resources between direct + legacy + strict env parsing
6	861047b	End-to-end integration test in @percy/core

Compatibility

Scenario	Result
New CLI + new API, LD flag on	Direct upload happens
New CLI + new API, LD flag off	API returns no signed URLs → CLI uses legacy. Transparent.
New CLI + old API	API ignores header, returns no signed URLs → CLI uses legacy. Transparent.
Old CLI + new API	No capability header → API doesn't mint URLs → legacy. Transparent.
New CLI + PERCY_DISABLE_DIRECT_UPLOAD=1	Capability header suppressed → API treats as old CLI → legacy.
New CLI + GCS unreachable for customer	Each PUT fails transport-class → falls back per-resource. Build succeeds.

What's intentionally NOT in this PR

• createBuild parity for declared resources. The static-image upload command uses createBuild declared resources, and symmetry suggests it should also carry content-md5/content-length. Held back until the percy-api side confirms it accepts those attrs on POST /builds — gated on O1 in the plan. Easy follow-up commit once confirmed.
• Docs. PERCY_DISABLE_DIRECT_UPLOAD doesn't appear in any README yet. Punted to a follow-up PR so the doc can describe the end-to-end behavior with the API side landed.

Open items (need API-side confirmation, not coding-blockers)

• O1 — POST /builds accepts content-md5 + content-length on declared resources (re-enables createBuild parity).
• O2 — Wire-attr naming: kebab-case (content-md5, content-length) as used here, or camelCase? Will mirror whatever the API side ships.
• O3 — Capability string: direct-upload-v1 is the working name. Confirm with API.

Test plan

• Unit tests: md5base64 (3), createResource & factories (6), request() rawBody (3), createSnapshot header + attrs (3 + 2 strict-parsing), uploadResourceDirect / uploadResourcesDirect (11), sendSnapshot partition + fallback (5)
• End-to-end in @percy/core with mocked GCS endpoint: happy path, transport failure → fallback, PERCY_DISABLE_DIRECT_UPLOAD forces legacy, Content-MD5 integrity matches declared md5 (4 tests)
• Existing regressions: full @percy/client suite (283/283 minus 1 pre-existing PAC proxy flake); existing createSnapshot / sendSnapshot tests updated to assert the new attrs; legacy POST /resources path still exercised by every test that doesn't return signed URLs.
• Staging end-to-end against real percy-api once the matching API PR lands (cross-repo, tracked separately).
• Manual smoke on a real production build with PERCY_DISABLE_DIRECT_UPLOAD=1 to confirm legacy still works for customers on the escape hatch.

Plan doc

Full implementation plan (both CLI and API sides, plus rollout/observability/rollback) is at docs/plans/2026-05-11-003-pplt5303-direct-bucket-upload-cli.md. That doc is gitignored — local reference only.

🤖 Generated with Claude Code