feat: add enterprise mirror support for air-gap deployments (Phase 1)

[avrabe]

Summary

Implements complete enterprise air-gap support (Issue #208) with both Phase 1 (mirrors) and Phase 2 (vendoring) in a single PR.

Phase 1: Environment Variable Mirrors

Core Infrastructure

• toolchains/secure_download.bzl: Add BAZEL_WASM_GITHUB_MIRROR support
  • Affects: wasm-tools, wit-bindgen, wac, wkg, wasmtime, wizer, wasi-sdk
  • Default: https://github.com

JavaScript Toolchain

• toolchains/jco_toolchain.bzl: Add mirror configuration
  • BAZEL_NODEJS_MIRROR: Node.js binary downloads (default: https://nodejs.org)
  • BAZEL_NPM_REGISTRY: npm package registry (default: https://registry.npmjs.org)
  • Creates .npmrc when custom registry specified

Go Toolchain

• toolchains/tinygo_toolchain.bzl: Add Go ecosystem mirrors
  • BAZEL_GO_MIRROR: Go SDK downloads (default: https://go.dev)
  • BAZEL_GOPROXY: Go module proxy (default: https://proxy.golang.org,direct)

Documentation

• .bazelrc: Complete documentation with examples
  • Corporate mirror configuration guide
  • Example configurations for JFrog/Nexus/Harbor
  • Security notes about SHA256 verification

Phase 2: Bazel-Native Vendoring (NEW!)

Pure Bazel Infrastructure - ZERO Shell Scripts

• tools/vendor/vendor_toolchains.bzl: Repository rule for downloading toolchains

  • Reuses existing secure_download infrastructure
  • Downloads to Bazel repository cache
  • Creates manifest of vendored items

• tools/vendor/defs.bzl: Export action using file-ops WASM component

  • Copies files from Bazel cache to third_party/
  • Uses file-ops component for all file operations
  • NO shell commands, pure WASM

• tools/vendor/README.md: Comprehensive documentation

  • Complete usage guide
  • Storage options (git, Git LFS, network share, artifact server)
  • Troubleshooting and maintenance

Enhanced Offline Mode

• toolchains/secure_download.bzl: Add BAZEL_WASM_OFFLINE support
  • Checks third_party/toolchains/ before downloading
  • Falls back to vendored files when offline mode enabled
  • Helpful error messages with vendoring instructions

Integration Tests

• test/vendor_integration/: Validates vendoring infrastructure
  • Build tests for vendor infrastructure
  • Documentation verification

Complete Enterprise Workflow

Scenario 1: Corporate Mirror (Phase 1)

# .bazelrc or environment
export BAZEL_WASM_GITHUB_MIRROR=https://jfrog.corp.com/github
export BAZEL_NPM_REGISTRY=https://npm.corp.com

bazel build //examples/basic:hello_component
# Downloads from corporate mirrors

Scenario 2: Air-Gap with Vendoring (Phase 2)

# Step 1: On internet-connected machine
bazel fetch @vendored_toolchains//...
bazel run @vendored_toolchains//:export_to_third_party

# Step 2: Transfer repository to air-gapped machine

# Step 3: Build offline
export BAZEL_WASM_OFFLINE=1
bazel build //examples/basic:hello_component
# Uses third_party/, no downloads

Scenario 3: Hybrid (Best of Both)

# Use corporate mirror + vendored fallback
export BAZEL_WASM_GITHUB_MIRROR=https://jfrog.corp.com/github
export BAZEL_WASM_OFFLINE=prefer  # Try vendored first

bazel build //examples/basic:hello_component

Benefits

✅ Zero Breaking Changes: All environment variables default to public URLs
✅ Zero Shell Scripts: Pure Bazel + WASM component for vendoring
✅ Enterprise Ready: Supports JFrog, Nexus, Harbor, Minio
✅ Security: Maintains mandatory SHA256 checksum verification
✅ Air-Gap Capable: Complete offline builds with vendoring
✅ Cross-Platform: Works identically on Linux/Mac/Windows
✅ Backward Compatible: Existing builds work without any configuration
✅ Hermetic: No system dependencies, pure Bazel infrastructure

Testing

Phase 1:

• ✅ Build completed successfully with default public URLs
• ✅ All toolchains download from correct default mirrors
• ✅ All 20+ CI checks passed

Phase 2:

• ✅ Vendoring infrastructure builds successfully
• ✅ Integration tests pass
• ✅ Documentation verified

Architecture

Phase 1: Mirror Override

Environment Variables → secure_download → Corporate Mirror → Build

Phase 2: Offline Vendoring

Repository Rule → Download to Cache → File-Ops Component → third_party/
                                                              ↓
                                            Offline Mode → Use Vendored Files

File Changes Summary

File	Lines Changed	Purpose
.bazelrc	+35	Mirror documentation
toolchains/secure_download.bzl	+32	Mirror + offline support
toolchains/jco_toolchain.bzl	+11	Node.js/npm mirrors
toolchains/tinygo_toolchain.bzl	+12	Go mirrors
tools/vendor/vendor_toolchains.bzl	+203	Vendoring repository rule
tools/vendor/defs.bzl	+113	Export action
tools/vendor/README.md	+405	Complete documentation
test/vendor_integration/BUILD.bazel	+21	Integration tests

Total: 832 lines added, 21 lines removed

Related

Closes #208

Next Steps

After merge:

• Validate in real enterprise environment
• Document mirror setup for different artifact managers
• Add more storage options documentation
• Consider: automatic vendoring in CI/CD