fix(web): make serve loads the browser app (#101)

Author: nosam1998

CONTRIBUTING.md

@@ -14,11 +14,17 @@ make setup
 make serve
 ```
 
-In another terminal, run `make dev` and open the URL printed by Vite. The API
-defaults to `http://127.0.0.1:8080`; its interactive reference is at `/docs/`.
+Open `http://127.0.0.1:8080/` for the browser app; the API reference is at
+`/docs/`. `make serve` installs the locked browser dependencies and builds the
+production app before starting the server. `make serve-postgres` does the same
+with PostgreSQL.
+
+For hot reload, use `make serve-api` in one terminal and `make dev` in another.
+Open Vite’s URL (normally `http://127.0.0.1:5173/`). API-only mode needs no browser
+build and redirects its root URL to the API reference.
 
 ```sh
-make serve PORT=9090 DB_PATH=./development.sqlite
+make serve-api PORT=9090 DB_PATH=./development.sqlite
 GFA_API_TARGET=http://127.0.0.1:9090 make dev
 make serve CLI_ARGS='--stockfish /usr/games/stockfish'
 make mcp
@@ -38,7 +44,7 @@ environment variable. The database URL is never a Make command-line argument.
 | --- | --- |
 | `make build` | Rust workspace and production web assets |
 | `make check` | Rust format, Clippy, dependency boundaries, all-feature tests; web types, lint, boundaries and format |
-| `make test-browser` | Build the server and run the actual browser integration suite |
+| `make test-browser` | Build the app and server, then run production and development browser tests |
 | `make format` | Format Rust and browser sources |
 | `make audit` | Run the existing cargo-deny policy (install cargo-deny first) |
 | `make docs` | Build Rust API documentation |

Cargo.lock

@@ -62,6 +62,7 @@ tempfile = "3"
 
 axum = { version = "0.8.9", default-features = false, features = ["http1", "json", "query", "tokio", "ws"] }
 tower = { version = "0.5", features = ["util"] }
+tower-http = { version = "0.6", default-features = false, features = ["fs"] }
 
 uuid = { version = "1", features = ["v4"] }
 

Cargo.toml

@@ -11,7 +11,7 @@ CLI_ARGS ?=
 SQLX_OFFLINE ?= true
 export SQLX_OFFLINE
 
-.PHONY: help setup setup-rust setup-web setup-python serve serve-postgres mcp dev \
+.PHONY: help setup setup-rust setup-web setup-python serve serve-api serve-postgres mcp dev \
 	build build-rust build-server build-web build-python check check-rust check-web \
 	test test-rust test-browser test-python lint-rust check-deps audit format \
 	format-rust format-web format-check format-check-rust format-check-web \
@@ -34,16 +34,19 @@ setup-web: ## Install the pinned browser dependencies.
 setup-python: ## Install the native SDK and test/dataset/tournament extras (use a virtualenv).
 	$(PYTHON) -m pip install '.[test,datasets,tournaments]' 'maturin>=1.9,<2'
 
-serve: ## Run the local SQLite API; open a second terminal for make dev.
+serve: build-web ## Build and serve the browser app + SQLite API at http://127.0.0.1:8080/.
+	$(CARGO) run -p gfa-cli --locked -- serve --web-dir web/apps/site/dist --sqlite "$(DB_PATH)" --port "$(PORT)" $(CLI_ARGS)
+
+serve-api: ## Run only the SQLite API (pair with make dev for hot reload).
 	$(CARGO) run -p gfa-cli --locked -- serve --sqlite "$(DB_PATH)" --port "$(PORT)" $(CLI_ARGS)
 
-serve-postgres: ## Run the API using a PostgreSQL URL from POSTGRES_ENV.
-	$(CARGO) run -p gfa-cli --features postgres --locked -- serve --postgres-env "$(POSTGRES_ENV)" --port "$(PORT)" $(CLI_ARGS)
+serve-postgres: build-web ## Serve the app + API using a PostgreSQL URL from POSTGRES_ENV.
+	$(CARGO) run -p gfa-cli --features postgres --locked -- serve --web-dir web/apps/site/dist --postgres-env "$(POSTGRES_ENV)" --port "$(PORT)" $(CLI_ARGS)
 
 mcp: ## Run the local MCP server over stdin/stdout.
 	@$(CARGO) run -p gfa-cli --locked -- mcp --sqlite "$(DB_PATH)" $(CLI_ARGS)
 
-dev: ## Run the browser development server (API must be running separately).
+dev: ## Run the browser with hot reload (run make serve-api in another terminal).
 	$(PNPM) dev
 
 build: build-rust build-web ## Build the Rust workspace and production browser assets.
@@ -54,7 +57,7 @@ build-rust: ## Build all Rust workspace members.
 build-server: ## Build the local gfa CLI/server.
 	$(CARGO) build -p gfa-cli --locked
 
-build-web: ## Build the browser application.
+build-web: setup-web ## Install locked dependencies and build the browser application.
 	$(PNPM) build
 
 build-python: ## Build a release Python wheel into dist/.
@@ -71,7 +74,7 @@ test: test-rust ## Run workspace unit/integration tests (alias for test-rust).
 test-rust: ## Test the Rust workspace with all features and the locked dependency graph.
 	$(CARGO) test --workspace --all-features --locked
 
-test-browser: build-server ## Test the browser against an isolated real backend.
+test-browser: build-server build-web ## Test the production app and dev browser against a real backend.
 	$(PNPM) test:browser
 
 test-python: ## Test the installed native Python SDK (run setup-python after Rust changes).

Makefile

@@ -6,18 +6,29 @@ See the [Product Requirements Document](docs/PRD.md).
 
 ## Run locally
 
-Use `make help` for setup, run, build, and verification shortcuts. The
-[contributor guide](CONTRIBUTING.md) documents prerequisites and optional Python
-setup. `make setup`, `make serve`, and `make dev` (in a second terminal) start the
-local development environment.
+With Rust, Node.js 22 and pnpm 10.6.5 installed, run:
 
+```sh
+make serve
+```
+
+This installs the locked browser dependencies, builds the app, and serves both
+it and the API at **http://127.0.0.1:8080/**. The interactive API reference is at
+`/docs/`. Stop and rerun the command after changing the browser source.
+Use `PORT=9090` or `DB_PATH=./development.sqlite` to override the local defaults.
+
+For browser development with hot reload, run `make serve-api` in one terminal
+and `make dev` in another; open the URL printed by Vite (normally port 5173).
+For API-only use without Node.js:
 
 ```sh
 cargo run -p gfa-cli --locked -- serve --sqlite ./gfa.sqlite --port 8080
 ```
 
-Open `http://127.0.0.1:8080/docs/` for the interactive API reference. Local mode
-binds to loopback and treats the local caller as the match owner.
+API-only mode redirects `/` to `/docs/`. To serve a previously built frontend,
+add `--web-dir web/apps/site/dist`. Local mode binds to loopback and treats the
+local caller as the match owner. See `make help` and the
+[contributor guide](CONTRIBUTING.md) for other workflows.
 
 For PostgreSQL, enable the backend and put the connection URL in an environment
 variable so credentials do not appear in the command arguments:

README.md

@@ -9,6 +9,7 @@ gfa-core = { workspace = true, features = ["openapi"] }
 gfa-api-types = { workspace = true, features = ["openapi"] }
 gfa-service.workspace = true
 axum.workspace = true
+tower-http.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 tokio.workspace = true

crates/adapters/gfa-http/Cargo.toml

@@ -12,6 +12,8 @@ mod opponents;
 pub use openapi::openapi_document;
 mod stream;
 mod training;
+mod web;
+pub use web::browser_router;
 
 pub use stream::LiveUpdates;
 

crates/adapters/gfa-http/src/lib.rs

@@ -0,0 +1,40 @@
+//! Host-selected browser assets. The app uses hash routes, so unknown API paths
+//! must keep their normal JSON errors instead of falling back to index.html.
+use axum::{response::Redirect, routing::get, Router};
+use std::{io, path::Path};
+use tower_http::services::{ServeDir, ServeFile};
+
+/// Serve a trusted Vite production build, or direct API-only visitors to the docs.
+///
+/// The host must wrap these routes in `protect_local_routes`. Only index.html and
+/// assets/ are exposed; the build directory's other files are never served.
+/// Files remain on disk and must be kept available for the server's lifetime.
+pub fn browser_router(directory: Option<&Path>) -> io::Result<Router> {
+    let Some(directory) = directory else {
+        return Ok(Router::new().route("/", get(|| async { Redirect::temporary("/docs/") })));
+    };
+    let directory = directory.canonicalize().map_err(|error| {
+        io::Error::new(
+            error.kind(),
+            format!(
+                "Browser build unavailable at {}. Run make build-web, then pass --web-dir web/apps/site/dist.",
+                directory.display()
+            ),
+        )
+    })?;
+    let index = directory.join("index.html");
+    let assets = directory.join("assets");
+    if !index.is_file() || !assets.is_dir() {
+        return Err(io::Error::new(
+            io::ErrorKind::NotFound,
+            "Browser build requires index.html and assets/. Run make build-web before serving it.",
+        ));
+    }
+    Ok(Router::new()
+        .route_service("/", ServeFile::new(index.clone()))
+        .route_service("/index.html", ServeFile::new(index))
+        .nest_service(
+            "/assets",
+            ServeDir::new(assets).append_index_html_on_directories(false),
+        ))
+}

crates/adapters/gfa-http/src/web.rs

@@ -2,7 +2,7 @@
 use gfa_server::{Config, Database, ServerError};
 use std::path::PathBuf;
 
-const USAGE: &str = "Usage: gfa mcp [--sqlite PATH | --postgres-env VARIABLE] [--seat SEAT | --spectator] [--stockfish PATH]\n       gfa serve [--sqlite PATH | --postgres-env VARIABLE] [--port PORT] [--stockfish PATH] [--mcp-seat SEAT | --mcp-spectator]\n       gfa tournament --game GAME --agents FILES [--opponents LADDER] [--games COUNT] [--report PATH]\n\nmcp serves a trusted local client over stdin/stdout; seat defaults to 0. No TCP port is opened.\nserve starts a local API on 127.0.0.1 (default port 8080).\nHTTP /mcp defaults to seat 0; use --mcp-seat or --mcp-spectator to change it.\ntournament uses gamesforai[tournaments] in GFA_PYTHON (default python3; python on Windows).\nSQLite defaults to ./gfa.sqlite. Port 0 selects an available port.\nPostgreSQL requires the postgres build feature and reads its URL from VARIABLE.\nStockfish requires an absolute binary path, Linux, bubblewrap and working user namespaces.";
+const USAGE: &str = "Usage: gfa mcp [--sqlite PATH | --postgres-env VARIABLE] [--seat SEAT | --spectator] [--stockfish PATH]\n       gfa serve [--sqlite PATH | --postgres-env VARIABLE] [--port PORT] [--web-dir DIRECTORY] [--stockfish PATH] [--mcp-seat SEAT | --mcp-spectator]\n       gfa tournament --game GAME --agents FILES [--opponents LADDER] [--games COUNT] [--report PATH]\n\nmcp serves a trusted local client over stdin/stdout; seat defaults to 0. No TCP port is opened.\nserve starts a local API on 127.0.0.1 (default port 8080). Add --web-dir to serve a browser build.\nWithout --web-dir, / redirects to /docs/. make serve builds and serves the browser app.\nHTTP /mcp defaults to seat 0; use --mcp-seat or --mcp-spectator to change it.\ntournament uses gamesforai[tournaments] in GFA_PYTHON (default python3; python on Windows).\nSQLite defaults to ./gfa.sqlite. Port 0 selects an available port.\nPostgreSQL requires the postgres build feature and reads its URL from VARIABLE.\nStockfish requires an absolute binary path, Linux, bubblewrap and working user namespaces.";
 
 fn parse(args: impl IntoIterator<Item = String>) -> Result<Option<Config>, String> {
     parse_with_env(args, |name| std::env::var(name).ok())
@@ -23,6 +23,7 @@ fn parse_with_env(
     let mut config = Config::default();
     let mut database_seen = false;
     let mut port_seen = false;
+    let mut web_seen = false;
     let mut stockfish_seen = false;
     let mut mcp_viewer_seen = false;
     while let Some(option) = args.next() {
@@ -83,6 +84,14 @@ fn parse_with_env(
                 config.stockfish = Some(gfa_server::StockfishConfig::linux(path));
                 stockfish_seen = true;
             }
+            "--web-dir" if !web_seen => {
+                let path = args.next().ok_or("--web-dir requires a build directory")?;
+                if path.is_empty() || path.starts_with("--") {
+                    return Err("--web-dir requires a build directory".into());
+                }
+                config.web_dir = Some(PathBuf::from(path));
+                web_seen = true;
+            }
             "--port" if !port_seen => {
                 config.port = args
                     .next()
@@ -128,6 +137,7 @@ fn command(args: impl IntoIterator<Item = String>) -> Result<Option<Command>, St
                 viewer_seen = true;
             }
             "--seat" | "--spectator" => return Err("Choose --seat or --spectator once".into()),
+            "--web-dir" => return Err("--web-dir is only supported by gfa serve".into()),
             "--mcp-seat" | "--mcp-spectator" => {
                 return Err("Use --seat or --spectator for mcp stdio".into())
             }
@@ -236,6 +246,7 @@ mod tests {
                 port: 0,
                 stockfish: None,
                 mcp_seat: Some(0),
+                web_dir: None,
             })
         );
         let configured =
@@ -309,6 +320,22 @@ mod tests {
             .is_some_and(|error| error.contains("--features postgres")));
     }
 
+    #[test]
+    fn browser_directory_is_explicit_and_only_supported_for_http() -> Result<(), String> {
+        let configured = options(&["serve", "--web-dir", "web build"])?.ok_or("missing config")?;
+        assert_eq!(configured.web_dir, Some(PathBuf::from("web build")));
+        for args in [
+            vec!["serve", "--web-dir"],
+            vec!["serve", "--web-dir", ""],
+            vec!["serve", "--web-dir", "--port"],
+            vec!["serve", "--web-dir", "one", "--web-dir", "two"],
+        ] {
+            assert!(options(&args).is_err(), "{args:?}");
+        }
+        assert!(command(["mcp", "--web-dir", "web"].map(str::to_owned)).is_err());
+        Ok(())
+    }
+
     #[test]
     fn rejects_invalid_or_ambiguous_options() {
         for args in [

crates/apps/gfa-cli/src/main.rs

@@ -27,6 +27,9 @@ pub struct Config {
     pub database: Database,
     /// Loopback port. Zero lets the OS select an available port.
     pub port: u16,
+    /// Optional trusted browser build directory containing index.html and assets/.
+    /// None serves the API and redirects browser visits at / to /docs/.
+    pub web_dir: Option<PathBuf>,
     /// Optional installed Stockfish engine and sandbox policy.
     pub stockfish: Option<StockfishConfig>,
     /// MCP viewer selected by the trusted local launcher. None selects spectator.
@@ -38,6 +41,7 @@ impl Default for Config {
         Self {
             database: Database::Sqlite("gfa.sqlite".into()),
             port: 8080,
+            web_dir: None,
             stockfish: None,
             mcp_seat: Some(0),
         }
@@ -153,14 +157,19 @@ async fn components(config: &Config) -> Result<Components, ServerError> {
 }
 
 async fn application(config: &Config, address: SocketAddr) -> Result<Application, ServerError> {
+    // Validate the requested build before opening or migrating the database.
+    let browser = gfa_http::protect_local_routes(
+        gfa_http::browser_router(config.web_dir.as_deref())?,
+        address,
+    )?;
     let Components {
         store,
         updates,
         service,
     } = components(config).await?;
     let router = gfa_http::local_router_with_updates(service.clone(), address, updates.clone())?;
     let (mcp_router, mcp) = mcp_http::router(service.clone(), address, config.mcp_seat)?;
-    let router = router.merge(mcp_router);
+    let router = router.merge(mcp_router).merge(browser);
     Ok(Application {
         mcp,
         router,
@@ -182,6 +191,12 @@ pub async fn serve(
     let address = listener.local_addr()?;
     let app = application(&config, address).await?;
     println!("GamesForAI listening on http://{address} (local mode)");
+    if config.web_dir.is_some() {
+        println!("Browser app: http://{address}/");
+    } else {
+        println!("API-only mode. Run make serve to include the browser app.");
+    }
+    println!("API reference: http://{address}/docs/");
     serve_application(listener, app, shutdown).await
 }
 
@@ -292,3 +307,6 @@ mod uci_cap_tests;
 
 #[cfg(test)]
 mod training_tests;
+
+#[cfg(test)]
+mod web_tests;