feat: Add off mode to UI5_WATCH_MODE

.claude/skills/incremental-build/architecture.md

@@ -44,7 +44,7 @@ Use this table to locate source files. ALWAYS read the relevant source file befo
 | `RecoveryBudget` | `lib/build/helpers/RecoveryBudget.js` | Sliding-window loop protection for watcher recovery (`WATCHER_RECOVERY_MAX_ATTEMPTS` = 5 within `WATCHER_RECOVERY_WINDOW_MS` = 60000). One instance per watcher, so a fault in one does not consume the other's budget |
 | `watchSettle` | `lib/build/helpers/watchSettle.js` | Single source of `WATCHER_BURST_SETTLE_MS` = 550 ms, shared by every `@parcel/watcher` consumer (sized above the watcher's 500 ms coalescing cap) |
 | `drainSubscriptions` | `lib/build/helpers/watchSubscriptions.js` | Unsubscribes a list of subscriptions in parallel (`Promise.allSettled`), returns the failures. Used by both watchers' `destroy()` and BuildServer's recovery re-subscribe |
-| `fileWatcher` | `lib/build/helpers/fileWatcher.js` | Watcher-backend facade. Exposes a `subscribe()` matching `@parcel/watcher`'s contract and picks a backend once per process: `UI5_WATCH_MODE=polling\|native` forces the choice, otherwise it auto-detects containers (`/.dockerenv`, `/run/.containerenv`, PID 1 cgroup) and uses polling there. Also falls back to polling if the native `@parcel/watcher` binding cannot load. All three watchers subscribe through this facade rather than importing `@parcel/watcher` directly |
+| `fileWatcher` | `lib/build/helpers/fileWatcher.js` | Watcher-backend facade. Exposes a `subscribe()` matching `@parcel/watcher`'s contract and picks a backend once per process: `UI5_WATCH_MODE=polling\|native` forces the choice, otherwise it auto-detects containers (`/.dockerenv`, `/run/.containerenv`, PID 1 cgroup) and uses polling there. Also falls back to polling if the native `@parcel/watcher` binding cannot load. `UI5_WATCH_MODE=off` disables watching entirely: `subscribe()` returns an inert subscription (callback never invoked, `unsubscribe` a no-op) so no backend loads, for CI where sources don't change. The memoized decision is a mode string exposed via `shouldUsePolling()` and `isWatchingDisabled()`. All three watchers subscribe through this facade rather than importing `@parcel/watcher` directly |
 | `pollingWatcher` | `lib/build/helpers/pollingWatcher.js` | Pure-JS polling backend. Walks the tree and diffs an `{mtimeMs, size}` snapshot every 250 ms (`DEFAULT_POLL_INTERVAL_MS`), emitting the same `{type, path}` events as the native backend. Needed on bind-mounted container volumes where inotify misses writes made from outside the container |
 | `TaskRunner` | `lib/build/TaskRunner.js` | Task composition, execution loop, abort handling |
 | `Cache` enum | `lib/build/cache/Cache.js` | Cache mode constants: `Default`, `Force`, `ReadOnly`, `Off` (CLI `--cache` option) |

internal/documentation/docs/pages/Troubleshooting.md

@@ -126,6 +126,16 @@ If you encounter this problem in your container-based development setup, try set
 Polling reads the watched files on an interval, so it reports changes regardless of where they originate, at the cost of more CPU than the event-based native watcher. Use it only when the native watcher fails to detect your file changes.
 :::
 
+### Disabling File Watching in CI
+
+`ui5 serve` watches the project's files and rebuilds on change. In CI and other environments where the sources do not change while the server runs, that watching is pure overhead. The polling watcher is the worst case: it walks the source tree on an interval, and it is the default inside containers, where CI commonly runs.
+
+Set `UI5_WATCH_MODE` to `off` to disable file watching entirely. Source changes will not trigger rebuilds or live reload, and neither the native nor the polling watcher is started.
+
+```sh
+UI5_WATCH_MODE=off ui5 serve
+```
+
 ### Changing UI5 CLI's Data Directory
 
 UI5 CLI's data directory is by default at `~/.ui5`. It's the place where the framework artifacts are stored.

packages/project/lib/build/helpers/fileWatcher.js

@@ -23,6 +23,12 @@ const log = getLogger("build:helpers:fileWatcher");
  * contained: when the native backend is selected but cannot load, subscribe() falls back to polling,
  * which needs no native code.
  *
+ * <code>UI5_WATCH_MODE=off</code> disables watching entirely: subscribe() returns an inert
+ * subscription that never invokes its callback, so no backend is loaded and no filesystem is polled.
+ * This is meant for CI and other environments where sources do not change while the server runs and
+ * the watching overhead (especially the polling backend's tree walk on container volumes) is pure
+ * cost.
+ *
  * @private
  * @module @ui5/project/build/helpers/fileWatcher
  */
@@ -34,8 +40,9 @@ const CONTAINER_MARKER_FILES = ["/.dockerenv", "/run/.containerenv"];
 // cgroup path fragments that appear only when PID 1 runs under a container runtime.
 const rContainerCgroup = /\b(?:docker|libpod|containerd|kubepods)\b/;
 
-// Memoized backend decision. Computed once per process and shared by every subscribe() call.
-let usePolling = null;
+// Memoized backend decision, one of "native" | "polling" | "off". Computed once per process and
+// shared by every subscribe() call.
+let watchBackend = null;
 
 // Memoized native backend: the @parcel/watcher module once loaded, or null when it could not load
 // (e.g. no prebuilt binary for this platform). nativeBackendLoaded guards the one load attempt so a
@@ -44,25 +51,44 @@ let nativeBackend = null;
 let nativeBackendLoaded = false;
 
 /**
- * Decides whether to poll, once per process. <code>UI5_WATCH_MODE=polling|native</code> forces the
- * choice; otherwise polling is the default inside a container and the native backend is the default
- * elsewhere.
+ * Decides the watcher backend, once per process. <code>UI5_WATCH_MODE=off|polling|native</code>
+ * forces the choice; otherwise polling is the default inside a container and the native backend is
+ * the default elsewhere.
  *
+ * @returns {"native"|"polling"|"off"} The selected backend
+ */
+function getWatchBackend() {
+	return (watchBackend ??= decideBackend());
+}
+
+/**
  * @returns {boolean} True when the polling backend should be used
  */
 export function shouldUsePolling() {
-	return (usePolling ??= decideBackend());
+	return getWatchBackend() === "polling";
+}
+
+/**
+ * @returns {boolean} True when file watching is disabled (<code>UI5_WATCH_MODE=off</code>)
+ */
+export function isWatchingDisabled() {
+	return getWatchBackend() === "off";
 }
 
 function decideBackend() {
 	const mode = process.env.UI5_WATCH_MODE;
+	if (mode === "off") {
+		log.info(`UI5_WATCH_MODE=off: file watching is disabled. Source changes will not trigger ` +
+			`rebuilds or live reload while the server runs.`);
+		return "off";
+	}
 	if (mode === "polling") {
 		log.verbose(`UI5_WATCH_MODE=polling: using polling file watcher`);
-		return true;
+		return "polling";
 	}
 	if (mode === "native") {
 		log.verbose(`UI5_WATCH_MODE=native: using native file watcher`);
-		return false;
+		return "native";
 	}
 	if (mode) {
 		log.warn(`Ignoring invalid UI5_WATCH_MODE '${mode}', detecting file watcher backend`);
@@ -72,10 +98,10 @@ function decideBackend() {
 		log.info(`Detected a container environment: using the polling file watcher. Inside a ` +
 			`container, inotify often does not report changes made to a mounted volume from outside ` +
 			`the container. Set UI5_WATCH_MODE=native to force the native watcher.`);
-		return true;
+		return "polling";
 	}
 	log.verbose(`No container environment detected, using the native file watcher`);
-	return false;
+	return "native";
 }
 
 // Reports whether the process runs inside a container. Checks the marker files the runtimes drop
@@ -98,7 +124,9 @@ function isRunningInContainer() {
 
 /**
  * Subscribes to filesystem changes below <code>dir</code>, matching
- * <code>@parcel/watcher</code>'s <code>subscribe</code> signature and return contract.
+ * <code>@parcel/watcher</code>'s <code>subscribe</code> signature and return contract. When watching
+ * is disabled (<code>UI5_WATCH_MODE=off</code>), the returned subscription is inert: its callback is
+ * never invoked and <code>unsubscribe</code> is a no-op.
  *
  * @param {string} dir Directory to watch
  * @param {Function} callback Invoked as <code>(err, events)</code>, events being
@@ -111,6 +139,12 @@ function isRunningInContainer() {
  * @returns {Promise<{unsubscribe: Function}>} Resolves once the watcher is ready
  */
 export async function subscribe(dir, callback, opts = {}) {
+	if (isWatchingDisabled()) {
+		// Watching is off (UI5_WATCH_MODE=off). Return an inert subscription the caller tracks and
+		// unsubscribes exactly as a real one, but the callback is never invoked, so no backend loads
+		// and no rebuild or live reload is ever triggered.
+		return {unsubscribe: async () => {}};
+	}
 	if (!shouldUsePolling()) {
 		const native = await loadNativeBackend();
 		if (native) {

packages/project/test/lib/build/helpers/fileWatcher.js

@@ -125,6 +125,42 @@ test.serial("subscribe: polling backend is loaded and used when UI5_WATCH_MODE=p
 	}
 });
 
+test.serial("subscribe: returns an inert subscription when UI5_WATCH_MODE=off", async (t) => {
+	// Disabled mode must not load any backend. The native stub stands in as a tripwire: if subscribe()
+	// delegated, it would be called. The returned subscription is real enough to track and unsubscribe.
+	process.env.UI5_WATCH_MODE = "off";
+	const parcelSubscribe = sinon.stub().resolves({unsubscribe: sinon.stub().resolves()});
+	const watcher = await importWatcherWithParcel({
+		default: {subscribe: parcelSubscribe}, subscribe: parcelSubscribe,
+	});
+	try {
+		const cb = sinon.stub();
+		const subscription = await watcher.subscribe("/some/dir", cb, {ignore: ["**/x/**"]});
+
+		t.is(parcelSubscribe.callCount, 0, "no native backend is loaded when watching is disabled");
+		t.is(cb.callCount, 0, "the callback is never invoked");
+		t.is(typeof subscription.unsubscribe, "function", "returns a subscription with unsubscribe()");
+		await t.notThrowsAsync(subscription.unsubscribe(), "unsubscribe is a no-op that resolves");
+	} finally {
+		esmock.purge(watcher);
+	}
+});
+
+test.serial("isWatchingDisabled: true only for UI5_WATCH_MODE=off", async (t) => {
+	process.env.UI5_WATCH_MODE = "off";
+	let watcher = await importWatcher();
+	t.true(watcher.isWatchingDisabled(), "off disables watching");
+	t.false(watcher.shouldUsePolling(), "off is not polling");
+
+	process.env.UI5_WATCH_MODE = "polling";
+	watcher = await importWatcher();
+	t.false(watcher.isWatchingDisabled(), "polling does not disable watching");
+
+	process.env.UI5_WATCH_MODE = "native";
+	watcher = await importWatcher();
+	t.false(watcher.isWatchingDisabled(), "native does not disable watching");
+});
+
 test.serial("shouldUsePolling: UI5_WATCH_MODE forces the backend without inspecting the environment", async (t) => {
 	const existsSync = sinon.stub().returns(false);
 	process.env.UI5_WATCH_MODE = "polling";