feat: proxy the BFF to Vite for single-origin HMR in one terminal window

[marekdano]

Summary

The BFF and frontend used to each need their own terminal (npm run dev in server/, npm run dev at root). npm run dev:all now starts both together with one command — down to a single terminal for those two, with the API in mcp-context-forge remaining the only other one needed.

• Local dev previously meant either a slow rebuild-and-refresh loop (build:watch, no HMR) or visiting Vite's dev server directly on :5173
  — which needs a separate /api/* route to the BFF and 403s on login/SSE/password-reset unless PUBLIC_ORIGIN is manually overridden to work around the BFF's origin-guard.
• The BFF now reverse-proxies everything it doesn't own itself (SPA shell, JS/CSS modules, HMR) to a running Vite dev server when VITE_DEV_SERVER_URL is set, via a new vite-dev-proxy plugin (@fastify/http-proxy) registered in place of the static-file plugin. /api/*, /auth/*, /healthz, and the auth-aware / redirect stay BFF-owned and unaffected — verified via manual route-precedence checks.
• The browser now only ever talks to the BFF's own origin (:3000), matching how the app is served in production, so there's no origin mismatch to configure around.
• Added npm run dev:bff and npm run dev:all (via concurrently) to start the BFF (with VITE_DEV_SERVER_URL set) and the Vite dev server together in one command.
• Added predev/predev:bff/predev:all npm lifecycle hooks that check node_modules is in sync before dev/dev:bff/dev:all run, so a missing install fails with a clear "run npm install" message instead of a bare command not found.
• predev:all also runs npm run generate before starting either dev server, so dev:all always has fresh src/generated/ types — both on a fresh clone (that directory is gitignored and 34 files import from it) and after editing openapi.json mid-session.
• Updated README and .env.example to document the new flow, alongside the existing build/build:watch path for testing the exact BFF-served bundle.

Test plan

• npm run build — succeeds
• npm run lint (in server/) — typechecks clean
• npm run dev:all from repo root: http://localhost:3000/ loads, redirects to /app/login when unauthed, HMR client/React-refresh correctly injected into /app/
• curl http://localhost:3000/healthz and /api/* still return BFF responses (not proxied to Vite)
• Simulated missing node_modules — dev, dev:bff, and dev:all each fail with the intended message instead of command not found
• Deleted src/generated/ — dev:all regenerates it via predev:all before either dev server starts

[a-effort]

Reviewed the diff. One blocker.

The vite-dev-proxy plugin registers a wildcard route with prefix "/" and routes ["/"], then relies on find-my-way preferring statically registered routes over this catch-all. That assumption holds for routes registered before the plugin, but the comment in the plugin file acknowledges that bare GET / is excluded from routes because routes/app.ts owns it. The problem: @fastify/http-proxy also registers a GET / by default when prefix is "/", which would collide with routes/app.ts's GET / as a duplicate route. The exclusion note says this is intentional, but the mechanism that prevents the collision is not obvious. If @fastify/http-proxy's internal route registration includes GET / regardless of the routes array, this will throw a duplicate route error at startup. Before merging, confirm that the plugin does not register GET / when routes: ["/"] is specified, or add an explicit test that the BFF starts without error when VITE_DEV_SERVER_URL is set.

A second concern: the predev:all hook runs npm run generate before starting either dev server, but generate runs orval which requires openapi.json to be present and valid. If a contributor clones the repo and openapi.json is absent or stale (e.g., after a rebase), generate will fail before anything starts. The README documents this as expected, but the error message from orval is not especially clear. A guard that checks for openapi.json before running generate, with a pointer to npm run openapi:refresh, would reduce friction.

[gcgoncalves]

Small one: the ! here relies on index.ts registering it to guarantee this is set. It may be worth a runtime check too, since @fastify/http-proxy's own validation won't catch an undefined upstream in this config. If the registration is ever removed, this would fail silently at startup and only surface as an error on the first proxied request.

Suggested fix:

if (!config.viteDevServerUrl) {
  throw new Error("viteDevProxyPlugin registered without VITE_DEV_SERVER_URL set");
}

await fastify.register(httpProxy, {
  upstream: config.viteDevServerUrl,
  ...

Cheap safeguard, fails fast and surfaces an error message. :)

[marekdano]

@a-effort - please review again

[a-effort]

LGTM! 🚀