feat(watch): filter Bun native-runtime noise from watcher stderr

The Bun-built tailwindcss standalone binary occasionally leaks
unhandled native-module crash traces (EIO on shutdown, ERR_DLOPEN_FAILED
on the rare DLOPEN race). Capture stderr per watcher and run a daemon
thread that drops the upstream noise while forwarding Tailwind's own
diagnostics verbatim. Cleanup output stays clean even when users
kill -TERM the runserver.

Author: oliverandrich

CHANGELOG.md

@@ -7,6 +7,9 @@
 - **SIGTERM-graceful shutdown for both watch managers**: `ProcessManager` and `MultiWatchProcessManager` now install a SIGTERM handler only when running on the main thread, so `kill -TERM` cleans up child watchers in `tailwind watch --noreload` and `tailwind runserver` without re-introducing the autoreloader crash. SIGINT keeps using Python's default handler (which raises `KeyboardInterrupt`).
 - **Sidestepped a Bun DLOPEN race in multi-entry watch**: `MultiWatchProcessManager` now staggers successive watcher subprocess spawns by 300 ms. The Bun-built tailwindcss standalone binary extracts its embedded `@parcel/watcher` native module to `/$bunfs/` on first use; two parallel processes raced on that path and the loser crashed with `ERR_DLOPEN_FAILED`. The 300 ms gap is below noticeable in interactive use.
 
+### 🛠️ Developer Experience
+- **Filtered Bun native-runtime noise from watcher stderr**: `MultiWatchProcessManager` captures each `tailwindcss` subprocess' stderr and drops upstream Bun stack traces (`EIO: i/o error` on shutdown, `ERR_DLOPEN_FAILED` on the rare DLOPEN race) while forwarding Tailwind's own diagnostics verbatim. Cleanup output stays clean even when the user `kill -TERM`s the runserver.
+
 ### 🔧 Technical Improvements
 - **Hardened GitHub Actions workflows**: pinned all actions to commit SHAs, scoped top-level permissions, added concurrency groups, moved `github.ref_name` / `github.repository` out of shell interpolation into `env:` vars, and added a [zizmor](https://docs.zizmor.sh/) audit job to keep workflow security regressions out of CI.
 

src/django_tailwind_cli/management/commands/tailwind.py

@@ -3,14 +3,15 @@
 import importlib.util
 import functools
 import os
+import re
 import signal
 import subprocess
 import sys
 import threading
 import time
 from pathlib import Path
 from types import FrameType
-from typing import Any
+from typing import IO, Any
 from collections.abc import Callable
 
 from django_tailwind_cli.utils import http
@@ -51,6 +52,44 @@
 # without being noticeable in interactive use.
 _WATCH_SPAWN_STAGGER_S = 0.3
 
+# Bun-built tailwindcss occasionally leaks unhandled native-module errors
+# (DLOPEN race on startup, EIO on shutdown when its watch FD is closed under
+# it). The traces are upstream noise — neither actionable nor caused by
+# user code. We drop matching lines from forwarded stderr while keeping
+# Tailwind's own diagnostics intact.
+_BUN_NOISE = re.compile(
+    r"""
+    ^EIO:\ i/o\ error          |   # EIO header
+    ^Bun\ v\d                  |   # crash footer
+    ^error:\ dlopen\(          |   # DLOPEN header
+    ^\d+\ ?\|                  |   # numbered source-context line
+    ^\s+(?:fd|syscall|errno|code):  |   # error-detail field
+    ^\s+at\ <anonymous>\ \(/\$bunfs/   |   # bunfs stack frame
+    ^\s+\^\s*$                 |   # caret pointer
+    ^\s+code:\s*"(?:EIO|ERR_DLOPEN_FAILED)"   # error-code value
+    """,
+    re.VERBOSE,
+)
+
+
+def _is_bun_noise(line: str) -> bool:
+    """Return True if the line looks like a Bun native-runtime crash trace."""
+    return bool(_BUN_NOISE.match(line))
+
+
+def _drain_filtered_stderr(stream: IO[str], is_shutting_down: Callable[[], bool]) -> None:
+    """Forward subprocess stderr to the parent's stderr, dropping Bun noise.
+
+    Runs in a daemon thread until the subprocess closes the pipe. Drops every
+    line once `is_shutting_down()` returns True — post-shutdown stderr is not
+    actionable and just churns output during cleanup.
+    """
+    for line in stream:
+        if is_shutting_down() or _is_bun_noise(line):
+            continue
+        sys.stderr.write(line)
+        sys.stderr.flush()
+
 
 # DECORATORS AND COMMON SETUP ---------------------------------------------------------------------
 
@@ -1166,15 +1205,25 @@ def start_watch_processes(self, config: Config, *, verbose: bool = False) -> Non
                     typer.secho(f"🚀 Starting watch for '{entry.name}'...", fg=typer.colors.CYAN)
                     typer.secho(f"   • Command: {' '.join(watch_cmd)}", fg=typer.colors.BLUE)
 
-                # Inherit stdout/stderr so output flows to the terminal and we
-                # avoid a pipe-fill deadlock — the OS pipe buffer would otherwise
-                # block the watcher after ~64 KB of rebuild status lines.
+                # Inherit stdout (high-volume rebuild progress) to avoid a pipe-fill
+                # deadlock — the OS pipe buffer would otherwise block the watcher
+                # after ~64 KB. stderr is captured so we can filter Bun's native-
+                # runtime noise (DLOPEN race, EIO on shutdown) before it hits the
+                # terminal; volume there is low enough that the drain thread keeps
+                # up easily.
                 process = subprocess.Popen(
                     watch_cmd,
                     cwd=settings.BASE_DIR,
                     text=True,
+                    stderr=subprocess.PIPE,
                 )
                 self.processes.append(process)
+                if process.stderr is not None:
+                    threading.Thread(
+                        target=_drain_filtered_stderr,
+                        args=(process.stderr, lambda: self.shutdown_requested),
+                        daemon=True,
+                    ).start()
                 typer.secho(f"Watching '{entry.name}': {entry.src_css}", fg=typer.colors.GREEN)
 
             self._monitor_processes()

tests/test_integration.py

@@ -5,6 +5,7 @@
 """
 # pyright: reportPrivateUsage=false
 
+import io
 import os
 import platform
 import signal
@@ -29,6 +30,8 @@
     _WATCH_SPAWN_STAGGER_S,
     MultiWatchProcessManager,
     ProcessManager,
+    _drain_filtered_stderr,
+    _is_bun_noise,
     _run_watch_loop,
 )
 
@@ -343,6 +346,7 @@ def mock_download_func(
             mock_process = Mock()
             mock_process.poll.return_value = 0  # Process already exited
             mock_process.wait.return_value = 0
+            mock_process.stderr = None  # skip the stderr drain thread
             mock_popen.return_value = mock_process
 
             call_command("tailwind", "watch")
@@ -405,6 +409,7 @@ def mock_download_func(
             mock_process = Mock()
             mock_process.poll.return_value = 0  # already exited → monitor loop returns immediately
             mock_process.wait.return_value = 0
+            mock_process.stderr = None  # skip the stderr drain thread
             mock_popen.return_value = mock_process
 
             errors: list[BaseException] = []
@@ -460,6 +465,7 @@ def mock_download_func(
         mock_process = Mock()
         mock_process.poll.return_value = 0  # exits immediately so monitor loop returns
         mock_process.wait.return_value = 0
+        mock_process.stderr = None  # skip the stderr drain thread
         mock_popen = mocker.patch("subprocess.Popen", return_value=mock_process)
 
         # Patch only the time reference inside tailwind.py to avoid disturbing
@@ -587,6 +593,70 @@ def test_signal_handler_is_idempotent(self, manager_cls: type, capsys: CaptureFi
         assert manager.shutdown_requested is True
 
 
+class TestBunStderrFilter:
+    """Pattern-match and drain logic for filtering Bun native-runtime crash traces."""
+
+    @pytest.mark.parametrize(
+        "line",
+        [
+            "EIO: i/o error, read\n",
+            "      fd: 7,\n",
+            ' syscall: "read",\n',
+            "   errno: -5,\n",
+            '    code: "EIO"\n',
+            "Bun v1.2.8 (macOS arm64)\n",
+            "error: dlopen(/$bunfs/root/watcher-tzt47keb.node, 0x0001): tried...\n",
+            "      at <anonymous> (/$bunfs/root/tailwindcss-macos-arm64:22717:29)\n",
+            '    code: "ERR_DLOPEN_FAILED"\n',
+            "22716 |   module.exports = __require(...);\n",
+            "                                    ^\n",
+        ],
+    )
+    def test_is_bun_noise_drops_known_patterns(self, line: str):
+        assert _is_bun_noise(line) is True
+
+    @pytest.mark.parametrize(
+        "line",
+        [
+            "≈ tailwindcss v4.1.3\n",
+            "Done in 32ms\n",
+            '[ERROR] Could not resolve "tailwindcss"\n',
+            "Watching 'admin': /path/to/admin.css\n",
+            "warn - Cannot find module './foo'\n",
+            "\n",  # blank line — drained but not filtered
+        ],
+    )
+    def test_is_bun_noise_keeps_legitimate_lines(self, line: str):
+        assert _is_bun_noise(line) is False
+
+    def test_drain_filtered_stderr_drops_bun_noise(self, capsys: CaptureFixture[str]):
+        stream = io.StringIO(
+            "Done in 32ms\n"
+            "EIO: i/o error, read\n"
+            "      fd: 7,\n"
+            "Bun v1.2.8 (macOS arm64)\n"
+            '[ERROR] Could not resolve "tailwindcss"\n'
+        )
+
+        _drain_filtered_stderr(stream, lambda: False)
+
+        err = capsys.readouterr().err
+        assert "Done in 32ms" in err
+        assert "[ERROR] Could not resolve" in err
+        assert "EIO" not in err
+        assert "Bun v" not in err
+        assert "fd: 7" not in err
+
+    def test_drain_filtered_stderr_drops_everything_after_shutdown(self, capsys: CaptureFixture[str]):
+        """Post-shutdown stderr is just churn from terminating subprocesses; drop it."""
+        stream = io.StringIO("Done in 32ms\n[ERROR] something legit\n")
+
+        _drain_filtered_stderr(stream, lambda: True)
+
+        err = capsys.readouterr().err
+        assert err == ""
+
+
 class TestCLIDownloadIntegration:
     """Test CLI download and setup workflows."""