@camunda8/cli 2.7.0-alpha.6 → 2.7.0-alpha.7

package/README.md

@@ -65,6 +65,7 @@ c8ctl help fail       # Shows fail command with all flags
 c8ctl help activate   # Shows activate command with all flags
 c8ctl help publish    # Shows publish command with all flags
 c8ctl help correlate  # Shows correlate command with all flags
+c8ctl help cluster    # Shows local cluster management help
 c8ctl help profiles   # Shows profile management help
 c8ctl help plugin     # Shows plugin management help
 
@@ -568,6 +569,67 @@ c8ctl help list     # → JSON for specific command
 
 ---
 
+### Local Cluster
+
+c8ctl includes a built-in `cluster` command for managing a local Camunda 8 instance (powered by a default plugin). No Docker or docker-compose required — it downloads and runs Camunda directly.
+
+```bash
+# Start the latest stable version
+c8ctl cluster start
+
+# Start a specific version
+c8ctl cluster start 8.9
+c8ctl cluster start 8.9.0-alpha5
+
+# Stop the running cluster
+c8ctl cluster stop
+
+# Check cluster status
+c8ctl cluster status
+
+# Stream cluster logs
+c8ctl cluster logs
+
+# List locally cached versions
+c8ctl cluster list
+
+# List available remote versions
+c8ctl cluster list-remote
+
+# Pre-download a version without starting it
+c8ctl cluster install 8.9
+
+# Remove a cached version
+c8ctl cluster delete 8.9
+```
+
+#### Version Aliases
+
+Instead of an exact version number, you can use:
+
+- **`stable`** — the latest GA release (highest minor version that has shipped a `.0` release)
+- **`alpha`** — the latest alpha-train release (highest minor version overall, which may only have alpha builds)
+- **A major.minor pattern** like `8.9` — resolves to the latest patch/alpha within that minor
+
+`c8ctl cluster start` with no version argument defaults to `stable`.
+
+```bash
+c8ctl cluster start stable
+c8ctl cluster start alpha
+c8ctl cluster start 8.9     # latest 8.9.x
+```
+
+#### Online vs Offline Behaviour
+
+- **`cluster start`** prefers locally cached versions. If the requested version is already installed, it starts immediately without going online. A non-blocking background check runs to hint if a newer build is available, but never delays startup.
+- **`cluster install`** always checks the remote download server for the latest build. If a newer ETag is detected for an already-installed version, it re-downloads.
+- **`cluster list-remote`** fetches the full list of available versions from the download server.
+- **Offline fallback**: if the network is unavailable, alias resolution falls back to a locally cached mapping, then to a hardcoded default.
+
+Run `c8ctl help cluster` for full details. See [EXAMPLES.md](EXAMPLES.md#local-cluster) for a complete local development workflow.
+
+---
+
 ### Core Components
 
 - **Logger** (`src/logger.ts`): Handles output in text or JSON mode
@@ -604,6 +666,7 @@ c8ctl <verb> <resource> [arguments] [flags]
 - `sync` - Synchronize plugins
 - `use` - Set active profile or tenant
 - `output` - Show or set output format
+- `cluster` - Manage local Camunda 8 cluster (start, stop, status, logs, install, delete, list, list-remote)
 - `completion` - Generate shell completion script
 - `feedback` - Open the feedback page to report issues or request features
 

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

@@ -892,12 +892,115 @@ async function startC8Run(config, debug = false) {
   }
 }
 
-async function stopC8Run(config) {
+export function hasRunningClusterPidfiles(cacheDir) {
+  if (!existsSync(cacheDir)) {
+    return false;
+  }
+
+  const versionDirs = readdirSync(cacheDir, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() && entry.name.startsWith('c8run-'),
+    )
+    .map((entry) => join(cacheDir, entry.name));
+
+  // Scan each version dir and its immediate subdirectories (max depth 1)
+  // rather than a full recursive DFS — c8run installs can contain large
+  // extracted trees, logs, and data that would make a deep walk slow.
+  for (const versionDir of versionDirs) {
+    let entries;
+    try {
+      entries = readdirSync(versionDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    // Collect directories at this level to also check one level deeper.
+    const dirsToCheck = [versionDir];
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        dirsToCheck.push(join(versionDir, entry.name));
+      }
+    }
+
+    for (const dir of dirsToCheck) {
+      let dirEntries;
+      try {
+        dirEntries = readdirSync(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+
+      for (const entry of dirEntries) {
+        if (!entry.isFile() || !entry.name.endsWith('.process')) {
+          continue;
+        }
+
+        const entryPath = join(dir, entry.name);
+
+        let pid;
+        try {
+          pid = Number.parseInt(readFileSync(entryPath, 'utf-8').trim(), 10);
+        } catch {
+          // Pidfile may have been removed between listing and reading.
+          continue;
+        }
+
+        if (!Number.isInteger(pid) || pid <= 0) {
+          continue;
+        }
+
+        try {
+          process.kill(pid, 0);
+          return true;
+        } catch (error) {
+          if (error && error.code === 'EPERM') {
+            return true;
+          }
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
+export async function stopC8Run(config, debug = false) {
   const logger = getLogger();
   const markerFile = join(config.cacheDir, ACTIVE_MARKER_FILE);
   const versionFile = join(config.cacheDir, VERSION_MARKER_FILE);
 
   const markerExists = existsSync(markerFile);
+  const clusterAppearsRunning = hasRunningClusterPidfiles(config.cacheDir);
+
+  if (!markerExists && !clusterAppearsRunning) {
+    logger.warn(
+      'No cluster is currently running.',
+    );
+    return;
+  }
+
+  if (markerExists && !clusterAppearsRunning) {
+    // Stale marker left behind (e.g. crash or forced kill). Clean up and
+    // return early — there is nothing to stop.
+    logger.warn(
+      'Cluster marker file found, but no running cluster processes detected. Cleaning up stale marker.',
+    );
+    if (existsSync(markerFile)) {
+      rmSync(markerFile);
+    }
+    if (existsSync(versionFile)) {
+      rmSync(versionFile);
+    }
+    return;
+  }
+
+  if (!markerExists && clusterAppearsRunning) {
+    logger.warn(
+      'Cluster marker file is missing, but running cluster processes were detected. Proceeding with stop.',
+    );
+  }
+
   const installedVersions = existsSync(config.cacheDir)
     ? readdirSync(config.cacheDir, { withFileTypes: true })
         .filter(
@@ -908,13 +1011,6 @@ async function stopC8Run(config) {
         .sort()
     : [];
 
-  if (!markerExists && installedVersions.length === 0) {
-    logger.warn(
-      'No running cluster found (use "c8ctl cluster start" to start one).',
-    );
-    return;
-  }
-
   const versionsToTry = [];
 
   if (existsSync(versionFile)) {
@@ -949,18 +1045,53 @@ async function stopC8Run(config) {
 
     attempted += 1;
 
-    const { code: exitCode, signal: exitSignal } = await new Promise(
+    const { code: exitCode, signal: exitSignal, stdout: procStdout, stderr: procStderr } = await new Promise(
       (resolve, reject) => {
         const proc = spawn(binaryPath, ['stop'], {
-          stdio: 'inherit',
+          stdio: ['ignore', 'pipe', 'pipe'],
           cwd: dirname(binaryPath),
         });
-        proc.on('exit', (code, signal) => resolve({ code, signal }));
+
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutLen = 0;
+        let stderrLen = 0;
+        const MAX_BUFFER = 64 * 1024; // 64 KB cap per stream
+
+        proc.stdout?.on('data', (chunk) => {
+          const text = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+          if (debug) {
+            process.stdout.write(text);
+          }
+          if (stdoutLen < MAX_BUFFER) {
+            stdoutChunks.push(text);
+            stdoutLen += text.length;
+          }
+        });
+        proc.stderr?.on('data', (chunk) => {
+          const text = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+          if (debug) {
+            process.stderr.write(text);
+          }
+          if (stderrLen < MAX_BUFFER) {
+            stderrChunks.push(text);
+            stderrLen += text.length;
+          }
+        });
+
+        proc.on('close', (code, signal) =>
+          resolve({
+            code,
+            signal,
+            stdout: stdoutChunks.join(''),
+            stderr: stderrChunks.join(''),
+          }),
+        );
         proc.on('error', reject);
       },
     ).catch((error) => {
       lastError = error instanceof Error ? error : new Error(String(error));
-      return { code: -1, signal: null };
+      return { code: -1, signal: null, stdout: '', stderr: '' };
     });
 
     if (exitCode === 0 || (exitCode === null && !exitSignal)) {
@@ -971,7 +1102,10 @@ async function stopC8Run(config) {
         `Stop command terminated by signal ${exitSignal}`,
       );
     } else if (exitCode !== -1) {
-      lastError = new Error(`Stop command failed with code ${exitCode}`);
+      const output = [procStdout, procStderr].filter(Boolean).join('\n');
+      lastError = new Error(
+        `Stop command failed with code ${exitCode}${output ? `:\n${output}` : ''}`,
+      );
     }
   }
 
@@ -1522,7 +1656,7 @@ export const commands = {
       }
     } else if (parsed.subcommand === 'stop') {
       try {
-        await stopC8Run(config);
+        await stopC8Run(config, parsed.debug);
       } catch (error) {
         logger.error(`Failed to stop cluster: ${error}`);
         process.exit(1);

package/package.json

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