feat: Clean cache command

internal/documentation/docs/pages/Troubleshooting.md

@@ -16,14 +16,28 @@ There are possibly many versions of UI5 framework dependencies installed on your
 
 #### Resolution
 
-Remove the `.ui5/framework/` directory from your user's home directory:
+Use the dedicated cache clean command, which safely removes all cached data:
 
 ```sh
-rm -rf ~/.ui5/framework/
+ui5 cache clean
 ```
 
+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
+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 `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
 ### Changing the Log Level
 

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

@@ -0,0 +1,195 @@
+import chalk from "chalk";
+import path from "node:path";
+import os from "node:os";
+import process from "node:process";
+import baseMiddleware from "../middlewares/base.js";
+import {getUi5DataDir} from "../../framework/utils.js";
+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);
+}
+
+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 getUi5DataDir({cwd: process.cwd()})) ?? path.join(os.homedir(), ".ui5");
+
+	// Abort early if a framework operation is holding a lock — before prompting the user
+	if (await frameworkCache.isFrameworkLocked(ui5DataDir)) {
+		process.stderr.write(
+			`${chalk.red("Error:")} Framework cache is currently locked by an active operation. ` +
+			"Please wait for it to finish and try again.\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`);
+
+	// Check what items exist before cleaning (orchestrate both domains)
+	const frameworkInfo = await frameworkCache.getCacheInfo(ui5DataDir);
+	const buildInfo = await CacheManager.getCacheInfo(ui5DataDir);
+
+	if (!frameworkInfo && !buildInfo) {
+		process.stderr.write("Nothing to clean\n");
+		return;
+	}
+
+	// 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;
+
+	// Capture build size now — reused for the ✓ line to avoid a before/after mismatch
+	// (getDatabaseSize ≠ VACUUM-freed bytes returned by clearAllRecords)
+	const buildPreSize = buildInfo?.size ?? 0;
+
+	// 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");
+
+	// Ask for confirmation (skip with --yes)
+	if (!argv.yes) {
+		const {default: yesno} = await import("yesno");
+		const confirmed = await yesno({
+			question: "Do you want to continue? (y/N)",
+			defaultValue: false
+		});
+		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);
+
+	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`);
+}
+
+export default cacheCommand;

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

@@ -1,7 +1,11 @@
 import path from "node:path";
 import os from "node:os";
+import fs from "node:fs/promises";
+import {promisify} from "node:util";
 import chalk from "chalk";
 import baseMiddleware from "../middlewares/base.js";
+import {getUi5DataDir} from "../../framework/utils.js";
+import lockfile from "lockfile";
 import {getLogger} from "@ui5/logger";
 const log = getLogger("cli:commands:serve");
 
@@ -189,42 +193,76 @@ serve.handler = async function(argv) {
 		reject(err);
 	});
 
-	const protocol = h2 ? "https" : "http";
-	let browserUrl = protocol + "://localhost:" + actualPort;
-	if (argv.acceptRemoteConnections) {
-		process.stderr.write("\n");
-		process.stderr.write(chalk.bold("⚠️  This server is accepting connections from all hosts on your network"));
-		process.stderr.write("\n");
-		process.stderr.write(chalk.dim.underline("Please Note:"));
-		process.stderr.write("\n");
-		process.stderr.write(chalk.bold.dim(
-			"* This server is intended for development purposes only. Do not use it in production."));
-		process.stderr.write("\n");
-		process.stderr.write(chalk.dim(
-			"* Vulnerable (custom-)middleware can pose a threat to your system when exposed to the network"));
-		process.stderr.write("\n");
-		process.stderr.write(chalk.dim(
-			"* The use of proxy-middleware with preconfigured credentials might enable unauthorized access " +
-			"to a target system for third parties on your network"));
-		process.stderr.write("\n\n");
-	}
-	process.stdout.write("Server started");
-	process.stdout.write("\n");
-	process.stdout.write("URL: " + browserUrl);
-	process.stdout.write("\n");
+	// Acquire a port-specific server lock so that 'ui5 cache clean' cannot delete
+	// framework files that the server reads on every HTTP request. Multiple concurrent
+	// servers each hold their own lock; cleanCache sees any active lock and refuses.
+	const ui5DataDir = (await getUi5DataDir({cwd: process.cwd()})) ??
+		path.join(os.homedir(), ".ui5");
+	const lockDir = path.join(ui5DataDir, "framework", "locks");
+	const lockPath = path.join(lockDir, `server-${actualPort}.lock`);
+	await fs.mkdir(lockDir, {recursive: true});
+	const lockFn = promisify(lockfile.lock);
+	const unlockFn = promisify(lockfile.unlock);
+	await lockFn(lockPath, {stale: 60000});
+	let lockReleased = false;
+	const releaseServerLock = async () => {
+		if (lockReleased) return;
+		lockReleased = true;
+		await unlockFn(lockPath).catch(() => {});
+	};
+	// Signal handlers must be synchronous — Node does not await async handlers before exit.
+	const onSignal = () => {
+		if (!lockReleased) {
+			lockReleased = true;
+			lockfile.unlockSync(lockPath);
+		}
+		process.exit(0);
+	};
+	process.once("SIGINT", onSignal);
+	process.once("SIGTERM", onSignal);
+
+	try {
+		const protocol = h2 ? "https" : "http";
+		let browserUrl = protocol + "://localhost:" + actualPort;
+		if (argv.acceptRemoteConnections) {
+			process.stderr.write("\n");
+			process.stderr.write(chalk.bold("⚠️  This server is accepting connections from all hosts on your network"));
+			process.stderr.write("\n");
+			process.stderr.write(chalk.dim.underline("Please Note:"));
+			process.stderr.write("\n");
+			process.stderr.write(chalk.bold.dim(
+				"* This server is intended for development purposes only. Do not use it in production."));
+			process.stderr.write("\n");
+			process.stderr.write(chalk.dim(
+				"* Vulnerable (custom-)middleware can pose a threat to your system when exposed to the network"));
+			process.stderr.write("\n");
+			process.stderr.write(chalk.dim(
+				"* The use of proxy-middleware with preconfigured credentials might enable unauthorized access " +
+				"to a target system for third parties on your network"));
+			process.stderr.write("\n\n");
+		}
+		process.stdout.write("Server started");
+		process.stdout.write("\n");
+		process.stdout.write("URL: " + browserUrl);
+		process.stdout.write("\n");
 
-	if (argv.open !== undefined) {
-		if (typeof argv.open === "string") {
-			let relPath = argv.open || "/";
-			if (!relPath.startsWith("/")) {
-				relPath = "/" + relPath;
+		if (argv.open !== undefined) {
+			if (typeof argv.open === "string") {
+				let relPath = argv.open || "/";
+				if (!relPath.startsWith("/")) {
+					relPath = "/" + relPath;
+				}
+				browserUrl += relPath;
 			}
-			browserUrl += relPath;
+			const {default: open} = await import("open");
+			open(browserUrl);
 		}
-		const {default: open} = await import("open");
-		open(browserUrl);
+		await pOnError; // Await errors that should bubble into the yargs handler
+	} finally {
+		process.off("SIGINT", onSignal);
+		process.off("SIGTERM", onSignal);
+		await releaseServerLock();
 	}
-	await pOnError; // Await errors that should bubble into the yargs handler
 };
 
 export default serve;

packages/cli/lib/framework/utils.js

@@ -49,7 +49,7 @@ export async function frameworkResolverResolveVersion({frameworkName, frameworkV
 	});
 }
 
-async function getUi5DataDir({cwd}) {
+export async function getUi5DataDir({cwd}) {
 	// ENV var should take precedence over the dataDir from the configuration.
 	let ui5DataDir = process.env.UI5_DATA_DIR;
 	if (!ui5DataDir) {

packages/cli/package.json

@@ -64,7 +64,8 @@
 		"pretty-hrtime": "^1.0.3",
 		"semver": "^7.7.2",
 		"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",