[wrangler] Serialize custom build watcher events to avoid concurrent runs - #14936

Fixes #10944.

Supersedes #12704 — that PR had gone stale and the code it touched was rewritten by #14462 and #14561 in the meantime, so this is a re-implementation on top of current main. Credit to @dhruv7539 for the original fix and the approach, retained via Co-authored-by.

The bug

When several watched files changed at once — a git pull, a "save all", a framework writing out a directory — wrangler dev started a custom build for every watcher event. Multiple copies of the user's build command ran at the same time and fought over the same output files.

Since #14462 a superseded build is sent SIGTERM, but tree-kill walks the process tree asynchronously while the replacement build is spawned immediately, so builds still overlap. A long burst also produces a stream of start/kill churn.

The fix

• Custom builds triggered by the watcher are debounced (100ms), so a burst of events results in one build rather than a build per event that is immediately superseded by the next.
• Builds are queued and run one at a time, keeping only the most recent request. A build only starts once the previous one has exited.
• This makes the #activeCustomBuilds set from [wrangler] Abort custom builds on dev teardown #14462 redundant — there is now at most one build in flight by construction, tracked by the promise for the queue-draining loop.
• A queued build is dropped if its abort signal has already fired, so a build scheduled against a replaced config never runs its command.

Related fixes while in here

These share a root cause with the above: watchers deliver events while they are closing, and DevEnv tears its controllers down concurrently, so work could be started after dev had already moved on. Controller already tracks teardown state for suppressing error events, so it's now exposed as a protected getter and checked at each entry point.

• Custom builds could run after dev shut down. A build scheduled in that window gets a fresh AbortController, so the aborted-signal guard above can't catch it, and it would spawn the user's build command and dispatch bundle events into a torn-down environment. (Reported by Devin on this PR.)
• The assets watcher's debounced bundle refresh was never cancelled. A pending refresh could dispatch bundleComplete into a torn-down bus, or report a bundle against a config a reload had just replaced, and its timer could delay the process exiting.
• onConfigUpdate() had no teardown check at all. ConfigController can dispatch a config-file change delivered while its own watcher was closing, so an update could reach the bundler after its teardown had finished. That created chokidar watchers that are never closed, an esbuild watch build whose cleanup callback is never invoked, and a temp directory — plus its process exit listener — that is never removed. Any of these can keep the node process alive after dev has stopped.

debounce() gains a cancel() method for the two debounced paths, called once the relevant watcher has closed so a late event can't re-arm the timer.

Also fixes an unrelated one-line bug in the same function that the original PR spotted: the custom build path passed the configured jsx_factory to esbuild as the JSX fragment factory, so projects setting both jsx_factory and jsx_fragment got the wrong fragment pragma. Separate changeset.

Testing notes

Every new test was checked to fail without its corresponding fix — a couple of earlier drafts passed either way and were rewritten.

• Concurrency: drives the real chokidar watcher and a real build command. The command records its pid in a lock file and reports an overlap only if the recorded pid is still alive — a liveness check rather than a bare existsSync, because a superseded build is killed and leaves its lock behind. Fails pre-fix with overlap.txt written (genuinely concurrent builds) and expected 5 to be less than 5 (no coalescing).
• Teardown: the assets tests drive the watcher through the existing chokidar mock, which makes arming the debounce deterministic rather than dependent on filesystem event timing. The EMFILE test file already had that mock, so it's been renamed to cover assets watcher behaviour generally.
• Post-teardown config updates: covered for all three paths (watched custom build, unwatched custom build, plain esbuild). The leaked .wrangler/tmp/dev-* directory is the signal that makes each case fail without the guard.
• debounce()'s coalescing and cancel() are unit tested with fake timers.

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s):
  • Documentation not necessary because: this fixes incorrect wrangler dev behaviour with no change to the configuration or API surface. Custom builds and jsx_fragment are already documented.

A picture of a cute animal (not mandatory, but encouraged)