Wait for index.html before copying admin static_root during dev

[MitchLillie]

What

This PR adds a new wait_for_file build step that waits for index.html to exist in the admin extension's static_root directory before copying files.

Why

Fixes https://github.com/shop/issues-admin-extensibility/issues/2411

When running shopify app dev immediately after shopify app init, there's a race condition where the web build process (which produces dist/index.html) hasn't completed before the admin extension tries to copy files from static_root. This causes the dev session to fail with:

Validation errors
  • index_missing: index.html must be present in the bundle.

How

1. New wait_for_file build step (wait-for-file-step.ts):

   • Waits up to 60 seconds for a specific file to appear
   • Polls every 500ms until the file exists
   • Succeeds immediately if the file already exists or if the config key isn't set
   • Throws a clear error with guidance if the file doesn't appear within the timeout

2. Updated admin extension specification (admin.ts):

   • Added the wait_for_file step before the include_assets step
   • Configured to wait for index.html in the directory specified by admin.static_root

Testing

• Added comprehensive unit tests for the new wait_for_file step
• All existing tests pass

---

Tophatting Instructions

Prerequisites

• Build the CLI from this branch:

  pnpm install
  pnpm build

Steps to reproduce the issue (before fix)

1. Create a new extension-only app:

   HOSTED_APPS=1 pnpm shopify app init --name test-fix-index-html --path="$HOME/tmp"

   • Select "Build an extension-only app (Shopify-hosted Preact app home and extensions, no back-end)"

2. Immediately run dev:

   HOSTED_APPS=1 pnpm shopify app dev --path="$HOME/tmp/test-fix-index-html"

3. Expected (before fix): You should see an error like:

   ╭─ error ─────────────────────────────────────────────────────╮
   │ Version couldn't be created.                                │
   │                                                              │
   │ admin                                                        │
   │                                                              │
   │ Validation errors                                            │
   │   • index_missing: index.html must be present in the bundle. │
   ╰──────────────────────────────────────────────────────────────╯
   

Steps to verify the fix

1. Create a new extension-only app:

   HOSTED_APPS=1 pnpm shopify app init --name test-fix-index-html --path="$HOME/tmp"

2. Immediately run dev:

   HOSTED_APPS=1 pnpm shopify app dev --path="$HOME/tmp/test-fix-index-html"

3. Expected (with fix):

   • You should see a message like: Waiting for 'index.html' in './dist'...
   • After a few seconds: Found 'index.html' in './dist' (waited X.Xs)
   • The dev session should start successfully without the validation error

Additional scenarios to test

1. File already exists: If you run pnpm build in the app directory before shopify app dev, it should proceed immediately without waiting.

2. Timeout behavior: If the build process fails and the file never appears, you should see a clear timeout error after 60 seconds:

   Timed out waiting for 'index.html' in './dist' after 60s. Make sure your build process creates this file (e.g., via a predev hook).
   

3. No static_root configured: If the app doesn't have admin.static_root configured, the wait step should be skipped silently.