[Bug]: app deploy fails intermittently with ENOENT on <handle>.js.map when two UI extensions share a folder

// Repro: `app deploy` fails with ENOENT on <handle>.js.map when one shopify.extension.toml
// declares two UI extensions (both build into the same dist/ folder).
//
// Save as packages/app/src/cli/services/deploy/shared-dist-race.test.ts and, from packages/app:
//   pnpm vitest run src/cli/services/deploy/shared-dist-race.test.ts
//
// By default three delays line the two builds up so every run fails. They change timing only:
//   - the second extension enters its build SKEW_MS late (a slower build),
//   - a folder copy takes STAT_DELAY_MS longer to reach each .js.map it listed,
//   - the rename that puts a map back is held RENAME_HOLD_MS (its destination is already removed).
// FORCE=0 removes all three and loops at natural timing, where the failure is rare.
import {bundleAndBuildExtensions} from './bundle.js'
import {localAppContext} from '../app-context.js'
import {expect, test, vi} from 'vitest'
import {mkdirSync, mkdtempSync, rmSync, writeFileSync} from 'node:fs'
import {tmpdir} from 'node:os'
import {join} from 'node:path'

const forced = process.env.FORCE !== '0'
const SKEW_MS = forced ? 300 : 0
const iterations = Number(process.env.ITER ?? (forced ? 10 : 300))

// Runs before the imports: fs-extra (through graceful-fs) copies the fs functions when it loads.
vi.hoisted(() => {
  if (process.env.FORCE === '0') return
  const STAT_DELAY_MS = 150
  const RENAME_HOLD_MS = 1500
  const fs = process.getBuiltinModule('node:fs')
  // a source map in an extension's own dist folder, not its copy inside the deploy bundle
  const localMap = (file: unknown) =>
    typeof file === 'string' && file.endsWith('.js.map') && !file.includes('/.shopify/')
  const {lstat, rename} = fs
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  ;(fs as any).lstat = (...args: any[]) => {
    if (localMap(args[0])) setTimeout(() => Reflect.apply(lstat, fs, args), STAT_DELAY_MS)
    else Reflect.apply(lstat, fs, args)
  }
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  ;(fs as any).rename = (...args: any[]) => {
    if (localMap(args[1])) setTimeout(() => Reflect.apply(rename, fs, args), RENAME_HOLD_MS)
    else Reflect.apply(rename, fs, args)
  }
})

// Under vitest this plugin resolves to its ESM build, whose default export is the plugin itself;
// the CLI expects the CommonJS shape (`graphqlLoaderPlugin.default()`).
vi.mock('@luckycatfactory/esbuild-graphql-loader', async (importOriginal) => {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const actual: any = await importOriginal()
  return {default: {default: actual.default?.default ?? actual.default}}
})

function createApp(): string {
  const dir = mkdtempSync(join(tmpdir(), 'shared-dist-race-'))
  writeFileSync(join(dir, 'package.json'), JSON.stringify({name: 'shared-dist-race', private: true}))
  writeFileSync(
    join(dir, 'shopify.app.toml'),
    `client_id = "0123456789abcdef0123456789abcdef"
name = "shared-dist-race"
application_url = "https://example.com"
embedded = true

[access_scopes]
scopes = "read_orders"

[auth]
redirect_urls = ["https://example.com/auth/callback"]

[webhooks]
api_version = "2026-01"
`,
  )
  const extension = join(dir, 'extensions', 'two-blocks')
  mkdirSync(join(extension, 'src'), {recursive: true})
  // one folder, two UI extensions
  writeFileSync(
    join(extension, 'shopify.extension.toml'),
    `api_version = "2026-01"

[[extensions]]
type = "ui_extension"
name = "First block"
handle = "first-block"

  [[extensions.targeting]]
  module = "./src/first.js"
  target = "admin.order-details.block.render"

[[extensions]]
type = "ui_extension"
name = "Second block"
handle = "second-block"

  [[extensions.targeting]]
  module = "./src/second.js"
  target = "admin.customer-details.block.render"
`,
  )
  writeFileSync(join(extension, 'src', 'first.js'), 'export default async () => {}\n')
  writeFileSync(join(extension, 'src', 'second.js'), 'export default async () => {}\n')
  return dir
}

test(
  'two UI extensions in one folder deploy without racing on their shared dist/',
  async () => {
    const failures: string[] = []

    for (let index = 0; index < iterations; index++) {
      const directory = createApp()
      const {app} = await localAppContext({directory, userProvidedConfigName: 'shopify.app.toml', skipPrompts: true})

      if (SKEW_MS > 0) {
        const late = app.allExtensions.find((extension) => extension.handle === 'second-block')!
        const buildForBundle = late.buildForBundle.bind(late)
        late.buildForBundle = async (options, bundleDirectory) => {
          await new Promise((resolve) => setTimeout(resolve, SKEW_MS))
          return buildForBundle(options, bundleDirectory)
        }
      }

      try {
        // what `shopify app deploy` runs before it uploads
        // eslint-disable-next-line no-await-in-loop
        await bundleAndBuildExtensions({
          app,
          appManifest: await app.manifest(undefined),
          bundlePath: join(directory, '.shopify', 'deploy-bundle.zip'),
          skipBuild: false,
        })
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
      } catch (error: any) {
        failures.push(String(error?.message ?? error).replace(directory, '<app>'))
        // the real CLI exits here; let the other extension's build settle before the next round
        // eslint-disable-next-line no-await-in-loop
        await new Promise((resolve) => setTimeout(resolve, 3000))
      }
      rmSync(directory, {recursive: true, force: true})
    }

    expect(failures, `${failures.length} of ${iterations} deploys failed`).toEqual([])
  },
  3_600_000,
)