@camunda8/cli 3.3.0-alpha.5 → 3.3.0-alpha.6

package/EXAMPLES.md

@@ -1233,6 +1233,26 @@ c8 cluster install alpha
 c8 cluster delete 8.8
 ```
 
+### Purge Cluster Data
+
+Wipe history and journal data while keeping the downloaded binary intact.
+The next `cluster start` begins with a fresh empty state without re-downloading anything.
+
+```bash
+# Purge data for a specific version (version required, like delete)
+c8 cluster purge 8.9
+c8 cluster purge 8.9.0-alpha5
+
+# Stop the running cluster and purge its data in one step
+c8 cluster stop --purge
+```
+
+If the target version is currently running, stop it first with `cluster stop`
+(or use `cluster stop --purge` to stop and purge in one step).
+
+`cluster stop --purge` is the recommended way to reset a running cluster:
+it captures the running version, stops it, then purges the data atomically.
+
 ### Typical Local Development Workflow
 
 ```bash

package/README.md

@@ -517,6 +517,12 @@ c8ctl cluster install 8.9
 
 # Remove a cached version
 c8ctl cluster delete 8.9
+
+# Purge history and journal data for a version (binary stays intact)
+c8ctl cluster purge 8.9
+
+# Stop cluster and purge its runtime data in one step
+c8ctl cluster stop --purge
 ```
 
 #### Version Aliases

package/dist/default-plugins/cluster/c8ctl-plugin.js

@@ -320,6 +320,7 @@ export const metadata = {
         { name: 'delete', description: 'Remove a cached version' },
         { name: 'log', description: 'Stream cluster logs' },
         { name: 'logs', description: 'Stream cluster logs' },
+        { name: 'purge', description: 'Delete runtime data (keeps binary) so the next start is fresh' },
       ],
       examples: [
         { command: 'c8ctl cluster start', description: 'Start a local Camunda 8 cluster (latest stable)' },
@@ -332,6 +333,8 @@ export const metadata = {
         { command: 'c8ctl cluster list-remote', description: 'List all versions available on the remote download server' },
         { command: 'c8ctl cluster install 8.8', description: 'Download a version without starting it' },
         { command: 'c8ctl cluster delete 8.8', description: 'Remove a locally cached version' },
+        { command: 'c8ctl cluster purge 8.8', description: 'Delete runtime data for a version (binary stays intact)' },
+        { command: 'c8ctl cluster stop --purge', description: 'Stop the running cluster and delete its runtime data' },
       ],
     },
   },
@@ -1043,13 +1046,16 @@ export async function stopC8Run(config, debug = false) {
     logger.warn(
       'Cluster marker file found, but no running cluster processes detected. Cleaning up stale marker.',
     );
-    if (existsSync(markerFile)) {
-      rmSync(markerFile);
-    }
+    let staleVersion = null;
     if (existsSync(versionFile)) {
+      const v = readFileSync(versionFile, 'utf-8').trim();
+      if (v) staleVersion = v;
       rmSync(versionFile);
     }
-    return;
+    if (existsSync(markerFile)) {
+      rmSync(markerFile);
+    }
+    return staleVersion;
   }
 
   if (!markerExists && clusterAppearsRunning) {
@@ -1069,10 +1075,12 @@ export async function stopC8Run(config, debug = false) {
     : [];
 
   const versionsToTry = [];
+  let stoppedVersion = null;
 
   if (existsSync(versionFile)) {
     const markerVersion = readFileSync(versionFile, 'utf-8').trim();
     if (markerVersion) {
+      stoppedVersion = markerVersion;
       versionsToTry.push(markerVersion);
     }
   }
@@ -1186,6 +1194,7 @@ export async function stopC8Run(config, debug = false) {
   }
 
   logger.info('Cluster stopped.');
+  return stoppedVersion;
 }
 
 // ---------------------------------------------------------------------------
@@ -1369,6 +1378,37 @@ export async function listRemoteVersions() {
   console.log('');
 }
 
+// ---------------------------------------------------------------------------
+// Shared helpers for delete / purge
+// ---------------------------------------------------------------------------
+
+// Validate and resolve a version spec to the locally installed version name.
+// Aliases (stable, alpha) are resolved preferring the local cache so that
+// delete/purge operate on what is actually installed.
+async function resolveVersionArg(cacheDir, versionSpec) {
+  validateVersionSpec(versionSpec);
+  return isVersionAlias(versionSpec)
+    ? await resolveVersion(versionSpec, { preferLocal: true, cacheDir })
+    : versionSpec;
+}
+
+// Return true if the given version appears to be currently running.
+// Requires both marker files to identify the running version, then confirms
+// with live .process pidfiles. Without markers we cannot attribute any
+// running process to a specific version, so we return false — consistent
+// with stopC8Run treating marker absence as "not running".
+function isVersionRunning(cacheDir, version) {
+  const markerFile = join(cacheDir, ACTIVE_MARKER_FILE);
+  const versionFile = join(cacheDir, VERSION_MARKER_FILE);
+
+  if (!existsSync(markerFile) || !existsSync(versionFile)) return false;
+
+  const markerVersion = readFileSync(versionFile, 'utf-8').trim();
+  if (markerVersion !== version) return false;
+
+  return hasRunningClusterPidfiles(cacheDir);
+}
+
 // ---------------------------------------------------------------------------
 // Delete cached version
 // ---------------------------------------------------------------------------
@@ -1381,28 +1421,28 @@ export async function deleteVersion(cacheDir, versionSpec) {
     process.exit(1);
   }
 
-  validateVersionSpec(versionSpec);
-
-  // Resolve named aliases (stable/alpha) to the actual cached version name.
-  // Use preferLocal so we delete the version that's actually installed,
-  // not whatever the remote currently resolves the alias to.
   // Major.minor patterns like 8.8 are used as-is since the cache dir is named c8run-8.8.
-  const resolvedVersion = isVersionAlias(versionSpec)
-    ? await resolveVersion(versionSpec, { preferLocal: true, cacheDir })
-    : versionSpec;
+  const resolvedVersion = await resolveVersionArg(cacheDir, versionSpec);
 
   // Prevent deleting a currently running version
-  const versionFile = join(cacheDir, VERSION_MARKER_FILE);
-  const markerFile = join(cacheDir, ACTIVE_MARKER_FILE);
+  if (isVersionRunning(cacheDir, resolvedVersion)) {
+    logger.error(
+      `Version ${resolvedVersion} is currently running. Stop it first with: c8ctl cluster stop`
+    );
+    process.exit(1);
+  }
 
-  if (existsSync(markerFile) && existsSync(versionFile)) {
-    const runningVersion = readFileSync(versionFile, 'utf-8').trim();
-    if (runningVersion === resolvedVersion) {
-      logger.error(
-        `Version ${resolvedVersion} is currently running. Stop it first with: c8ctl cluster stop`
-      );
-      process.exit(1);
-    }
+  // Safety backstop: if processes are running but either marker is absent we
+  // cannot confirm the version, so refuse rather than risk deleting a live install.
+  if (
+    (!existsSync(join(cacheDir, ACTIVE_MARKER_FILE)) || !existsSync(join(cacheDir, VERSION_MARKER_FILE))) &&
+    hasRunningClusterPidfiles(cacheDir)
+  ) {
+    logger.error(
+      'A cluster appears to be running (processes detected) but the cluster marker is missing. ' +
+      'Run c8ctl cluster stop first.'
+    );
+    process.exit(1);
   }
 
   const config = { cacheDir, version: resolvedVersion };
@@ -1416,6 +1456,79 @@ export async function deleteVersion(cacheDir, versionSpec) {
   logger.info(`Version ${versionSpec} has been deleted.`);
 }
 
+// ---------------------------------------------------------------------------
+// Purge cluster data
+// ---------------------------------------------------------------------------
+
+export async function purgeClusterData(cacheDir, versionSpec) {
+  const logger = getLogger();
+
+  const resolvedVersion = await resolveVersionArg(cacheDir, versionSpec);
+
+  // Prevent purging a currently running version
+  if (isVersionRunning(cacheDir, resolvedVersion)) {
+    logger.error(
+      `Version ${resolvedVersion} is currently running. ` +
+      'Stop it first with: c8ctl cluster stop\n' +
+      `Or stop and purge in one step: c8ctl cluster stop --purge`
+    );
+    process.exit(1);
+  }
+
+  // Safety backstop: if processes are running but either marker is absent we
+  // cannot confirm the version, so refuse rather than risk purging a live cluster.
+  if (
+    (!existsSync(join(cacheDir, ACTIVE_MARKER_FILE)) || !existsSync(join(cacheDir, VERSION_MARKER_FILE))) &&
+    hasRunningClusterPidfiles(cacheDir)
+  ) {
+    logger.error(
+      'A cluster appears to be running (processes detected) but the cluster marker is missing. ' +
+      'Run c8ctl cluster stop first.'
+    );
+    process.exit(1);
+  }
+
+  const config = { cacheDir, version: resolvedVersion };
+  if (!isC8RunInstalled(config)) {
+    logger.error(`Version ${resolvedVersion} is not installed locally.`);
+    process.exit(1);
+  }
+
+  const binaryPath = getC8RunBinaryPath(config);
+  const binaryDir = dirname(binaryPath);
+
+  const deleted = [];
+
+  // Delete camunda-data (history data + application state)
+  const camundaDataDir = join(binaryDir, 'camunda-data');
+  if (existsSync(camundaDataDir)) {
+    rmSync(camundaDataDir, { recursive: true });
+    deleted.push('camunda-data');
+  }
+
+  // Delete Zeebe journal data inside camunda-zeebe-* subdirectory
+  if (existsSync(binaryDir)) {
+    for (const entry of readdirSync(binaryDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || !entry.name.startsWith('camunda-zeebe-')) continue;
+      const dataDir = join(binaryDir, entry.name, 'data');
+      if (existsSync(dataDir)) {
+        rmSync(dataDir, { recursive: true });
+        deleted.push(join(entry.name, 'data'));
+      }
+    }
+  }
+
+  if (deleted.length > 0) {
+    logger.info(`Purged runtime data for ${resolvedVersion}:`);
+    for (const d of deleted) {
+      logger.info(`  deleted: ${d}`);
+    }
+  } else {
+    logger.info(`No runtime data found for ${resolvedVersion} — nothing to delete.`);
+  }
+  logger.info(`Binary and installed files preserved. Start fresh with: c8ctl cluster start ${resolvedVersion}`);
+}
+
 // ---------------------------------------------------------------------------
 // Logs
 // ---------------------------------------------------------------------------
@@ -1499,7 +1612,7 @@ export async function streamLogs(cacheDir) {
 // ---------------------------------------------------------------------------
 
 export function parsePluginArgs(args) {
-  const result = { subcommand: null, version: null, debug: false };
+  const result = { subcommand: null, version: null, debug: false, purge: false };
 
   let i = 0;
   while (i < args.length) {
@@ -1523,6 +1636,12 @@ export function parsePluginArgs(args) {
       continue;
     }
 
+    if (arg === '--purge') {
+      result.purge = true;
+      i += 1;
+      continue;
+    }
+
     if (!arg.startsWith('-') && result.subcommand === null) {
       result.subcommand = arg;
       i += 1;
@@ -1546,7 +1665,7 @@ export function parsePluginArgs(args) {
 // Plugin commands export
 // ---------------------------------------------------------------------------
 
-const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'list', 'list-remote', 'install', 'delete', 'log', 'logs'];
+const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'list', 'list-remote', 'install', 'delete', 'purge', 'log', 'logs'];
 
 export const commands = {
   'cluster': async (args) => {
@@ -1556,28 +1675,31 @@ export const commands = {
     if (!parsed.subcommand || !VALID_SUBCOMMANDS.includes(parsed.subcommand)) {
       console.log('Usage:');
       console.log('  c8ctl cluster start [<version>] [--debug]');
-      console.log('  c8ctl cluster stop');
+      console.log('  c8ctl cluster stop [--purge]');
       console.log('  c8ctl cluster status');
       console.log('  c8ctl cluster logs              (alias: log)');
       console.log('  c8ctl cluster list');
       console.log('  c8ctl cluster list-remote');
       console.log('  c8ctl cluster install <version>');
       console.log('  c8ctl cluster delete <version>');
+      console.log('  c8ctl cluster purge <version>');
       console.log('');
       console.log('Subcommands:');
       console.log('  start        Download (if needed) and start a local Camunda 8 cluster');
-      console.log('  stop         Stop the running local Camunda 8 cluster');
+      console.log('  stop         Stop the running local Camunda 8 cluster (--purge also deletes runtime data)');
       console.log('  status       Show whether a cluster is running and connection details');
       console.log('  logs         Stream log output from the running cluster');
       console.log('  list         List locally cached versions and available version aliases');
       console.log('  list-remote  List all versions available on the remote download server');
       console.log('  install      Download a version without starting it');
       console.log('  delete       Remove a locally cached version to reclaim disk space');
+      console.log('  purge        Delete runtime data for a version (binary stays intact, next start is fresh)');
       console.log('');
       console.log('Options:');
       console.log('  <version>              Camunda version, alias, or major.minor (default: stable)');
       console.log('  --c8-version <version> Alternative flag form for version');
       console.log('  --debug                Stream raw c8run output during start');
+      console.log('  --purge                (stop only) also delete runtime data after stopping');
       console.log('');
       console.log('A <version> can be:');
       console.log('  stable / alpha         Named aliases');
@@ -1604,9 +1726,16 @@ export const commands = {
       console.log('  c8ctl cluster list-remote');
       console.log('  c8ctl cluster install 8.8');
       console.log('  c8ctl cluster delete 8.8');
+      console.log('  c8ctl cluster purge 8.8          # Delete runtime data, keep binary');
+      console.log('  c8ctl cluster stop --purge        # Stop cluster and delete its runtime data');
       return;
     }
 
+    if (parsed.purge && parsed.subcommand !== 'stop') {
+      logger.error('--purge can only be used with the stop subcommand. Example: c8ctl cluster stop --purge');
+      process.exit(1);
+    }
+
     if (parsed.subcommand === 'status') {
       try {
         await clusterStatus(getCacheDir());
@@ -1647,11 +1776,14 @@ export const commands = {
       return;
     }
 
-    // install and delete require an explicit version argument
-    if (!parsed.version && (parsed.subcommand === 'install' || parsed.subcommand === 'delete')) {
-      const example = parsed.subcommand === 'delete'
-        ? 'c8ctl cluster delete 8.8'
-        : 'c8ctl cluster install stable';
+    // install, delete, and purge require an explicit version argument
+    if (!parsed.version && (parsed.subcommand === 'install' || parsed.subcommand === 'delete' || parsed.subcommand === 'purge')) {
+      const example =
+        parsed.subcommand === 'delete'
+          ? 'c8ctl cluster delete 8.8'
+          : parsed.subcommand === 'purge'
+            ? 'c8ctl cluster purge 8.8'
+            : 'c8ctl cluster install stable';
       logger.error(`Please specify a version. Example: ${example}`);
       process.exit(1);
     }
@@ -1666,6 +1798,16 @@ export const commands = {
       return;
     }
 
+    if (parsed.subcommand === 'purge') {
+      try {
+        await purgeClusterData(getCacheDir(), parsed.version);
+      } catch (error) {
+        logger.error(`Failed to purge cluster data: ${error}`);
+        process.exit(1);
+      }
+      return;
+    }
+
     const versionSpec = parsed.version || 'stable';
     if (!parsed.version && parsed.subcommand === 'start') {
       logger.info(`No version specified, using default: "${versionSpec}"`);
@@ -1713,7 +1855,15 @@ export const commands = {
       }
     } else if (parsed.subcommand === 'stop') {
       try {
-        await stopC8Run(config, parsed.debug);
+        const stoppedVersion = await stopC8Run(config, parsed.debug);
+        if (parsed.purge) {
+          if (!stoppedVersion) {
+            logger.warn('Cannot determine which version to purge (version marker is missing). ' +
+                'To purge manually, run: c8ctl cluster purge <version>');
+          } else {
+            await purgeClusterData(theCacheDir, stoppedVersion);
+          }
+        }
       } catch (error) {
         logger.error(`Failed to stop cluster: ${error}`);
         process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camunda8/cli",
-  "version": "3.3.0-alpha.5",
+  "version": "3.3.0-alpha.6",
   "description": "Camunda 8 CLI - minimal-dependency CLI for Camunda 8 operations",
   "type": "module",
   "engines": {