feat(cli): embed private dependency tarballs into Playwright code bundles [RED-855] [ship]

[sorccu]

Linear: RED-855

What

Adds a bundle.packages.embed config option (a new top-level bundle.packages section, which the RED-862 auto-detection options will expand) that embeds npm registry tarballs into the Playwright Check Suite code bundle at .checkly/embedded-packages/*.tgz, so runners can install packages they cannot fetch themselves (e.g. from a private registry that is only reachable from the customer's network). The runner half that serves the embedded tarballs through a local registry during install (RED-856) is already deployed, so this feature is releasable.

How

Three commits, one per layer (plus follow-ups: platform-independent npm-cache tests for Windows CI, and moving the tarball cache to node_modules/.cache/checkly):

1. Config option — bundle.packages.embed?: string[] (package names embed every lockfile version; name@version pins an exact version; initially added as checks.embeddedPackages and moved before release), with runtime shape validation at config load — including rejecting a misshapen bundle or bundle.packages value that would otherwise silently disable embedding — and plumbing through ProjectParseOpts → Session for deploy/test/validate/pw-test/parse-project.
2. Services (src/services/embedded-packages/) — lockfile enumeration (pnpm-lock.yaml v6/v9, package-lock.json v2/v3, with precise reasons for git/file/workspace/integrity-less entries), .npmrc parsing with scope-aware registry resolution, nerf-dart auth matching and npm_config_* env layering, SRI integrity helpers, and a content-addressed per-user tarball cache with a read-only npm-cache (cacache) lookup tier.
3. Wiring — a memoized session-level materializer shared by validation and bundling; project validation resolves the configured entries against the lockfile before any bundling (grouped fatal diagnostics — multi-entry failures render under per-problem headings naming the lockfile once, with available versions listed for stale pins); Playwright bundling appends the verified tarballs at the contract path via explicit archive paths, independent of workspace layout.

Tarballs are always the verbatim registry artifact, verified against the lockfile's integrity hash, sourced through CLI cache → npm cacache → registry download (proxy-aware via the existing assignProxy helper, credentials redacted from errors). Downloads are cached under the workspace root's node_modules/.cache/checkly (persisted automatically by CI setups that cache node_modules; a per-user cache dir is the read/write fallback; CHECKLY_CACHE_DIR overrides), so nothing user-visible lands in the project outside node_modules. The pnpm store cannot serve as a source because it retains only unpacked per-file blobs, not original tarballs.

Wildcards (added after review of the initial version): entries may contain * wildcards — @acme/*, acme-*, @acme/*-utils — where each * matches any run of characters except /, so a pattern never crosses the scope separator; wildcards combine with exact version pins and resolve against the lockfile only. Matches a spec cannot embed are skipped (workspace members silently; git/file/URL and integrity-less dependencies via a non-fatal warning diagnostic, since the runner must fetch those itself), while a spec whose only matches cannot be embedded — or that matches nothing — remains an error. Each wildcard announces what it selected during bundling. Excluded lockfile entries now carry a structured kind (workspace vs unfetchable), with npm/pnpm links pointing outside the workspace classified as unfetchable.

Dependency cache invalidation — the resolved embed set (name@version + lockfile integrity) is mixed into the code bundle's cacheHash as a new embedded-package: record type, so changing bundle.packages.embed invalidates the runner's install cache even when the lockfile is unchanged (previously the hash covered only lockfile + package.json + .npmrc + caching.dependencyCache.version, so an edited embed list silently reused a stale cached install). Projects without embedded packages keep byte-identical digests, and a new cross-language parity fixture pins all optional record groups in order for the terraform-provider-checkly mirror.

Deliberate v1 limits (documented; follow-ups tracked in Linear): only explicitly listed packages are embedded (no auto-detection, including transitive private deps — see the stacked follow-up PR), no yarn/bun lockfiles, .npmrc proxy/cafile/strict-ssl keys not honored (proxy env vars work).

Other changes

• Oversized-bundle error handling — the API rejects a code bundle over its size limit (currently 30 MB) with HTTP 413, which previously surfaced as a raw Payload content length greater than maximum allowed: <bytes> message. Since embedded tarballs can grow bundles toward that limit, the CLI now maps 413 to a typed error and reports the bundle size, the server-reported limit (parsed from the response, never hard-coded client-side), and remediation steps — mentioning bundle.packages.embed only when the bundle actually embeds packages.

Testing

• 110+ new unit tests (spec parsing, npmrc/registry/auth, lockfile enumeration, cache, materializer against a local HTTP registry covering auth, integrity mismatch, cache tiers).
• Offline integration tests: fixtures with committed deterministic tarballs pre-seeded into a temp CHECKLY_CACHE_DIR assert the archive contains the contract paths (including subdirectory Playwright configs and version-pin filtering) and that a package missing from the lockfile fails validation.
• Cache-hash coverage: no-op equivalence for empty embed lists, order-insensitivity, sensitivity to version/integrity changes, pinned parity fixtures, and a config-driven end-to-end test asserting the payload cacheHash differs between two embed lists.
• Full suite: 1976 passed (including 30+ wildcard parse/match/plan tests). Manual smoke test against registry.npmjs.org: bundled tarball byte-identical to the lockfile integrity; warm-cache re-run skips the download.

🤖 Generated with Claude Code

[github-actions]

Auto-approved: ship/show PR from a same-repo branch.