feat(webui): add integrated Vite dev mode (#5239)

nanobot/cli/gateway_runtime.py

@@ -25,6 +25,7 @@ from nanobot.cli.webui_support import (
     _tcp_endpoint_reachable,
     _webui_browser_url,
     _webui_channel_enabled,
+    _webui_display_url,
     _webui_endpoint_reachable,
 )
 from nanobot.config.paths import is_default_workspace
@@ -34,6 +35,7 @@ from nanobot.session.keys import UNIFIED_SESSION_KEY, last_channel_from_metadata
 from nanobot.utils.evaluator import evaluate_response, resolve_evaluator_prompt
 from nanobot.utils.helpers import sync_workspace_templates
 from nanobot.webui.build import BuildMode
+from nanobot.webui.dev import WebUIDevError, WebUIDevServer
 from nanobot.webui.sidebar_state import read_webui_sidebar_state
 
 __all__ = ["_run_gateway"]
@@ -41,6 +43,34 @@ __all__ = ["_run_gateway"]
 console = Console()
 
 
+def _http_endpoint_responding(url: str, *, timeout_s: float = 0.25) -> bool:
+    """Return whether an HTTP endpoint responds, including with an auth error."""
+    import urllib.error
+    import urllib.request
+
+    try:
+        with urllib.request.urlopen(url, timeout=timeout_s):
+            return True
+    except urllib.error.HTTPError:
+        return True
+    except (OSError, urllib.error.URLError, TimeoutError, ValueError):
+        return False
+
+
+async def _watch_webui_dev_server(
+    server: WebUIDevServer,
+    shutdown_event: asyncio.Event,
+    *,
+    poll_interval_s: float = 0.2,
+) -> None:
+    """Fail the foreground gateway when its owned Vite sidecar exits."""
+    while not shutdown_event.is_set():
+        await asyncio.sleep(poll_interval_s)
+        if shutdown_event.is_set():
+            return
+        server.ensure_running()
+
+
 def _signal_name(signum: int) -> str:
     with suppress(ValueError):
         return signal.Signals(signum).name
@@ -258,12 +288,14 @@ def _run_gateway(
     *,
     port: int | None = None,
     open_browser_url: str | None = None,
+    open_browser_ready_url: str | None = None,
     webui_static_dist: bool = True,
     webui_bundle_mode: BuildMode = "warn",
     webui_runtime_surface: str = "browser",
     webui_runtime_capabilities: dict[str, Any] | None = None,
     health_server_enabled: bool = True,
     unconfigured_provider_error: str | None = None,
+    webui_dev_server: WebUIDevServer | None = None,
 ) -> None:
     """Shared gateway runtime; ``open_browser_url`` opens a tab once channels are up."""
     from nanobot.agent.model_presets import load_model_preset_catalog
@@ -760,10 +792,21 @@ def _run_gateway(
         import webbrowser
         from urllib.parse import urlparse
 
+        # Channels start asynchronously. When the caller supplies a backend
+        # readiness route, wait for an actual HTTP response rather than probing
+        # the WebSocket listener with an incomplete TCP connection.
+        if open_browser_ready_url:
+            for _ in range(40):  # ~4s max per listener
+                if await asyncio.to_thread(
+                    _http_endpoint_responding,
+                    open_browser_ready_url,
+                ):
+                    break
+                await asyncio.sleep(0.1)
+
         parsed = urlparse(open_browser_url)
         target_host = parsed.hostname or config.gateway.host or "127.0.0.1"
         target_port = parsed.port or port
-        # Channels start asynchronously; a short poll lets us avoid racing the bind.
         for _ in range(40):  # ~4s max
             try:
                 _reader, writer = await asyncio.open_connection(
@@ -776,11 +819,12 @@ def _run_gateway(
                 break
             except OSError:
                 await asyncio.sleep(0.1)
+        display_url = _webui_display_url(open_browser_url)
         try:
             webbrowser.open(open_browser_url)
-            console.print(f"[green]✓[/green] Opened browser at {open_browser_url}")
+            console.print(f"[green]✓[/green] Opened browser at {display_url}")
         except Exception as e:
-            console.print(f"[yellow]Could not open browser ({e}); visit {open_browser_url}[/yellow]")
+            console.print(f"[yellow]Could not open browser ({e}); visit {display_url}[/yellow]")
 
     async def run() -> None:
         tasks: list[asyncio.Task[Any]] = []
@@ -827,6 +871,11 @@ def _run_gateway(
                     _open_browser_when_ready(),
                     name="nanobot-open-browser",
                 ))
+            if webui_dev_server is not None:
+                tasks.append(asyncio.create_task(
+                    _watch_webui_dev_server(webui_dev_server, shutdown_event),
+                    name="nanobot-webui-dev-server",
+                ))
             runtime_tasks = asyncio.gather(*tasks)
             shutdown_task = asyncio.create_task(
                 shutdown_event.wait(),
@@ -842,6 +891,8 @@ def _run_gateway(
                 runtime_tasks.cancel()
         except KeyboardInterrupt:
             console.print("\nShutting down...")
+        except WebUIDevError:
+            raise
         except Exception:
             import traceback
 

nanobot/cli/webui.py

@@ -39,10 +39,39 @@ from nanobot.cli.webui_support import (
 )
 from nanobot.config.paths import get_workspace_path
 from nanobot.utils.helpers import sync_workspace_templates
+from nanobot.webui.dev import (
+    WebUIDevError,
+    WebUIDevServer,
+    run_webui_dev_server,
+    webui_dev_browser_url,
+    webui_dev_proxy_target,
+)
 
 console = Console()
 
 
+def _wait_with_existing_foreground_gateway(
+    gateway_host: str,
+    gateway_port: int,
+    dev_server: WebUIDevServer,
+) -> None:
+    """Keep a Vite sidecar alive without taking ownership of an external gateway."""
+    import time
+
+    console.print(
+        "[dim]Vite is attached to the existing foreground gateway. "
+        "Press Ctrl+C to stop Vite; the gateway will keep running.[/dim]"
+    )
+    try:
+        while True:
+            dev_server.ensure_running()
+            if not _gateway_health_ready(gateway_host, gateway_port):
+                break
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Stopping the WebUI dev server.[/yellow]")
+
+
 def webui(
     port: int | None = typer.Option(None, "--port", "-p", help="WebUI port"),
     gateway_port: int | None = typer.Option(
@@ -57,6 +86,11 @@ def webui(
         "--background",
         help="Keep the gateway running after this command exits",
     ),
+    dev: bool = typer.Option(
+        False,
+        "--dev",
+        help="Run the Vite development server with live frontend updates",
+    ),
     no_open: bool = typer.Option(False, "--no-open", help="Do not open a browser"),
     yes: bool = typer.Option(
         False,
@@ -70,6 +104,9 @@ def webui(
     from nanobot.gateway import GatewayRuntime, GatewayRuntimePaths, GatewayStartOptions
 
     cli_terminal._ensure_interactive_tty_mode()
+    if dev and background:
+        console.print("[red]Error: --dev cannot be combined with --background.[/red]")
+        raise typer.Exit(1)
     config_path = _resolve_webui_config_path(config)
     created_config = not config_path.exists()
     if created_config:
@@ -143,8 +180,13 @@ def webui(
     runtime_config = _load_runtime_config(str(config_path), workspace)
     effective_gateway_port = gateway_port if gateway_port is not None else runtime_config.gateway.port
 
+    dev_browser_url = webui_dev_browser_url(webui_url) if dev else None
     console.print()
-    console.print(f"WebUI: [cyan]{_webui_display_url(webui_url)}[/cyan]")
+    if dev_browser_url:
+        console.print(f"WebUI dev: [cyan]{_webui_display_url(dev_browser_url)}[/cyan]")
+        console.print(f"WebUI gateway: [cyan]{_webui_display_url(webui_url)}[/cyan]")
+    else:
+        console.print(f"WebUI: [cyan]{_webui_display_url(webui_url)}[/cyan]")
     gateway_health_url = _gateway_health_url(
         runtime_config.gateway.host,
         effective_gateway_port,
@@ -223,19 +265,45 @@ def webui(
     webui_ready = _webui_endpoint_reachable(webui_url)
     if gateway_ready and webui_ready:
         console.print("[yellow]Gateway is already running; attaching to the existing WebUI.[/yellow]")
-        console.print(
-            "Restart the gateway if you need it to pick up local source changes: "
-            f"[cyan]{_gateway_instance_command('restart', config_path=config_path, workspace=workspace)}[/cyan]"
-        )
-        if not no_open:
-            _open_webui_browser(webui_url, wait=False)
-        if runtime.status().running:
-            _attach_to_background_gateway(runtime)
-        else:
+        if not dev:
             console.print(
-                "[yellow]This gateway is controlled by another foreground command. "
-                "Stop it from that terminal.[/yellow]"
+                "Restart the gateway if you need it to pick up local source changes: "
+                f"[cyan]{_gateway_instance_command('restart', config_path=config_path, workspace=workspace)}[/cyan]"
             )
+            if not no_open:
+                _open_webui_browser(webui_url, wait=False)
+            if runtime.status().running:
+                _attach_to_background_gateway(runtime)
+            else:
+                console.print(
+                    "[yellow]This gateway is controlled by another foreground command. "
+                    "Stop it from that terminal.[/yellow]"
+                )
+            return
+
+        try:
+            assert dev_browser_url is not None
+            with run_webui_dev_server(
+                target_url=webui_dev_proxy_target(webui_url),
+                browser_url=dev_browser_url,
+                output=lambda message: console.print(f"[green]✓[/green] {message}"),
+            ) as dev_server:
+                if not no_open:
+                    _open_webui_browser(dev_browser_url, wait=False)
+                if runtime.status().running:
+                    _attach_to_background_gateway(
+                        runtime,
+                        poll_hook=dev_server.ensure_running,
+                    )
+                else:
+                    _wait_with_existing_foreground_gateway(
+                        runtime_config.gateway.host,
+                        effective_gateway_port,
+                        dev_server,
+                    )
+        except WebUIDevError as exc:
+            console.print(f"[red]Error: {exc}[/red]")
+            raise typer.Exit(1) from exc
         return
 
     gateway_port_taken = gateway_ready or _tcp_endpoint_reachable(
@@ -252,6 +320,29 @@ def webui(
         raise typer.Exit(1)
 
     _print_webui_foreground_lifecycle(attached=False)
+    if dev_browser_url:
+        dev_proxy_target = webui_dev_proxy_target(webui_url)
+        try:
+            with run_webui_dev_server(
+                target_url=dev_proxy_target,
+                browser_url=dev_browser_url,
+                output=lambda message: console.print(f"[green]✓[/green] {message}"),
+            ) as dev_server:
+                _run_gateway(
+                    runtime_config,
+                    port=effective_gateway_port,
+                    open_browser_url=None if no_open else dev_browser_url,
+                    open_browser_ready_url=f"{dev_proxy_target}/webui/bootstrap",
+                    webui_static_dist=False,
+                    webui_bundle_mode="skip",
+                    unconfigured_provider_error=settings_setup_error,
+                    webui_dev_server=dev_server,
+                )
+        except WebUIDevError as exc:
+            console.print(f"[red]Error: {exc}[/red]")
+            raise typer.Exit(1) from exc
+        return
+
     _run_gateway(
         runtime_config,
         port=effective_gateway_port,

nanobot/cli/webui_support.py

@@ -2,6 +2,7 @@
 
 import sys
 import time
+from collections.abc import Callable
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -424,11 +425,17 @@ def _print_webui_foreground_lifecycle(*, attached: bool) -> None:
     console.print("[dim]Press Ctrl+C here to stop nanobot.[/dim]")
 
 
-def _attach_to_background_gateway(runtime: "GatewayRuntime") -> None:
+def _attach_to_background_gateway(
+    runtime: "GatewayRuntime",
+    *,
+    poll_hook: Callable[[], None] | None = None,
+) -> None:
     """Keep a foreground WebUI command attached to a managed gateway."""
     _print_webui_foreground_lifecycle(attached=True)
     try:
         while runtime.status().running:
+            if poll_hook is not None:
+                poll_hook()
             time.sleep(0.5)
     except KeyboardInterrupt:
         console.print("\n[yellow]Stopping nanobot...[/yellow]")