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 UI5 CLI v5, the option `--cache-mode` (for commands `ui5 build` and `ui5 serve`) has been renamed to `--snapshot-cache`.
+
+When legacy `--cache-mode` is used, the behavior remains the same but a deprecation warning is logged. When both `--snapshot-cache` and `--cache-mode` are used, the `--snapshot-cache` flag always gets priority.
+
 ## 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,7 @@
 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 +86,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 the cache is 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 +120,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' is 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", // Use "defaultdescription" to allow undefined (needed for evaluation)
+			choices: ["Default", "Force", "Off"],
 		})
 		.option("experimental-css-variables", {
 			describe:
@@ -160,13 +190,13 @@ 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,
 		});
@@ -196,6 +226,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 the cache is 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' is 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", // Use "defaultdescription" to allow undefined (needed for evaluation)
+			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,
 		});

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

@@ -20,11 +20,14 @@ function getDefaultArgv() {
 		"createBuildManifest": false,
 		"dest": "./dist",
 		"clean-dest": false,
+		"cache": "Default",
 		"cleanDest": false,
 		"experimental-css-variables": false,
 		"experimentalCssVariables": false,
 		"cache-mode": "Default",
 		"cacheMode": "Default",
+		"snapshot-cache": "Default",
+		"snapshotCache": "Default",
 		"output-style": "Default",
 		"$0": "ui5"
 	};
@@ -35,6 +38,7 @@ function getDefaultBuilderArgs() {
 		cacheDir: path.join("/root/path", ".ui5-cache"),
 		destPath: "./dist",
 		cleanDest: false,
+		cache: "Default",
 		dependencyIncludes: {
 			includeAllDependencies: false,
 			includeDependency: undefined,
@@ -133,15 +137,15 @@ test.serial("ui5 build --framework-version", async (t) => {
 			versionOverride: "1.99.0",
 			workspaceConfigPath: undefined,
 			workspaceName: undefined,
-			cacheMode: "Default",
+			snapshotCache: "Default",
 		}, "generateProjectGraph.graphFromPackageDependencies got called with expected arguments"
 	);
 });
 
-test.serial("ui5 build --cache-mode", async (t) => {
+test.serial("ui5 build --snapshot-cache", async (t) => {
 	const {build, argv, graphFromPackageDependenciesStub} = t.context;
 
-	argv.cacheMode = "Off";
+	argv.snapshotCache = "Off";
 
 	await build.handler(argv);
 
@@ -152,7 +156,7 @@ test.serial("ui5 build --cache-mode", async (t) => {
 			versionOverride: undefined,
 			workspaceConfigPath: undefined,
 			workspaceName: undefined,
-			cacheMode: "Off",
+			snapshotCache: "Off",
 		}, "generateProjectGraph.graphFromPackageDependencies got called with expected arguments"
 	);
 });
@@ -171,7 +175,7 @@ test.serial("ui5 build --config", async (t) => {
 			versionOverride: undefined,
 			workspaceConfigPath: undefined,
 			workspaceName: undefined,
-			cacheMode: "Default",
+			snapshotCache: "Default",
 		}, "generateProjectGraph.graphFromPackageDependencies got called with expected arguments"
 	);
 });
@@ -190,7 +194,7 @@ test.serial("ui5 build --workspace", async (t) => {
 			versionOverride: undefined,
 			workspaceConfigPath: undefined,
 			workspaceName: "dolphin",
-			cacheMode: "Default",
+			snapshotCache: "Default",
 		}, "generateProjectGraph.graphFromPackageDependencies got called with expected arguments"
 	);
 });
@@ -209,7 +213,7 @@ test.serial("ui5 build --no-workspace", async (t) => {
 			versionOverride: undefined,
 			workspaceConfigPath: undefined,
 			workspaceName: null,
-			cacheMode: "Default",
+			snapshotCache: "Default",
 		}, "generateProjectGraph.graphFromPackageDependencies got called with expected arguments"
 	);
 });
@@ -229,7 +233,7 @@ test.serial("ui5 build --workspace-config", async (t) => {
 			versionOverride: undefined,
 			workspaceConfigPath: fakePath,
 			workspaceName: undefined,
-			cacheMode: "Default",
+			snapshotCache: "Default",
 		}, "generateProjectGraph.graphFromPackageDependencies got called with expected arguments"
 	);
 });
@@ -247,7 +251,7 @@ test.serial("ui5 build --dependency-definition", async (t) => {
 			filePath: "dependencies.yaml",
 			rootConfigPath: undefined,
 			versionOverride: undefined,
-			cacheMode: "Default",
+			snapshotCache: "Default",
 		}, "generateProjectGraph.graphFromStaticFile got called with expected arguments"
 	);
 });
@@ -266,7 +270,7 @@ test.serial("ui5 build --dependency-definition --config", async (t) => {
 			filePath: "dependencies.yaml",
 			rootConfigPath: "ui5-test.yaml",
 			versionOverride: undefined,
-			cacheMode: "Default",
+			snapshotCache: "Default",
 		}, "generateProjectGraph.graphFromStaticFile got called with expected arguments"
 	);
 });
@@ -286,7 +290,7 @@ test.serial("ui5 build --dependency-definition --config --framework-version", as
 			filePath: "dependencies.yaml",
 			rootConfigPath: "ui5-test.yaml",
 			versionOverride: "1.99.0",
-			cacheMode: "Default",
+			snapshotCache: "Default",
 		}, "generateProjectGraph.graphFromStaticFile got called with expected arguments"
 	);
 });