[compile-extension] Fetch Docker assets lazily

[adamziel]

What it does

Makes @php-wasm/compile-extension usable without checking out WordPress/wordpress-playground.

Before this PR, you've needed to get the PHP build context from the Playground repository before using the compilation extensions.

After this PR, the package lazily sparse-fetches the minimal PHP.wasm Docker asset set it needs. Published packages fetch from the matching Playground tag, e.g. package 3.1.27 fetches v3.1.27. Playground workspace/dev runs use local assets when present and otherwise fetch from trunk.

Rationale

The README said the package only needs Docker and Node, but the CLI still expected packages/php-wasm/compile to exist locally. Downstream CI had to sparse clone Playground as a workaround.

Implementation

Added an isomorphic-git based sparse fetcher for the required Dockerfiles, base-image scripts, PHP patches, and extension build script. Added --prepare-image so workflows can prepare the package-owned Docker image before compiling a final extension.

The package does not ship Playground-built dependency archives. Consumers should vendor/build their own Emscripten archives and pass them via --extra-cflags / --extra-ldflags.

Testing instructions

Run:

npx nx run php-wasm-compile-extension:test-lazy-docker-asset-fetch

This target builds the npm package, verifies the dry-run tarball does not include Playground Docker assets, runs the built CLI from outside the repo, verifies the cache was fetched from the matching tag, and uses a fake Docker binary to stop before a real image build.

The full compile-extension CI job now runs this package-boundary check before the Docker-backed integration fixtures.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR makes @php-wasm/compile-extension runnable outside a WordPress/wordpress-playground checkout by lazily fetching only the minimal Docker-related assets it needs, and adds a CLI mode to pre-build the required Docker images.

Changes:

• Added an isomorphic-git-based sparse fetcher + caching for required PHP.wasm Docker build assets.
• Introduced --prepare-image to build the base/extension images without compiling an extension.
• Added CI + tests to verify the published-package boundary (no bundled Playground assets; lazy fetch works).

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/php-wasm/compile-extension/vite.config.ts	Externalizes isomorphic-git modules for the bundle/runtime.
packages/php-wasm/compile-extension/tests/test-lazy-docker-asset-fetch.sh	End-to-end check that built package fetches assets lazily and doesn’t ship them.
packages/php-wasm/compile-extension/src/git-sparse-checkout.ts	Implements sparse blob fetch via git-upload-pack and isomorphic-git object reads.
packages/php-wasm/compile-extension/src/docker.ts	Makes docker context resolution async and adds lazy asset fetching fallback.
packages/php-wasm/compile-extension/src/docker.spec.ts	Adds unit tests for docker context selection and ref resolution.
packages/php-wasm/compile-extension/src/docker-assets.ts	Adds asset list, cache layout, ref selection, and sparse fetch integration.
packages/php-wasm/compile-extension/src/compile.ts	Adds image preparation flow and updates compile flow for async context + docker check.
packages/php-wasm/compile-extension/src/cli.ts	Adds --prepare-image mode and adjusts argument validation + workspace detection.
packages/php-wasm/compile-extension/project.json	Removes docker-asset copying during build; adds clean + a new Nx test target.
packages/php-wasm/compile-extension/package.json	Adds isomorphic-git dependency.
packages/php-wasm/compile-extension/README.md	Documents lazy fetch behavior, caching, and --prepare-image.
.github/workflows/ci.yml	Runs the new lazy-fetch verification step before integration fixtures.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.