feat(project): Add liveReload server setting and BuildServer event

- Add new `server.settings.liveReload` boolean option to the project
  configuration schema, available with specVersion 5.0 and higher.
- BuildServer now emits a debounced `sourcesChanged` event (100ms
  debounce) whenever watched source files change, so a burst of changes
  results in a single notification.

JIRA: CPOUI5FOUNDATION-1224

Author: matz3

internal/documentation/docs/pages/Configuration.md

@@ -650,6 +650,7 @@ server:
   settings:
     httpPort: 1337
     httpsPort: 1443
+    liveReload: true
 ```
 
 :::
@@ -662,6 +663,8 @@ A project can also configure alternative default ports. If the configured port i
 
 The default and configured server ports can always be overwritten with the CLI parameter `--port`.
 
+The `liveReload` setting controls whether the browser automatically reloads when project sources change. It defaults to `true` when running `ui5 serve` and can be overridden via the CLI parameter `--live-reload`. Requires [Specification Version](#specification-versions) 5.0 or higher.
+
 ## Extension Configuration
 
 ::: details Example
@@ -809,6 +812,10 @@ Version | UI5 CLI Release
 
 ### Specification Version 5.0
 
+**Features:**
+
+- Adds new server setting [`server.settings.liveReload`](#server-configuration) to control automatic browser reload on source changes
+
 Specification Version 5.0 projects are supported by [UI5 CLI](https://github.com/UI5/cli) v5.0.0 and above.
 
 ### Specification Version 4.0

packages/project/lib/build/BuildServer.js

@@ -6,6 +6,10 @@ import {SourceChangedDuringBuildError} from "./cache/ProjectBuildCache.js";
 import {getLogger} from "@ui5/logger";
 const log = getLogger("build:BuildServer");
 
+// Debounce window for the `sourcesChanged` event so a burst of file changes
+// results in a single notification.
+const SOURCES_CHANGED_DEBOUNCE_MS = 100;
+
 class AbortBuildError extends Error {
 	constructor(message) {
 		super(message);
@@ -44,6 +48,7 @@ class BuildServer extends EventEmitter {
 	#pendingBuildRequest = new Set();
 	#activeBuild = null;
 	#processBuildRequestsTimeout;
+	#sourcesChangedTimeout;
 	#destroyed = false;
 	#allReader;
 	#rootReader;
@@ -154,6 +159,7 @@ class BuildServer extends EventEmitter {
 	async destroy() {
 		this.#destroyed = true;
 		clearTimeout(this.#processBuildRequestsTimeout);
+		clearTimeout(this.#sourcesChangedTimeout);
 		await this.#watchHandler.destroy();
 		try {
 			if (this.#activeBuild) {
@@ -308,10 +314,14 @@ class BuildServer extends EventEmitter {
 			this.#resourceChangeQueue.set(project.getName(), new Set([filePath]));
 		}
 
-		// : Emit event debounced
-		// Emit change event immediately so that consumers can react to it (like browser reloading)
-		// const changedResourcePaths = [...changes.values()].flat();
-		// this.emit("sourcesChanged", changedResourcePaths);
+		// Debounced emit so a burst of file changes results in a single reload notification
+		if (this.#sourcesChangedTimeout) {
+			clearTimeout(this.#sourcesChangedTimeout);
+		}
+		this.#sourcesChangedTimeout = setTimeout(() => {
+			this.#sourcesChangedTimeout = null;
+			this.emit("sourcesChanged");
+		}, SOURCES_CHANGED_DEBOUNCE_MS);
 	}
 
 	#flushResourceChanges() {

packages/project/lib/validation/schema/specVersion/kind/project.json

@@ -24,6 +24,33 @@
 					}
 				}
 			}
+		},
+		{
+			"if": {
+				"type": "object",
+				"properties": {
+					"specVersion": {
+						"not": {"const": "5.0"}
+					}
+				}
+			},
+			"then": {
+				"type": "object",
+				"properties": {
+					"server": {
+						"type": "object",
+						"properties": {
+							"settings": {
+								"type": "object",
+								"not": {
+									"required": ["liveReload"]
+								},
+								"errorMessage": "The 'liveReload' setting is only supported with specVersion '5.0' and higher."
+							}
+						}
+					}
+				}
+			}
 		}
 	],
 	"properties": {
@@ -691,6 +718,9 @@
 						},
 						"httpsPort": {
 							"type": "number"
+						},
+						"liveReload": {
+							"type": "boolean"
 						}
 					}
 				},

packages/project/test/lib/validation/schema/specVersion/kind/project.js

@@ -285,3 +285,47 @@ test("Legacy: Special characters in name (module)", async (t) => {
 		}
 	});
 });
+
+test("server.settings.liveReload (specVersion 5.0)", async (t) => {
+	await assertValidation(t, {
+		"specVersion": "5.0",
+		"type": "application",
+		"metadata": {
+			"name": "my-application"
+		},
+		"server": {
+			"settings": {
+				"liveReload": true
+			}
+		}
+	});
+});
+
+test("server.settings.liveReload (legacy specVersion)", async (t) => {
+	await assertValidation(t, {
+		"specVersion": "4.0",
+		"type": "application",
+		"metadata": {
+			"name": "my-application"
+		},
+		"server": {
+			"settings": {
+				"liveReload": true
+			}
+		}
+	}, [{
+		instancePath: "/server/settings",
+		keyword: "errorMessage",
+		message: "The 'liveReload' setting is only supported with specVersion '5.0' and higher.",
+		params: {
+			errors: [{
+				emUsed: true,
+				instancePath: "/server/settings",
+				keyword: "not",
+				message: "must NOT be valid",
+				params: {},
+				schemaPath: "#/allOf/1/then/properties/server/properties/settings/not",
+			}],
+		}
+	}]);
+});

packages/project/test/lib/validation/schema/specVersion/kind/project/application.js

@@ -338,6 +338,38 @@ SpecificationVersion.getVersionsForRange(">=4.0").forEach(function(specVersion)
 			}
 		]);
 	});
+
+	test(`Server liveReload setting (specVersion ${specVersion})`, async (t) => {
+		const config = {
+			"specVersion": specVersion,
+			"type": "application",
+			"metadata": {
+				"name": "com.sap.ui5.test"
+			},
+			"server": {
+				"settings": {
+					"liveReload": true
+				}
+			}
+		};
+		if (new SpecificationVersion(specVersion).gte("5.0")) {
+			await assertValidation(t, config);
+		} else {
+			await assertValidation(t, config, [{
+				instancePath: "/server/settings",
+				keyword: "errorMessage",
+				message: "The 'liveReload' setting is only supported with specVersion '5.0' and higher.",
+				params: {
+					errors: [{
+						instancePath: "/server/settings",
+						keyword: "not",
+						message: "must NOT be valid",
+						params: {},
+					}],
+				}
+			}]);
+		}
+	});
 });
 
 SpecificationVersion.getVersionsForRange("2.0 - 3.2").forEach(function(specVersion) {

packages/project/test/lib/validation/schema/specVersion/kind/project/component.js

@@ -960,6 +960,21 @@ SpecificationVersion.getVersionsForRange(">=5.0").forEach(function(specVersion)
 			},
 		}]);
 	});
+
+	test(`Server liveReload setting (specVersion ${specVersion})`, async (t) => {
+		await assertValidation(t, {
+			"specVersion": specVersion,
+			"type": "component",
+			"metadata": {
+				"name": "my.component"
+			},
+			"server": {
+				"settings": {
+					"liveReload": true
+				}
+			}
+		});
+	});
 });
 
 project.defineTests(test, assertValidation, "component");

packages/project/test/lib/validation/schema/specVersion/kind/project/library.js

@@ -265,6 +265,38 @@ SpecificationVersion.getVersionsForRange(">=4.0").forEach(function(specVersion)
 			},
 		]);
 	});
+
+	test(`Server liveReload setting (specVersion ${specVersion})`, async (t) => {
+		const config = {
+			"specVersion": specVersion,
+			"type": "library",
+			"metadata": {
+				"name": "my.library"
+			},
+			"server": {
+				"settings": {
+					"liveReload": true
+				}
+			}
+		};
+		if (new SpecificationVersion(specVersion).gte("5.0")) {
+			await assertValidation(t, config);
+		} else {
+			await assertValidation(t, config, [{
+				instancePath: "/server/settings",
+				keyword: "errorMessage",
+				message: "The 'liveReload' setting is only supported with specVersion '5.0' and higher.",
+				params: {
+					errors: [{
+						instancePath: "/server/settings",
+						keyword: "not",
+						message: "must NOT be valid",
+						params: {},
+					}],
+				}
+			}]);
+		}
+	});
 });
 
 SpecificationVersion.getVersionsForRange("2.0 - 3.2").forEach(function(specVersion) {

packages/project/test/lib/validation/schema/specVersion/kind/project/module.js

@@ -174,6 +174,38 @@ SpecificationVersion.getVersionsForRange(">=2.5").forEach(function(specVersion)
 		});
 	});
 
+	test(`Server liveReload setting (specVersion ${specVersion})`, async (t) => {
+		const config = {
+			"specVersion": specVersion,
+			"type": "module",
+			"metadata": {
+				"name": "my-module"
+			},
+			"server": {
+				"settings": {
+					"liveReload": true
+				}
+			}
+		};
+		if (new SpecificationVersion(specVersion).gte("5.0")) {
+			await assertValidation(t, config);
+		} else {
+			await assertValidation(t, config, [{
+				instancePath: "/server/settings",
+				keyword: "errorMessage",
+				message: "The 'liveReload' setting is only supported with specVersion '5.0' and higher.",
+				params: {
+					errors: [{
+						instancePath: "/server/settings",
+						keyword: "not",
+						message: "must NOT be valid",
+						params: {},
+					}],
+				}
+			}]);
+		}
+	});
+
 	test(`module (specVersion ${specVersion}): builder/settings/includeDependency*`, async (t) => {
 		await assertValidation(t, {
 			"specVersion": specVersion,

packages/project/test/lib/validation/schema/specVersion/kind/project/theme-library.js

@@ -167,6 +167,38 @@ SpecificationVersion.getVersionsForRange(">=2.0").forEach(function(specVersion)
 			}
 		}]);
 	});
+
+	test(`Server liveReload setting (specVersion ${specVersion})`, async (t) => {
+		const config = {
+			"specVersion": specVersion,
+			"type": "theme-library",
+			"metadata": {
+				"name": "my.theme.library"
+			},
+			"server": {
+				"settings": {
+					"liveReload": true
+				}
+			}
+		};
+		if (new SpecificationVersion(specVersion).gte("5.0")) {
+			await assertValidation(t, config);
+		} else {
+			await assertValidation(t, config, [{
+				instancePath: "/server/settings",
+				keyword: "errorMessage",
+				message: "The 'liveReload' setting is only supported with specVersion '5.0' and higher.",
+				params: {
+					errors: [{
+						instancePath: "/server/settings",
+						keyword: "not",
+						message: "must NOT be valid",
+						params: {},
+					}],
+				}
+			}]);
+		}
+	});
 });
 
 SpecificationVersion.getVersionsForRange(">=2.5").forEach(function(specVersion) {