feat: Offer --cache option to control cache mode (Incremental Build)

internal/documentation/docs/updates/migrate-v5.md

@@ -15,6 +15,8 @@ Or update your global install via: `npm i --global @ui5/cli@next`
 
 - **@ui5/cli: `ui5 init` defaults to Specification Version 5.0**
 
+- **Rename: Command Option `--cache-mode` is now `--snapshot-cache`**
+
 
 ## Node.js and npm Version Support
 
@@ -27,6 +29,12 @@ UI5 CLI 5.x introduces **Specification Version 5.0**, which enables the new Comp
 
 Projects using older **Specification Versions** are expected to be **fully compatible with UI5 CLI v5**.
 
+## Rename of Command Option
+
+With Specification Version 5.0, the option `--cache-mode` (for commands `ui5 build` and `ui5 serve`) has been renamed to `--snapshot-cache`.
+
+The behavior remains the same. When `--cache-mode` is used, a deprecation warning is logged and `--snapshot-cache` is set to `Default`.
+
 ## UI5 CLI Init Command
 
 The `ui5 init` command now generates projects with Specification Version 5.0 by default.

packages/cli/lib/cli/commands/build.js

@@ -1,5 +1,6 @@
 import baseMiddleware from "../middlewares/base.js";
-import path from "node:path";
+import {getLogger} from "@ui5/logger";
+const log = getLogger("cli:commands:build");
 
 const build = {
 	command: "build",
@@ -84,6 +85,17 @@ build.builder = function(cli) {
 			default: false,
 			type: "boolean"
 		})
+		.option("cache", {
+			describe:
+				"Cache mode to use for building UI5 projects. " +
+				"The 'Default' behavior is to always use the cache if available. 'Force' uses the cache only " +
+				"(if it's unavailable or invalid, the build fails). 'ReadOnly' does not create or update any " +
+				"cache but makes use of a cache if available. 'Off' does not use any cache and always triggers " +
+				"a rebuild of the project",
+			type: "string",
+			default: "Default",
+			choices: ["Default", "Force", "ReadOnly", "Off"],
+		})
 		.option("create-build-manifest", {
 			describe: "Store build metadata in a '.ui5' directory in the build destination, " +
 				"allowing reuse of the build result in other builds",
@@ -107,13 +119,30 @@ build.builder = function(cli) {
 			type: "string"
 		})
 		.option("cache-mode", {
+			// Deprecated
+			hidden: true,
+			describe:
+				"As of UI5 CLI version 5, renamed to '--snapshot-cache'. " +
+				"Use '--snapshot-cache' to control this behavior.",
+			type: "string",
+			choices: ["Default", "Force", "Off"],
+		})
+		.coerce("cache-mode", (opt) => {
+			// Log a warning if this option is used
+			if (opt !== undefined) {
+				log.warn("As of UI5 CLI version 5, '--cache-mode' was renamed to '--snapshot-cache'. " +
+					"Use '--snapshot-cache' to control this behavior.");
+			}
+			return opt;
+		})
+		.option("snapshot-cache", {
 			describe:
 				"Cache mode to use when consuming SNAPSHOT versions of framework dependencies. " +
 				"The 'Default' behavior is to invalidate the cache after 9 hours. 'Force' uses the cache only and " +
 				"does not create any requests. 'Off' invalidates any existing cache and updates from the repository",
 			type: "string",
-			default: "Default",
-			choices: ["Default", "Force", "Off"]
+			defaultDescription: "Default",
+			choices: ["Default", "Force", "Off"],
 		})
 		.option("experimental-css-variables", {
 			describe:
@@ -160,21 +189,20 @@ async function handleBuild(argv) {
 			filePath: argv.dependencyDefinition,
 			rootConfigPath: argv.config,
 			versionOverride: argv.frameworkVersion,
-			cacheMode: argv.cacheMode,
+			snapshotCache: argv.snapshotCache ?? argv.cacheMode ?? "Default", // Use cacheMode as fallback
 		});
 	} else {
 		graph = await graphFromPackageDependencies({
 			rootConfigPath: argv.config,
 			versionOverride: argv.frameworkVersion,
-			cacheMode: argv.cacheMode,
+			snapshotCache: argv.snapshotCache ?? argv.cacheMode ?? "Default", // Use cacheMode as fallback
 			workspaceConfigPath: argv.workspaceConfig,
 			workspaceName: argv.workspace === false ? null : argv.workspace,
 		});
 	}
 	const buildSettings = graph.getRoot().getBuilderSettings() || {};
 	await graph.build({
 		graph,
-		cacheDir: path.join(graph.getRoot().getRootPath(), ".ui5-cache"),
 		destPath: argv.dest,
 		cleanDest: argv["clean-dest"],
 		createBuildManifest: argv["create-build-manifest"],
@@ -196,6 +224,7 @@ async function handleBuild(argv) {
 		excludedTasks: argv["exclude-task"],
 		cssVariables: argv["experimental-css-variables"],
 		outputStyle: argv["output-style"],
+		cache: argv["cache"],
 	});
 }
 

packages/cli/lib/cli/commands/serve.js

@@ -2,6 +2,8 @@ import path from "node:path";
 import os from "node:os";
 import chalk from "chalk";
 import baseMiddleware from "../middlewares/base.js";
+import {getLogger} from "@ui5/logger";
+const log = getLogger("cli:commands:serve");
 
 // Serve
 const serve = {
@@ -61,19 +63,47 @@ serve.builder = function(cli) {
 			default: false,
 			type: "boolean"
 		})
+		.option("cache", {
+			describe:
+				"Cache mode to use for building UI5 projects. " +
+				"The 'Default' behavior is to always use the cache if available. 'Force' uses the cache only " +
+				"(if it's unavailable or invalid, the build fails). 'Read-only' does not create or update any " +
+				"cache but makes use of a cache if available. 'Off' does not use any cache and always triggers " +
+				"a rebuild of the project",
+			type: "string",
+			default: "Default",
+			choices: ["Default", "Force", "ReadOnly", "Off"],
+		})
 		.option("framework-version", {
 			describe: "Overrides the framework version defined by the project. " +
 				"Takes the same value as the version part of \"ui5 use\"",
 			type: "string"
 		})
 		.option("cache-mode", {
+			// Deprecated
+			hidden: true,
+			describe:
+				"As of UI5 CLI version 5, renamed to '--snapshot-cache'. " +
+				"Use '--snapshot-cache' to control this behavior.",
+			type: "string",
+			choices: ["Default", "Force", "Off"],
+		})
+		.coerce("cache-mode", (opt) => {
+			// Log a warning if this option is used
+			if (opt !== undefined) {
+				log.warn("As of UI5 CLI version 5, '--cache-mode' was renamed to '--snapshot-cache'. " +
+					"Use '--snapshot-cache' to control this behavior.");
+			}
+			return opt;
+		})
+		.option("snapshot-cache", {
 			describe:
 				"Cache mode to use when consuming SNAPSHOT versions of framework dependencies. " +
 				"The 'Default' behavior is to invalidate the cache after 9 hours. 'Force' uses the cache only and " +
 				"does not create any requests. 'Off' invalidates any existing cache and updates from the repository",
 			type: "string",
-			default: "Default",
-			choices: ["Default", "Force", "Off"]
+			defaultDescription: "Default",
+			choices: ["Default", "Force", "Off"],
 		})
 		.example("ui5 serve", "Start a web server for the current project")
 		.example("ui5 serve --h2", "Enable the HTTP/2 protocol for the web server (requires SSL certificate)")
@@ -95,13 +125,13 @@ serve.handler = async function(argv) {
 			filePath: argv.dependencyDefinition,
 			rootConfigPath: argv.config,
 			versionOverride: argv.frameworkVersion,
-			cacheMode: argv.cacheMode,
+			snapshotCache: argv.snapshotCache ?? argv.cacheMode ?? "Default", // Use cacheMode as fallback
 		});
 	} else {
 		graph = await graphFromPackageDependencies({
 			rootConfigPath: argv.config,
 			versionOverride: argv.frameworkVersion,
-			cacheMode: argv.cacheMode,
+			snapshotCache: argv.snapshotCache ?? argv.cacheMode ?? "Default", // Use cacheMode as fallback
 			workspaceConfigPath: argv.workspaceConfig,
 			workspaceName: argv.workspace === false ? null : argv.workspace,
 		});
@@ -137,7 +167,8 @@ serve.handler = async function(argv) {
 		cert: argv.h2 ? argv.cert : undefined,
 		key: argv.h2 ? argv.key : undefined,
 		sendSAPTargetCSP: !!argv.sapCspPolicies,
-		serveCSPReports: !!argv.serveCspReports
+		serveCSPReports: !!argv.serveCspReports,
+		cache: argv.cache,
 	};
 
 	if (serverConfig.h2) {

packages/cli/lib/cli/commands/tree.js

@@ -28,7 +28,13 @@ tree.builder = function(cli) {
 				"Takes the same value as the version part of \"ui5 use\"",
 			type: "string"
 		})
-		.option("cache-mode", {
+		.hide("cache-mode", {
+			describe:
+				"As of UI5 CLI version 5, renamed to '--snapshot-cache'. " +
+				"Use '--snapshot-cache' to control this behavior.",
+			type: "string",
+		})
+		.option("snapshot-cache", {
 			describe:
 				"Cache mode to use when consuming SNAPSHOT versions of framework dependencies. " +
 				"The 'Default' behavior is to invalidate the cache after 9 hours. 'Force' uses the cache only and " +
@@ -51,13 +57,13 @@ tree.handler = async function(argv) {
 		graph = await graphFromStaticFile({
 			filePath: argv.dependencyDefinition,
 			versionOverride: argv.frameworkVersion,
-			cacheMode: argv.cacheMode,
+			snapshotCache: argv.snapshotCache,
 		});
 	} else {
 		graph = await graphFromPackageDependencies({
 			rootConfigPath: argv.config,
 			versionOverride: argv.frameworkVersion,
-			cacheMode: argv.cacheMode,
+			snapshotCache: argv.snapshotCache,
 			workspaceConfigPath: argv.workspaceConfig,
 			workspaceName: argv.workspace === false ? null : argv.workspace,
 		});