feat: Clean cache command

internal/documentation/docs/pages/Troubleshooting.md

@@ -12,36 +12,30 @@ Please follow our [Contribution Guidelines](https://github.com/UI5/cli/blob/main
 ## UI5 Project
 ### `~/.ui5` Taking too Much Disk Space
 
-UI5 CLI stores several kinds of data under your user's home directory in `~/.ui5/`:
-
-| Directory | Contents | Safe to delete? |
-| ---- | ---- | ---- |
-| `~/.ui5/framework/` | Downloaded UI5 framework dependencies (one copy per version) | Yes — re-downloaded on next invocation |
-| `~/.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.
-:::
+There are possibly many versions of UI5 framework dependencies installed on your system, taking a large amount of disk space.
 
 #### Resolution
 
-To free disk space, remove the relevant subdirectory.
-
-To only remove framework downloads:
+Use the dedicated cache clean command, which safely removes all cached data:
 
 ```sh
-rm -rf ~/.ui5/framework/
+ui5 cache clean
 ```
 
-To only remove the build cache:
+This will display the cache location, the amount of data that will be removed, and ask for confirmation before proceeding. To skip the confirmation prompt (e.g. in CI environments), use the `--yes` flag:
 
 ```sh
-rm -rf ~/.ui5/buildCache/
+ui5 cache clean --yes
 ```
 
+The command removes two types of cached data:
+- **UI5 Framework packages** — downloaded UI5 library files (`~/.ui5/framework/`)
+- **Build cache (DB)** — build data (`~/.ui5/buildCache/`)
+
+Any missing framework dependencies will be downloaded again 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 `ui5DataDir`, the cache will be cleaned from that location instead of `~/.ui5`. See [Changing UI5 CLI's Data Directory](#changing-ui5-clis-data-directory) below.
 :::
 
 ## Environment Variables

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

@@ -0,0 +1,260 @@
+import chalk from "chalk";
+import path from "node:path";
+import process from "node:process";
+import baseMiddleware from "../middlewares/base.js";
+import {resolveUi5DataDir} from "@ui5/project/utils/dataDir";
+import {getLockDir, hasActiveLocks} from "@ui5/project/utils/lock";
+import * as frameworkCache from "@ui5/project/ui5Framework/cache";
+import CacheManager from "@ui5/project/build/cache/CacheManager";
+
+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
+					.option("yes", {
+						alias: "y",
+						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 confirming the prompt")
+					.example("$0 cache clean --yes",
+						"Remove all cached UI5 data without confirmation (e.g. in CI)")
+					.example("UI5_DATA_DIR=/custom/path $0 cache clean",
+						"Remove cached data from a non-default UI5 data directory")
+					.epilogue(
+						"The cache is stored in the UI5 data directory (default: ~/.ui5).\n" +
+						"Override the location with the UI5_DATA_DIR environment variable or\n" +
+						"the 'ui5DataDir' configuration option (see 'ui5 config --help').\n\n" +
+						"Two cache types are removed:\n" +
+						"  UI5 Framework packages  Downloaded UI5 library files " +
+							"(~/.ui5/framework/)\n" +
+						"  Build cache (DB)        build data " +
+							"(~/.ui5/buildCache/)"
+					);
+			},
+			middlewares: [baseMiddleware],
+		});
+};
+
+const LABEL_FRAMEWORK = "UI5 Framework packages";
+const LABEL_BUILD = "Build cache (DB)";
+// Pad labels to equal width for two-column alignment
+const LABEL_WIDTH = Math.max(LABEL_FRAMEWORK.length, LABEL_BUILD.length);
+
+/**
+ * Format a byte size as a human-readable string.
+ *
+ * @param {number} bytes Size in bytes
+ * @returns {string} Formatted size string
+ */
+function formatSize(bytes) {
+	if (bytes < 1024) {
+		return `${bytes} B`;
+	} else if (bytes < 1024 * 1024) {
+		return `${(bytes / 1024).toFixed(1)} KB`;
+	} else if (bytes < 1024 * 1024 * 1024) {
+		return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	}
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+/**
+ * Format framework cache stats as a human-readable detail string.
+ * E.g. "1,189 versions of 155 libraries" or "1 version of 1 library".
+ *
+ * @param {number} libraryCount
+ * @param {number} versionCount
+ * @returns {string}
+ */
+function formatFrameworkStats(libraryCount, versionCount) {
+	const v = `${versionCount.toLocaleString("en-US")} ${versionCount === 1 ? "version" : "versions"}`;
+	const l = `${libraryCount.toLocaleString("en-US")} ${libraryCount === 1 ? "library" : "libraries"}`;
+	return `${v} of ${l}`;
+}
+
+/**
+ * Pad a label to the shared column width.
+ *
+ * @param {string} label
+ * @returns {string}
+ */
+function padLabel(label) {
+	return label.padEnd(LABEL_WIDTH);
+}
+
+/**
+ * Display information about the cached data that will be removed,
+ * including the absolute paths and details about the framework and build caches.
+ *
+ * @param {*} data
+ * @param {object} data.frameworkInfo
+ * @param {object} data.buildInfo
+ * @param {string} data.frameworkAbsPath
+ * @param {string} data.buildAbsPath
+ * @param {number} data.buildPreSize
+ */
+async function displayCacheInfo({
+	frameworkInfo,
+	buildInfo,
+	frameworkAbsPath,
+	buildAbsPath,
+	buildPreSize,
+}) {
+	// Display items that will be removed
+	process.stderr.write(chalk.bold("\nThe following cached data will be removed:\n\n"));
+	if (frameworkInfo) {
+		const detail = formatFrameworkStats(frameworkInfo.libraryCount, frameworkInfo.versionCount);
+		process.stderr.write(
+			`  ${chalk.yellow("•")} ${padLabel(LABEL_FRAMEWORK)}   ${frameworkAbsPath}   (${detail})\n`
+		);
+	}
+	if (buildInfo) {
+		const detail = buildPreSize > 0 ? formatSize(buildPreSize) : "";
+		process.stderr.write(
+			`  ${chalk.yellow("•")} ${padLabel(LABEL_BUILD)}   ${buildAbsPath}   (${detail})\n`
+		);
+	}
+	process.stderr.write("\n");
+}
+
+/**
+ * Display the result of the cache cleanup operation,
+ * including which caches were removed and their details.
+ *
+ * @param {object} data
+ * @param {object} data.frameworkResult
+ * @param {object} data.buildResult
+ * @param {string} data.frameworkAbsPath
+ * @param {string} data.buildAbsPath
+ * @param {number} data.buildPreSize
+ */
+async function displayCleanupResult({
+	frameworkResult,
+	buildResult,
+	frameworkAbsPath,
+	buildAbsPath,
+	buildPreSize,
+}) {
+	process.stderr.write("\n");
+	if (frameworkResult) {
+		const detail = formatFrameworkStats(
+			frameworkResult.libraryCount,
+			frameworkResult.versionCount,
+		);
+		process.stderr.write(
+			`${chalk.green("✓")} Removed ${chalk.bold(LABEL_FRAMEWORK)}` +
+				`   (${frameworkAbsPath} · ${detail})\n`,
+		);
+	}
+	if (buildResult) {
+		// Use pre-clean size so the number matches what was shown before confirmation
+		const detail = buildPreSize > 0 ? formatSize(buildPreSize) : "";
+		process.stderr.write(
+			`${chalk.green("✓")} Removed ${chalk.bold(LABEL_BUILD)}` +
+				`   (${buildAbsPath}${detail ? ` · ${detail}` : ""})\n`,
+		);
+	}
+
+	// Success summary
+	const cleaned = [];
+	if (frameworkResult) {
+		cleaned.push(LABEL_FRAMEWORK);
+	}
+	if (buildResult) {
+		cleaned.push(LABEL_BUILD);
+	}
+	process.stderr.write(
+		`\n${chalk.green("Success:")} Cleaned ${cleaned.join(" and ")}\n`,
+	);
+}
+
+/**
+ * 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.yes) {
+		return true;
+	}
+	const {default: yesno} = await import("yesno");
+	return yesno({
+		question: "Do you want to continue? (y/N)",
+		defaultValue: false
+	});
+}
+
+async function handleCache(argv) {
+	// Resolve UI5 data directory — uses the same resolution chain as ui5 build/serve:
+	// UI5_DATA_DIR env var → ui5DataDir config (~/.ui5rc) → default ~/.ui5
+	// Relative paths are resolved against process.cwd() (project root when invoked from the project).
+	const ui5DataDir = await resolveUi5DataDir();
+
+	// Abort early if a lock is active — before prompting the user
+	if (await hasActiveLocks(getLockDir(ui5DataDir))) {
+		process.stderr.write(
+			`${chalk.red("Error:")} A UI5 server or build process is currently running. ` +
+			"Cannot clean the cache while it is in use. " +
+			"Please stop all running 'ui5 serve' or wait for 'ui5 build' processes to finish.\n"
+		);
+		process.exitCode = 1;
+		return;
+	}
+
+	// Inform the user immediately — getPackageStats may take a moment on a large cache
+	process.stderr.write(`Checking cache at ${chalk.bold(ui5DataDir)} …\n`);
+
+	const frameworkInfo = await frameworkCache.getCacheInfo(ui5DataDir);
+	const buildInfo = await CacheManager.getCacheInfo(ui5DataDir);
+
+	// Compute absolute paths once — producers return relative sub-path segments
+	const frameworkAbsPath = frameworkInfo ? path.join(ui5DataDir, frameworkInfo.path) : null;
+	const buildAbsPath = buildInfo ? path.join(ui5DataDir, buildInfo.path) : null;
+	const buildPreSize = buildInfo?.size ?? 0;
+
+	if (!frameworkInfo && !buildInfo) {
+		process.stderr.write("Nothing to clean\n");
+		return;
+	}
+
+	await displayCacheInfo({
+		frameworkInfo,
+		buildInfo,
+		frameworkAbsPath,
+		buildAbsPath,
+		buildPreSize,
+	});
+
+	const confirmed = await getConfirmation(argv);
+	if (!confirmed) {
+		process.stderr.write("Cancelled\n");
+		return;
+	}
+
+	// Perform the actual cleanup (orchestrate both domains)
+	const frameworkResult = await frameworkCache.cleanCache(ui5DataDir);
+	const buildResult = await CacheManager.cleanCache(ui5DataDir);
+
+	await displayCleanupResult({
+		frameworkResult,
+		buildResult,
+		frameworkAbsPath,
+		buildAbsPath,
+		buildPreSize,
+	});
+}
+
+export default cacheCommand;

packages/cli/package.json

@@ -64,7 +64,8 @@
 		"pretty-hrtime": "^1.0.3",
 		"semver": "^7.8.5",
 		"update-notifier": "^7.3.1",
-		"yargs": "^18.0.0"
+		"yargs": "^18.0.0",
+		"yesno": "^0.4.0"
 	},
 	"devDependencies": {
 		"@istanbuljs/esm-loader-hook": "^0.3.0",