refactor(runserver): replace hand-copied options with typer passthrough

`tailwind runserver` used to declare every runserver / runserver_plus
flag as its own typer.Option and ship a translation helper to turn them
back into argv — two sources of truth that had already drifted (the
wrapper was missing ~7 runserver_plus flags including --extra-file,
--reloader-interval and --browser).

Use Click's `ignore_unknown_options` + `allow_extra_args` so only
`--force-default-runserver` is caught by typer; every other positional
and flag falls into `ctx.args` and is forwarded verbatim to the
subprocess. Argument parsing goes back to Django where it belongs.

Trade-off: `tailwind runserver --help` no longer lists the upstream
flags — the docstring now points at `runserver --help` /
`runserver_plus --help` for the authoritative list.

Author: oliverandrich

CHANGELOG.md

@@ -22,6 +22,7 @@
 - **Type checking**: Switched from `pyright` to `basedpyright` in pre-commit, added `django-stubs` as a dev dependency, and resolved a latent pre-existing baseline so the type checker runs clean on all files.
 - **Pre-commit hooks**: Bumped all hooks to their latest releases (pre-commit-hooks 6.0.0, ruff 0.15.10, pyupgrade 3.21.2, django-upgrade 1.30.0, djade 1.9.0, uv-secure 0.17.1).
 - **Test coverage**: Raised `config.py` to 100% and `http.py` from 67% to 100%, covering the previously-untested download body (chunked writes with progress callbacks), 200/redirect responses, HTTP 4xx/5xx paths, generic `URLError` branches, and the `NoRedirectHandler` redirect methods.
+- **`tailwind runserver` is now a transparent passthrough wrapper**. Instead of declaring every `runserver` / `runserver_plus` flag by hand, the command forwards all unknown options to the underlying Django command. This removes ~120 lines of duplication, fixes the silent gap where several `runserver_plus` flags (`--extra-file`, `--reloader-interval`, `--browser`, …) were not exposed, and stays in sync with future upstream changes automatically. Existing invocations keep working unchanged; the reduced output of `tailwind runserver --help` now points users at `runserver --help` for the full flag list.
 
 ## 4.5.1 (2025-12-29)
 

docs/usage.md

@@ -32,54 +32,32 @@ python manage.py tailwind watch --noreload
 
 ### runserver
 
-Run `python manage.py tailwind runserver` to start the classic Django debug server in parallel to a tailwind watcher process.
-
-```text
-Usage: manage.py tailwind runserver
-           [OPTIONS] [ADDRPORT]
-
-  Run the development server with Tailwind CSS CLI in watch mode.
-
-  If django-extensions is installed along with this library, this command runs
-  the runserver_plus command from django-extensions. Otherwise it runs the
-  default runserver command.
-
-Arguments:
-  [ADDRPORT]  Optional port number, or ipaddr:port
-
-Options:
-  -6, --ipv6                      Tells Django to use an IPv6 address.
-  --nothreading                   Tells Django to NOT use threading.
-  --nostatic                      Tells Django to NOT automatically serve
-                                  static files at STATIC_URL.
-  --noreload                      Tells Django to NOT use the auto-reloader.
-  --skip-checks                   Skip system checks.
-  --pdb                           Drop into pdb shell at the start of any
-                                  view. (Requires django-extensions.)
-  --ipdb                          Drop into ipdb shell at the start of any
-                                  view. (Requires django-extensions.)
-  --pm                            Drop into (i)pdb shell if an exception is
-                                  raised in a view. (Requires django-
-                                  extensions.)
-  --print-sql                     Print SQL queries as they're executed.
-                                  (Requires django-extensions.)
-  --print-sql-location            Show location in code where SQL query
-                                  generated from. (Requires django-
-                                  extensions.)
-  --cert-file TEXT                SSL .crt file path. If not provided path
-                                  from --key-file will be selected. Either
-                                  --cert-file or --key-file must be provided
-                                  to use SSL. (Requires django-extensions.)
-  --key-file TEXT                 SSL .key file path. If not provided path
-                                  from --cert-file will be selected. Either
-                                  --cert-file or --key-file must be provided
-                                  to use SSL. (Requires django-extensions.)
-  --force-default-runserver / --no-force-default-runserver
-                                  Force the use of the default runserver
-                                  command even if django-extensions is
-                                  installed.   [default: no-force-default-
-                                  runserver]
-  --help                          Show this message and exit.
+Run `python manage.py tailwind runserver` to start the Django debug server in parallel to a tailwind watcher process. If `django-extensions` plus `werkzeug` are installed, `runserver_plus` is used automatically; otherwise the vanilla `runserver` command runs.
+
+This command is a transparent passthrough wrapper: **every** positional argument and option other than the tailwind-specific `--force-default-runserver` is forwarded verbatim to the underlying server command. That includes flags the wrapper itself does not know about (e.g. `runserver_plus`'s `--extra-file`, `--reloader-interval`, `--browser`, `--exclude-pattern`, …).
+
+For the exhaustive list of forwarded flags, run:
+
+```bash
+python manage.py runserver --help
+python manage.py runserver_plus --help   # with django-extensions
+```
+
+Examples:
+
+```bash
+# Default port (8000)
+python manage.py tailwind runserver
+
+# Custom port
+python manage.py tailwind runserver 8080
+
+# Forward arbitrary runserver / runserver_plus flags
+python manage.py tailwind runserver 0.0.0.0:8000 --noreload
+python manage.py tailwind runserver --print-sql --ipdb
+
+# Pin to vanilla runserver even with django-extensions installed
+python manage.py tailwind runserver --force-default-runserver
 ```
 
 ### download_cli

src/django_tailwind_cli/management/commands/tailwind.py

@@ -968,162 +968,57 @@ def remove_cli():
         typer.secho(f"Tailwind CSS CLI not found at '{c.cli_path}'.", fg=typer.colors.RED)
 
 
-@app.command()
+@app.command(
+    context_settings={
+        "ignore_unknown_options": True,
+        "allow_extra_args": True,
+    },
+)
 def runserver(
-    addrport: str | None = typer.Argument(
-        None,
-        help="Optional port number, or ipaddr:port",
-    ),
+    ctx: typer.Context,
     *,
-    use_ipv6: bool = typer.Option(
-        False,
-        "--ipv6",
-        "-6",
-        help="Tells Django to use an IPv6 address.",
-    ),
-    no_threading: bool = typer.Option(
-        False,
-        "--nothreading",
-        help="Tells Django to NOT use threading.",
-    ),
-    no_static: bool = typer.Option(
-        False,
-        "--nostatic",
-        help="Tells Django to NOT automatically serve static files at STATIC_URL.",
-    ),
-    no_reloader: bool = typer.Option(
-        False,
-        "--noreload",
-        help="Tells Django to NOT use the auto-reloader.",
-    ),
-    skip_checks: bool = typer.Option(
-        False,
-        "--skip-checks",
-        help="Skip system checks.",
-    ),
-    pdb: bool = typer.Option(
-        False,
-        "--pdb",
-        help="Drop into pdb shell at the start of any view. (Requires django-extensions.)",
-    ),
-    ipdb: bool = typer.Option(
-        False,
-        "--ipdb",
-        help="Drop into ipdb shell at the start of any view. (Requires django-extensions.)",
-    ),
-    pm: bool = typer.Option(
-        False,
-        "--pm",
-        help="Drop into (i)pdb shell if an exception is raised in a view. (Requires django-extensions.)",
-    ),
-    print_sql: bool = typer.Option(
-        False,
-        "--print-sql",
-        help="Print SQL queries as they're executed. (Requires django-extensions.)",
-    ),
-    print_sql_location: bool = typer.Option(
-        False,
-        "--print-sql-location",
-        help="Show location in code where SQL query generated from. (Requires django-extensions.)",
-    ),
-    cert_file: str | None = typer.Option(
-        None,
-        help=(
-            "SSL .crt file path. If not provided path from --key-file will be selected. "
-            "Either --cert-file or --key-file must be provided to use SSL. "
-            "(Requires django-extensions.)"
-        ),
-    ),
-    key_file: str | None = typer.Option(
-        None,
-        help=(
-            "SSL .key file path. If not provided path from --cert-file will be "
-            "selected. Either --cert-file or --key-file must be provided to use SSL. "
-            "(Requires django-extensions.)"
-        ),
-    ),
     force_default_runserver: bool = typer.Option(
         False,
-        help=("Force the use of the default runserver command even if django-extensions is installed. "),
+        help="Force vanilla runserver even if django-extensions is installed.",
     ),
 ):
     """Run Django development server with Tailwind CSS watch mode.
 
-    This command combines 'tailwind watch' and Django's runserver, providing a
-    complete development environment in a single terminal. It automatically:
-    - Starts Tailwind CSS in watch mode to rebuild styles on changes
-    - Runs Django's development server
-    - Manages both processes with proper signal handling
+    Combines `tailwind watch` and Django's runserver in one terminal, with
+    signal-clean shutdown of both processes on Ctrl+C. If `django-extensions`
+    plus `werkzeug` are installed, `runserver_plus` is used by default — pass
+    `--force-default-runserver` to opt out.
 
     \b
-    Features:
-    - Automatic process management (both stop cleanly with Ctrl+C)
-    - Live CSS updates as you edit templates and styles
-    - Support for django-extensions runserver_plus (if installed)
-    - All standard runserver options are supported
+    All positional arguments and options other than `--force-default-runserver`
+    are forwarded verbatim to the underlying server command. That means every
+    runserver / runserver_plus flag is supported, including ones this wrapper
+    does not know about:
 
     \b
-    Examples:
-        # Run on default port (8000)
         python manage.py tailwind runserver
-
-        # Run on custom port
         python manage.py tailwind runserver 8080
-
-        # Run on specific IP and port
-        python manage.py tailwind runserver 0.0.0.0:8000
-
-        # Run with django-extensions features
-        python manage.py tailwind runserver --print-sql
-
-        # Force default runserver (ignore django-extensions)
-        python manage.py tailwind runserver --force-default-runserver
+        python manage.py tailwind runserver 0.0.0.0:8000 --noreload
+        python manage.py tailwind runserver --print-sql --ipdb
+        python manage.py tailwind runserver --extra-file .env --reloader-interval 5
 
     \b
-    Tips:
-        - This replaces the need to run 'tailwind watch' and 'runserver' separately
-        - Both processes are managed together - Ctrl+C stops both cleanly
-        - Check console output for both Tailwind build status and Django logs
+    For the full list of forwarded flags, see:
+        python manage.py runserver --help
+        python manage.py runserver_plus --help   (with django-extensions)
     """
-    if (
+    use_plus = (
         importlib.util.find_spec("django_extensions")
         and importlib.util.find_spec("werkzeug")
         and not force_default_runserver
-    ):
-        server_command = "runserver_plus"
-        runserver_options = get_runserver_options(
-            addrport=addrport,
-            use_ipv6=use_ipv6,
-            no_threading=no_threading,
-            no_static=no_static,
-            no_reloader=no_reloader,
-            skip_checks=skip_checks,
-            pdb=pdb,
-            ipdb=ipdb,
-            pm=pm,
-            print_sql=print_sql,
-            print_sql_location=print_sql_location,
-            cert_file=cert_file,
-            key_file=key_file,
-        )
-    else:
-        server_command = "runserver"
-        runserver_options = get_runserver_options(
-            addrport=addrport,
-            use_ipv6=use_ipv6,
-            no_threading=no_threading,
-            no_static=no_static,
-            no_reloader=no_reloader,
-            skip_checks=skip_checks,
-        )
+    )
+    server_command = "runserver_plus" if use_plus else "runserver"
 
-    # Prepare commands for concurrent execution
     watch_cmd = [sys.executable, "manage.py", "tailwind", "watch"]
-    debug_server_cmd = [sys.executable, "manage.py", server_command] + runserver_options
+    server_cmd = [sys.executable, "manage.py", server_command, *ctx.args]
 
-    # Use improved process manager
     process_manager = ProcessManager()
-    process_manager.start_concurrent_processes(watch_cmd, debug_server_cmd)
+    process_manager.start_concurrent_processes(watch_cmd, server_cmd)
 
 
 # PROCESS MANAGEMENT FUNCTIONS -------------------------------------------------------------------
@@ -1714,51 +1609,3 @@ def _create_standard_config_with_verbose(*, verbose: bool = False) -> None:
         )
     elif verbose:
         typer.secho("⏭️  Source CSS file is up-to-date, no changes needed", fg=typer.colors.GREEN)
-
-
-def get_runserver_options(
-    *,
-    addrport: str | None = None,
-    use_ipv6: bool = False,
-    no_threading: bool = False,
-    no_static: bool = False,
-    no_reloader: bool = False,
-    skip_checks: bool = False,
-    pdb: bool = False,
-    ipdb: bool = False,
-    pm: bool = False,
-    print_sql: bool = False,
-    print_sql_location: bool = False,
-    cert_file: str | None = None,
-    key_file: str | None = None,
-) -> list[str]:
-    options: list[str] = []
-
-    if use_ipv6:
-        options.append("--ipv6")
-    if no_threading:
-        options.append("--nothreading")
-    if no_static:
-        options.append("--nostatic")
-    if no_reloader:
-        options.append("--noreload")
-    if skip_checks:
-        options.append("--skip-checks")
-    if pdb:
-        options.append("--pdb")
-    if ipdb:
-        options.append("--ipdb")
-    if pm:
-        options.append("--pm")
-    if print_sql:
-        options.append("--print-sql")
-    if print_sql_location:
-        options.append("--print-sql-location")
-    if cert_file:
-        options.append(f"--cert-file={cert_file}")
-    if key_file:
-        options.append(f"--key-file={key_file}")
-    if addrport:
-        options.append(addrport)
-
-    return options