refactor: Handle project definition changes

[RandomByte]

Problem

ui5 serve could not safely react to project-definition changes while running. Changes to files like ui5.yaml, package.json, workspace config, or a static dependency definition need a fresh project graph, but the server only watched source files and served an app it had already built. Switching branches or editing config could leave the running server pointing at an out-of-date graph, source paths that had moved, or short-lived watcher/build errors.

Solution

This adds a way to handle definition changes, alongside the existing handling of source changes.

• Add ProjectDefinitionWatcher to watch the project-definition files.
• Add Supervisor to keep the HTTP server and port stable while it rebuilds the graph, Express app, and BuildServer behind them.
• Build the new server before tearing down the old one, so a failed rebuild leaves the last working server running.
• Recover a broken server by retrying until the new graph is stable, so switching branches mid-checkout (sources still being written) resolves cleanly on a retry instead of serving a half-restored project.
• Stop answering requests as soon as a definition change starts, so requests fail fast instead of hanging until the checkout finishes writing files.
• Re-point live reload and the file watchers at the new graph after a successful swap.
• Make source watching survive branch switches and moved paths.
• Update the interactive console while the project is being re-resolved, including an error status line that stays until the server recovers.
• Add serveMiddleware for mounting UI5 middleware into another server.

ProjectDefinitionWatcher and Supervisor

ProjectDefinitionWatcher watches the files that define the project graph: project package.json files, ui5.yaml or a custom --config, workspace config, and static dependency-definition files. It fires an early definitionChanging signal (for UI feedback) and, once the changes settle, a definitionChanged signal that tells the server to reinitialize. Settling matters for bursts of changes such as branch switches, where many files change at once.

The watcher belongs to Supervisor, not the BuildServer, so it stays alive across serving-stack swaps. After a successful reinitialization it is re-pointed at the new graph, while the source watcher keeps handling incremental rebuilds for the graph that is currently live.

  CLI
   |
   v
serve()  [server.js]
   |
   v
Supervisor  (owns the stable HTTP socket)
   |
   +-- binds port once; request forwarder routes every request to #stack.app
   |
   +-- ProjectDefinitionWatcher  (@ui5/project)
   |    watches ui5.yaml, package.json, workspace config
   |    definitionChanging --> blank version in console; stop answering requests
   |    definitionChanged  --> Supervisor.reinitialize()
   |
   +-- #stack  { app, BuildServer }   <-- swapped on reinit; forwarder retargets silently
   |    |
   |    +-- BuildServer  (@ui5/project)
   |         watches source files; emits sourcesChanged
   |
   +-- #sourcesChangedRelay  (stable; live-reload clients stay connected across swaps)

Supervisor keeps the socket and the relay for the whole run. Everything else -- the serving app, the BuildServer, and the ProjectDefinitionWatcher -- is rebuilt on a definition change and swapped in behind the request forwarder, without dropping the port or disconnecting open browsers.

Swap lifecycle

Reinitialization follows a small state machine. State only changes through #setState, which checks each change against a table of allowed transitions:

HEALTHY    --(definition change)--------> RESOLVING
RESOLVING  --(resolve+build ok)---------> HEALTHY
RESOLVING  --(resolve/build failed)-----> DEGRADED
DEGRADED   --(scheduled recovery)-------> RECOVERING
RECOVERING --(converged+built)----------> HEALTHY
RECOVERING --(still failing)------------> DEGRADED
any        --(destroy)------------------> DESTROYED  (terminal)

The state decides what is allowed: whether a swap is already running, whether the server has been shut down, and which transitions are legal. A HEALTHY swap resolves the graph once; a DEGRADED swap runs the recovery loop described below. If several definitionChanged events arrive while a swap is running, they collapse into one final pass, so a burst of edits only resolves once against the settled files.

One switch controls whether the server answers requests. When definitionChanging fires, the current BuildServer stops serving readers: it rejects the requests already waiting and fast-fails new ones. Serving is turned back on in a single place, used by both swap outcomes (success and failure), so no code path can accidentally leave the server stuck not answering.

Degraded recovery

If a re-resolve fails, the previous server keeps running, but its graph no longer matches the files on disk. The server is marked degraded: a middleware step sends every request to the error page (not just page loads), and the interactive console shows an error status line that stays put. The next successful swap, on a valid edit, clears the mark.

A degraded server also schedules one recovery attempt on its own. The reason it retries rather than resolving once: a branch switch writes package.json, ui5.yaml, and the source files as one operation, and on a big tree (or a slow disk, or Git LFS fetching files) those arrive in several waves. A single "wait for quiet, then retry" can land in the gap between waves and resolve against a tree that is still missing files, or missing a symlink target that a restored package.json points at. So recovery loops instead (#convergeRecoveryGraph): resolve, list the project roots, and if that list changed from last time, wait for another quiet window and resolve again. It stops once two resolves in a row agree on the roots.

DEGRADED (last-good stack serving)
   |
   +-- schedule one recovery (RecoveryBudget: 5 attempts / 60s)
   |
   v
#convergeRecoveryGraph()  loop, bounded by RECOVERY_MAX_ITERATIONS
   |
   +-- resolve graph via graphFactory()
   +-- collect project-root set
   +-- roots subset of previous?  --yes--> converged: build + swap --> HEALTHY
   |                              --no-->  feed [candidate, last-good] to
   |                                       ProjectGraphSettler, await quiet, re-resolve
   v
 (budget exhausted / branch never resolves) --> stay DEGRADED until next definition change

The check is "did the root set shrink or stay the same", not "is it identical", so a branch that removes a dependency still counts as settled. Each pass hands the settler both the new graph and the last known-good one, so a project that only the target branch adds gets watched for quiet as soon as it first shows up in a resolve. RecoveryBudget counts an attempt when recovery is scheduled, not when it succeeds, so a branch that never resolves uses up its 5 attempts and then stays degraded instead of retrying forever. A real edit (definitionChanging) cancels any pending retry and resets the count; a clean swap resets it too.

Middleware API

The server now keeps two jobs apart: building the middleware and owning the HTTP listener. That split is what makes the graph swap work: the HTTP server stays bound to its port while a new graph, middleware stack, and BuildServer are built and swapped in behind it. serve() still starts and owns the UI5 dev server, but under the hood it reuses smaller pieces for building the middleware, binding HTTP, and managing graph swaps.

It also adds a new serveMiddleware() API for outside consumers. It sets up the same UI5 readers/resources and the same standard and custom middleware chain that ui5 serve uses, but hands it back as connect/Express-compatible middleware instead of starting an HTTP server.

Other tools can now call app.use(result.middleware) on their own Express/connect server and stay in charge of the port, protocol, routing around UI5, and error handling. The returned close() function frees the BuildServer's watcher and cache when the outside server shuts down.

Third-party server (e.g. Vite, custom Express app)
   |
   | const {middleware, close} = await serveMiddleware(graph, options)
   v
serveMiddleware()  [server.js re-export -> serveMiddleware.js]
   |
   +-- calls buildRouter()  [serve/stack.js]
   |    |
   |    +-- starts BuildServer  (@ui5/project)
   |    +-- assembles UI5 middleware chain onto an Express Router
   |    +-- returns { router, buildServer }
   |
   +-- returns { middleware: router, buildServer, close() }


Third-party app                       @ui5/server
+-------------------------+           +--------------------+
| const app = express()   |           |                    |
| app.use(middleware)  ---+---------> | UI5 router         |
| app.use(errorHandler)   |           | (build-on-request, |
| app.listen(8080)        |           |  index, CSP, ...)  |
|                         |           +--------------------+
| // teardown:            |
| listener.close()        |
| await close()        ---+---------> BuildServer.destroy()
+-------------------------+           (releases source watcher
                                       and build-cache handle)

The caller owns the port, the HTTP server, error handling, and the order of teardown. serveMiddleware never binds a socket, never attaches a live-reload WebSocket server, and never installs a final error handler -- those stay with the caller's server.