fix(watch): handle Ctrl+C in MultiWatchProcessManager without signal handlers

signal.signal() raises ValueError when called from a worker thread, so
multi-entry watch crashed under Django's autoreloader. Drop the handlers
and rely on KeyboardInterrupt + finally cleanup, matching the single-
entry path. Closes #201.

Author: oliverandrich

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### 🐛 Bug Fixes
+- **`tailwind watch` crash with `TAILWIND_CLI_CSS_MAP`**: `MultiWatchProcessManager` installed `signal.signal` handlers that fail with `ValueError: signal only works in main thread of the main interpreter` under Django's autoreloader (the watch loop runs in a worker thread). Cleanup now relies on `KeyboardInterrupt` propagation, matching the single-entry path. Fixes [#201](https://github.com/django-commons/django-tailwind-cli/issues/201).
+
 ### 🔧 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

@@ -1130,10 +1130,9 @@ def start_watch_processes(self, config: Config, *, verbose: bool = False) -> Non
             config: Configuration object with css_entries.
             verbose: Whether to show detailed information.
         """
-        # Set up signal handlers for graceful shutdown
-        signal.signal(signal.SIGINT, self._signal_handler)
-        signal.signal(signal.SIGTERM, self._signal_handler)
-
+        # Rely on KeyboardInterrupt rather than signal.signal() so this works
+        # under Django's autoreloader, which runs the watch loop in a worker
+        # thread where signal.signal() raises ValueError.
         try:
             for entry in config.css_entries:
                 watch_cmd = config.get_watch_cmd(entry)
@@ -1153,19 +1152,17 @@ def start_watch_processes(self, config: Config, *, verbose: bool = False) -> Non
                 typer.secho(f"Watching '{entry.name}': {entry.src_css}", fg=typer.colors.GREEN)
 
             self._monitor_processes()
+        except KeyboardInterrupt:
+            typer.secho("\nShutdown signal received, stopping watch processes...", fg=typer.colors.YELLOW)
+            self.shutdown_requested = True
         except Exception as e:
             typer.secho(f"Error starting watch processes: {e}", fg=typer.colors.RED)
-            self._cleanup_processes()
             raise
-
-    def _signal_handler(self, _signum: int, _frame: FrameType | None) -> None:
-        """Handle shutdown signals gracefully."""
-        typer.secho("\nShutdown signal received, stopping watch processes...", fg=typer.colors.YELLOW)
-        self.shutdown_requested = True
-        self._cleanup_processes()
+        finally:
+            self._cleanup_processes()
 
     def _monitor_processes(self) -> None:
-        """Monitor all watch processes."""
+        """Monitor all watch processes. Cleanup is owned by start_watch_processes' finally."""
         while not self.shutdown_requested and any(p.poll() is None for p in self.processes):
             time.sleep(0.5)
 
@@ -1175,8 +1172,6 @@ def _monitor_processes(self) -> None:
                     self.shutdown_requested = True
                     break
 
-        self._cleanup_processes()
-
     def _cleanup_processes(self) -> None:
         """Clean up all watch processes."""
         for process in self.processes:

tests/test_integration.py

@@ -7,6 +7,7 @@
 
 import os
 import platform
+import threading
 import time
 from pathlib import Path
 from collections.abc import Callable
@@ -25,6 +26,7 @@
     DAISY_UI_SOURCE_CSS,
     DEFAULT_SOURCE_CSS,
     ProcessManager,
+    _run_watch_loop,
 )
 
 
@@ -33,6 +35,13 @@ def _call_directly(func: Any, *args: Any, **kwargs: Any) -> Any:
     return func(*args, **kwargs)
 
 
+def _clear_legacy_css_settings(settings: LazySettings) -> None:
+    """Drop single-file CSS settings so CSS_MAP is the sole source of truth."""
+    for name in ("TAILWIND_CLI_SRC_CSS", "TAILWIND_CLI_DIST_CSS"):
+        if hasattr(settings, name):
+            delattr(settings, name)
+
+
 class TestBuildWorkflowIntegration:
     """Test complete build workflow from setup to CSS generation."""
 
@@ -197,11 +206,7 @@ def test_build_with_multiple_css_entries(self, settings: LazySettings, tmp_path:
             ("admin.css", "admin.output.css"),
             ("web.css", "web.output.css"),
         ]
-        # Remove single-file settings to avoid conflict
-        if hasattr(settings, "TAILWIND_CLI_SRC_CSS"):
-            delattr(settings, "TAILWIND_CLI_SRC_CSS")
-        if hasattr(settings, "TAILWIND_CLI_DIST_CSS"):
-            delattr(settings, "TAILWIND_CLI_DIST_CSS")
+        _clear_legacy_css_settings(settings)
 
         # Create source CSS files
         (tmp_path / "admin.css").write_text('@import "tailwindcss";')
@@ -308,11 +313,7 @@ def test_watch_with_multiple_css_entries(self, settings: LazySettings, tmp_path:
             ("admin.css", "admin.output.css"),
             ("web.css", "web.output.css"),
         ]
-        # Remove single-file settings to avoid conflict
-        if hasattr(settings, "TAILWIND_CLI_SRC_CSS"):
-            delattr(settings, "TAILWIND_CLI_SRC_CSS")
-        if hasattr(settings, "TAILWIND_CLI_DIST_CSS"):
-            delattr(settings, "TAILWIND_CLI_DIST_CSS")
+        _clear_legacy_css_settings(settings)
 
         # Create source CSS files
         (tmp_path / "admin.css").write_text('@import "tailwindcss";')
@@ -361,6 +362,63 @@ def mock_download_func(
             assert "web.output.css" in str(call_args_1)
             assert "--watch" in call_args_1
 
+    def test_watch_with_css_map_runs_in_worker_thread(self, settings: LazySettings, tmp_path: Path):
+        """Regression for #201: multi-entry watch must work outside the main thread.
+
+        Django's autoreload.run_with_reloader executes the wrapped callable
+        in a worker thread. signal.signal() raises ValueError there, so the
+        multi-entry watch path must not rely on signal handlers.
+        """
+        settings.BASE_DIR = tmp_path
+        settings.TAILWIND_CLI_PATH = tmp_path / ".django_tailwind_cli"
+        settings.STATICFILES_DIRS = (tmp_path / "assets",)
+        settings.TAILWIND_CLI_VERSION = "4.1.3"
+        settings.TAILWIND_CLI_CSS_MAP = [
+            ("admin.css", "admin.output.css"),
+            ("web.css", "web.output.css"),
+        ]
+        _clear_legacy_css_settings(settings)
+
+        (tmp_path / "admin.css").write_text('@import "tailwindcss";')
+        (tmp_path / "web.css").write_text('@import "tailwindcss";')
+
+        with (
+            patch("django_tailwind_cli.utils.http.download_with_progress") as mock_download,
+            patch("subprocess.Popen") as mock_popen,
+        ):
+
+            def mock_download_func(
+                url: str,
+                filepath: Path,
+                timeout: int = 30,
+                progress_callback: Callable[[int, int, float], None] | None = None,
+            ) -> None:
+                filepath.parent.mkdir(parents=True, exist_ok=True)
+                filepath.write_bytes(b"fake-cli-binary")
+                filepath.chmod(0o755)
+
+            mock_download.side_effect = 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_popen.return_value = mock_process
+
+            errors: list[BaseException] = []
+
+            def runner() -> None:
+                try:
+                    _run_watch_loop(verbose=False)
+                except BaseException as exc:
+                    errors.append(exc)
+
+            worker = threading.Thread(target=runner)
+            worker.start()
+            worker.join(timeout=5)
+
+            assert not worker.is_alive(), "_run_watch_loop did not terminate within 5s"
+            assert not errors, f"_run_watch_loop crashed in worker thread: {errors[0]!r}"
+
     def test_watch_keyboard_interrupt_handling(
         self, settings: LazySettings, tmp_path: Path, capsys: CaptureFixture[str]
     ):