feat: add --fallback-to-source flag for bytecode failures

[robertsLando]

Summary

• Moves the automatic source fallback (from 46a7f8e) behind a new --fallback-to-source CLI flag
• Default (no flag): warns about the bytecode failure, mentions --fallback-to-source in the warning, and skips the file. The empty VFS key is cleaned up so the prelude no longer crashes with UNEXPECTED-20 (NodeJS 22/24 issues/feedbacks tracker #87, Cross-compilation from macOS to Linux on arm64 broken on >=22 #181)
• With --fallback-to-source: ships the file as plain source instead of skipping it (the behaviour from 46a7f8e)

Test plan

• Cross-compile without --fallback-to-source → verify warning is logged with flag hint and file is skipped (no UNEXPECTED-20 crash)
• Cross-compile with --fallback-to-source → verify warning is logged and file is shipped as plain source
• Native compile (no fabrication failure) → verify no change in behaviour with or without the flag
• pkg --help shows the new flag

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds a new --fallback-to-source CLI flag to control what happens when V8 bytecode generation fails during packaging (commonly in cross-compilation scenarios). The intent is to make the default behavior “warn and skip the file” (instead of silently falling back to shipping source), while preserving the prior fallback behavior when the flag is explicitly enabled.

Changes:

• Add --fallback-to-source to CLI parsing and help output, and plumb the option into the producer pipeline.
• Change bytecode fabrication failure handling to either (a) ship plaintext source (flag enabled) or (b) warn and skip the file (default).
• Update docs to describe the new flag and recommended mitigations; update an existing test to pass the new flag.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
lib/index.ts	Adds the new boolean CLI flag and passes it into producer() options.
lib/producer.ts	Implements flag-driven behavior on bytecode fabrication failures; introduces Stripe.skip.
lib/packer.ts	Extends Stripe type with optional skip metadata.
prelude/bootstrap.js	Improves the runtime error message when a VFS entry has neither source nor bytecode.
lib/help.ts	Documents the new flag in pkg --help output.
test/test-50-extensions/main.js	Updates an existing integration test invocation to include --fallback-to-source.
docs-site/guide/targets.md	Adds “fallback to source” as an option in cross-compilation guidance.
docs-site/guide/getting-started.md	Adds the flag to the CLI reference table.
docs-site/guide/bytecode.md	Adds a new section documenting fallback-to-source behavior.

Comments suppressed due to low confidence (1)

lib/producer.ts:455

• The new skip mechanism only prevents recording the previous stripe’s payload range, but the VFS key is still pre-created earlier and other stripes for the same snap (notably STORE_STAT) will still be recorded. This leaves a VFS entry that existsSync/statSync considers present, but readFileSync later fails with UNEXPECTED-20. To truly “skip the file”, ensure no VFS entry (and no STORE_STAT) is emitted for that snap—e.g., build VFS entries lazily when adding a store, and/or track skipped snaps and suppress all subsequent stripes for them (and delete any pre-created VFS key).

      if (count === 2) {
        if (prevStripe && !prevStripe.skip) {
          const { store } = prevStripe;
          let { snap } = prevStripe;
          snap = snapshotify(snap, slash);
          const vfsKey = makeKey(doCompress, snap, slash);
          vfs[vfsKey][store] = [track, meter.bytes];
          track += meter.bytes;
        }