docker-shim: fail fast when shared BuildKit builder unavailable

[lukemarsden]

Summary

When /buildkit-cache exists, the shared BuildKit builder is REQUIRED for docker builds. Previously, the shim would inject cache flags even when the builder wasn't available, causing "Cache export is not supported for the docker driver" errors.

Changes

Fail-fast behavior: The shim now fails immediately with a clear error when:

• /buildkit-cache directory exists (expecting cached builds)
• The helix-buildkit container is missing or unreachable
• The helix-shared buildx builder cannot be created

Error message example:

docker-shim: build failed: shared BuildKit builder required for cached builds:
shared BuildKit container 'helix-buildkit' not found. This container should be
started by Hydra. Check that Hydra is running and has set up the BuildKit container.

The /buildkit-cache directory exists, which means cached builds are expected.
Ensure Hydra has started the helix-buildkit container.

Error before fix

🔨 Building helix-sway:latest...
[+] Building 0.0s (0/0)                                  docker:default
ERROR: failed to build: Cache export is not supported for the docker driver.

This error was confusing because it didn't explain what was wrong or how to fix it.

Principle

Follows the fail-fast principle: builds fail immediately with actionable error messages rather than proceeding with broken cache configuration.

🤖 Generated with Claude Code