Fix CLI watcher cleanup race

[philipp-spiess]

This PR supersets #18559 and fixes the same issue reported by @Gazler.

Upon testing, we noticed that it's possible that two parallel invocations of file system change events could cause some cleanup functions to get swallowed.

This happens because we only remember one global cleanup function but it is possible timing wise that two calls to createWatcher() are created before the old watchers are cleaned and thus only one of the new cleanup functions get retained.

To fix this, this PR changes cleanupWatchers to an array and ensures that all functions are retained.

In some local testing, I was able to trigger this, based on the reproduction by @Gazler in #18559, to often call a cleanup with more than one cleanup function in the array.

I'm going to paste the amazing reproduction from #18559 here as well:

Requirements

We need a way to stress the CPU to slow down tailwind compilation, for example stress-ng.

stress-ng --cpu 16 --timeout 10

It can be install with apt, homebrew or similar.

Installation

There is a one-liner at the bottom to perform the required setup and run the tailwindcli.

Create a new directory:

mkdir twtest && cd twtest

Create a package.json with the correct deps.

cat << 'EOF' > package.json
{
  "dependencies": {
    "@tailwindcss/cli": "^4.1.11",
    "daisyui": "^5.0.46",
    "tailwindcss": "^4.1.11"
  }
}
EOF

Create the input css:

mkdir src
cat << 'EOF' > src/.input.css
@import "tailwindcss" source(none);
@plugin "daisyui";
@source "../core_components.ex";
@source "../home.html.heex";
@source "./input.css";

EOF

Install tailwind, daisyui, and some HTML to make tailwind do some work:

npm install
wget https://raw.githubusercontent.com/phoenixframework/phoenix/refs/heads/main/installer/templates/phx_web/components/core_components.ex
wget https://github.com/phoenixframework/phoenix/blob/main/installer/templates/phx_web/controllers/page_html/home.html.heex

Usage

This is easiest with 3 terminal windows:

Start a tailwindcli watcher in one terminal:

npx @tailwindcss/cli -i src/input.css -o src/output.css --watch

Start a stress test in another:

stress-ng --cpu 16 --timeout 30

Force repeated compilation in another:

for i in $(seq 1 50); do touch src/input.css; sleep 0.1; done

Result

Once the stress test has completed, you can run:

touch src/input.css

You should see that there is repeated output, and the duration is in the multiple seconds.

If this setup doesn't cause the issue, you can also add the -p flag which causes the
CSS to be printed, slowing things down further:

npx @tailwindcss/cli -i src/input.css -p --watch

One-liner

mkdir twtest && cd twtest
cat << 'EOF' > package.json
{
  "dependencies": {
    "@tailwindcss/cli": "^4.1.11",
    "daisyui": "^5.0.46",
    "tailwindcss": "^4.1.11"
  }
}
EOF

mkdir src
cat << 'EOF' > src/input.css
@import "tailwindcss" source(none);
@plugin "daisyui";
@source "../core_components.ex";
@source "../home.html.heex";
@source "./input.css";

EOF

npm install
wget https://raw.githubusercontent.com/phoenixframework/phoenix/refs/heads/main/installer/templates/phx_web/components/core_components.ex
wget https://github.com/phoenixframework/phoenix/blob/main/installer/templates/phx_web/controllers/page_html/home.html.heex
npx @tailwindcss/cli -i src/input.css -o src/output.css --watch

Test plan

• Not able to reproduce this with a local build of the CLI after the patch is applied but was able to reproduce it again once the patch was reverted.

[Gazler]

I like this solution, my PR was mainly about reproducing the issue, which is why I marked it as a draft. 👍

[RobinMalfait]

I am not able to reproduce this issue on my M1 Max and tried a few things. E.g.:

Tab 1: start watcher
Tab 2: touch the input.css file for 500 times (for i in $(seq 1 500); do touch src/input.css; sleep 0.1; done)
Tab 3: once tab 2 is running, start stress-ng --cpu 16 --timeout 30

You can see when I turn on the stress test:

... and you can see when I turn it off again:

I tried it a dozen times now and can't get it to reproduce.

However, while on call with @philipp-spiess, we pushed the cleanup functions into an array, and as a sanity check we did some additional logging when the array got 2 or more items. Lo and behold, there were 2 items at one point meaning that in the previous implementation we would've overwritten a cleanup function that wasn't called yet.

Going to approve this, because @philipp-spiess can't reproduce it with the new code either, and it still works as expected on my machine with the fix.