feat(cli): Add ui5 cache clean command

internal/documentation/docs/pages/Troubleshooting.md

@@ -20,28 +20,43 @@ UI5 CLI stores several kinds of data under your user's home directory in `~/.ui5
 | `~/.ui5/buildCache/` | Build cache used by `ui5 build` and `ui5 serve` (see [Build Cache Control](./Builder.md#build-cache-control)) | Yes — rebuilt on next `ui5 build` / `ui5 serve` |
 | `~/.ui5/server/` | Locally generated SSL certificate and private key for HTTPS / HTTP/2 mode | Yes — regenerated on next HTTPS server start; the new certificate must be re-trusted |
 
-::: warning
-Only remove these directories when no UI5 CLI process and no `@ui5/*` API consumer is actively running. Deleting files that are in use can cause running builds or servers to fail or produce inconsistent results.
-:::
-
 #### Resolution
 
-To free disk space, remove the relevant subdirectory.
+Use the dedicated cache clean command, which removes all cached data:
+
+```sh
+ui5 cache clean
+```
 
-To only remove framework downloads:
+For a detailed preview and grouped cleanup summary, use the `--verbose` flag:
 
 ```sh
-rm -rf ~/.ui5/framework/
+ui5 cache clean --verbose
 ```
 
-To only remove the build cache:
+To skip the confirmation prompt (for example in CI environments), use the `--force` flag.
+In non-verbose mode with `--force`, the command runs completely silent:
 
 ```sh
-rm -rf ~/.ui5/buildCache/
+ui5 cache clean --force
 ```
 
+The command removes the following cached data:
+- **UI5 Framework packages** — downloaded UI5 library files (`~/.ui5/framework/`)
+- **Build cache** — build data (`~/.ui5/buildCache/`)
+
+If a previous `ui5 cache clean` was interrupted (for example, because the process was killed or the system crashed), the command also detects and removes any leftover data from that interrupted operation. This data is listed as separate entries:
+- **Stale UI5 Framework packages** — incomplete framework directories left over from a previously interrupted cleanup (`~/.ui5/_framework_to_delete_*/`)
+- **Stale build cache** — freed database pages not yet reclaimed during a previously interrupted cleanup
+
+Any required framework dependencies will be re-downloaded during the next UI5 CLI invocation.
+
 ::: info
-If you have configured a custom data directory via `UI5_DATA_DIR` or `ui5 config set ui5DataDir`, replace `~/.ui5/` with that path. See [Changing UI5 CLI's Data Directory](#changing-ui5-cli-s-data-directory).
+If you have configured a custom data directory via `UI5_DATA_DIR` or `ui5 config set ui5DataDir`, the `ui5 cache clean` command will clean up that location instead of the default `~/.ui5/`. See [Changing UI5 CLI's Data Directory](#changing-ui5-cli-s-data-directory).
+:::
+
+::: warning
+Only remove these directories, or run `ui5 cache clean`, when no UI5 CLI process and no `@ui5/*` API consumer is actively running. Running `ui5 cache clean` while `ui5 build` or `ui5 serve` is in progress can break the running process and lead to failed or inconsistent results.
 :::
 
 ## Environment Variables

packages/cli/lib/cli/commands/cache.js

@@ -0,0 +1,182 @@
+import chalk from "chalk";
+import path from "node:path";
+import os from "node:os";
+import process from "node:process";
+import {isLogLevelEnabled} from "@ui5/logger";
+import baseMiddleware from "../middlewares/base.js";
+import Configuration from "@ui5/project/config/Configuration";
+import FrameworkCache from "@ui5/project/internal/ui5Framework/cache";
+import CacheManager from "@ui5/project/internal/build/cache/CacheManager";
+import {
+	CACHE_CLEAN_HELP_USAGE,
+	displayCacheCleanWarning,
+	displayCacheInfo,
+	displayCleanupResult,
+} from "./helpers/cacheOutput.js";
+
+const cacheCommand = {
+	command: "cache",
+	describe: "Manage the UI5 CLI cache (downloaded framework packages and build data)",
+	middlewares: [baseMiddleware],
+	handler: handleCache
+};
+
+cacheCommand.builder = function(cli) {
+	return cli
+		.demandCommand(1, "Command required. Available command is 'clean'")
+		.command("clean", "Remove all cached UI5 data", {
+			handler: handleCache,
+			builder: function(yargs) {
+				return yargs
+					.usage(CACHE_CLEAN_HELP_USAGE)
+					.option("force", {
+						alias: "f",
+						describe: "Skip the confirmation prompt, e.g. for use in CI pipelines",
+						default: false,
+						type: "boolean",
+					})
+					.example("$0 cache clean",
+						"Remove all cached UI5 data after confirmation")
+					.example("$0 cache clean --force",
+						"Remove all cached UI5 data without confirmation (e.g. in CI scenarios)")
+					.example("UI5_DATA_DIR=/custom/path $0 cache clean",
+						"Remove cached data from a non-default UI5 data directory");
+			},
+			middlewares: [baseMiddleware],
+		});
+};
+/**
+ * Prompt the user for confirmation before proceeding with cache cleanup.
+ *
+ * @param {Yargs.Arguments} argv
+ * @returns {Promise<boolean>} Confirmation result
+ */
+async function getConfirmation(argv) {
+	if (argv.force) {
+		return true;
+	}
+	displayCacheCleanWarning();
+	const {default: yesno} = await import("yesno");
+	return yesno({
+		question: "Proceed with cache cleanup? (y/N)",
+		defaultValue: false
+	});
+}
+
+async function resolveCacheUi5DataDir() {
+	// TODO: Consolidate ui5DataDir resolution once PR #1456 follow-up cleanup is done.
+	// Keep behavior aligned with existing main-branch resolution order.
+	let ui5DataDir = process.env.UI5_DATA_DIR;
+	if (!ui5DataDir) {
+		const config = await Configuration.fromFile();
+		ui5DataDir = config.getUi5DataDir();
+	}
+	if (ui5DataDir) {
+		return path.resolve(process.cwd(), ui5DataDir);
+	}
+	return path.join(os.homedir(), ".ui5");
+}
+
+function withAbsPath(entries, ui5DataDir) {
+	return entries.map((entry) => {
+		return {...entry, absPath: getAbsPath(ui5DataDir, entry)};
+	});
+}
+
+function getAbsPath(ui5DataDir, cacheEntry) {
+	if (!cacheEntry?.path) {
+		return null;
+	}
+	return path.join(ui5DataDir, cacheEntry.path);
+}
+
+async function handleCache(argv) {
+	const ui5DataDir = await resolveCacheUi5DataDir();
+	const isVerbose = isLogLevelEnabled("verbose");
+
+	if (isVerbose) {
+		// logger.verbose pollutes output with framework noise.
+		process.stderr.write(`Checking cache at ${chalk.bold(ui5DataDir)} …\n`);
+	}
+
+	const [frameworkInfo, buildInfo] = await Promise.all([
+		FrameworkCache.getCacheInfo(ui5DataDir),
+		CacheManager.getCacheInfo(ui5DataDir),
+	]);
+
+	const hasActiveCache = Boolean(frameworkInfo || buildInfo);
+	let staleInfo = [];
+	let buildStaleInfo = [];
+
+	if (isVerbose || !hasActiveCache) {
+		[staleInfo, buildStaleInfo] = await Promise.all([
+			FrameworkCache.getAdditionalCacheInfo(ui5DataDir),
+			CacheManager.getAdditionalCacheInfo(ui5DataDir),
+		]);
+	}
+
+	const hasStaleCache = staleInfo.length > 0 || buildStaleInfo.length > 0;
+
+	if (!hasActiveCache && !hasStaleCache) {
+		if (isVerbose) {
+			process.stderr.write(`${chalk.italic("Nothing to clean")}\n`);
+		}
+		return;
+	}
+
+	if (isVerbose) {
+		await displayCacheInfo({
+			frameworkInfo,
+			buildInfo,
+			frameworkAbsPath: getAbsPath(ui5DataDir, frameworkInfo),
+			buildAbsPath: getAbsPath(ui5DataDir, buildInfo),
+			buildPreSize: buildInfo?.size ?? 0,
+			staleInfo: withAbsPath(staleInfo, ui5DataDir),
+			buildAdditionalInfo: withAbsPath(buildStaleInfo, ui5DataDir),
+		});
+	}
+
+	const confirmed = await getConfirmation(argv);
+	if (!confirmed) {
+		if (isVerbose) {
+			process.stderr.write(`${chalk.italic("Cancelled")}\n`);
+		}
+		return;
+	}
+
+	if (isVerbose) {
+		// Get fresh build stale info to distinguish
+		// between active and stale build cache after cleanup.
+		buildStaleInfo = await CacheManager.getAdditionalCacheInfo(ui5DataDir);
+	}
+
+	const [frameworkCleanupResult, buildCleanupResult] = await Promise.all([
+		FrameworkCache.cleanCache(ui5DataDir),
+		CacheManager.cleanCache(ui5DataDir),
+	]);
+
+	const [additionalFrameworkCleanupResult, buildStaleCleanupResult] = await Promise.all([
+		FrameworkCache.cleanAdditional(ui5DataDir),
+		CacheManager.cleanAdditional(ui5DataDir),
+	]);
+
+	if (isVerbose) {
+		const staleBuildCleanupResult = buildStaleInfo?.length > 0 ?
+			buildStaleCleanupResult : [];
+		const cleanedStaleFramework = withAbsPath(additionalFrameworkCleanupResult, ui5DataDir);
+		const cleanedStaleBuild = withAbsPath(staleBuildCleanupResult, ui5DataDir);
+		const frameworkResultAbsPath = getAbsPath(ui5DataDir, frameworkCleanupResult);
+		const buildResultAbsPath = getAbsPath(ui5DataDir, buildCleanupResult);
+		await displayCleanupResult({
+			frameworkResult: frameworkCleanupResult,
+			buildResult: buildCleanupResult,
+			frameworkAbsPath: frameworkResultAbsPath,
+			buildAbsPath: buildResultAbsPath,
+			buildSize: buildCleanupResult?.size ?? 0,
+			staleInfoWithAbsPaths: cleanedStaleFramework,
+			buildAdditionalResult: cleanedStaleBuild,
+		});
+	}
+}
+
+export default cacheCommand;