Merge branch 'main' into copilot/log-search-criteria-to-user

Author: vobu

.github/workflows/release.yml

@@ -38,11 +38,8 @@ jobs:
         run: npm run test:unit
 
       - name: Start Camunda ${{ matrix.camunda }} with Docker Compose
-        run: |
-          cd assets/c8/${{ matrix.camunda }}
-          DATABASE=elasticsearch docker compose --profile elasticsearch up -d
-        env:
-          DATABASE: elasticsearch
+        working-directory: assets/c8/${{ matrix.camunda }}
+        run: docker compose up -d
 
       - name: Wait for Camunda to be ready
         run: |
@@ -79,19 +76,13 @@ jobs:
 
       - name: Stop Camunda
         if: always()
-        run: |
-          cd assets/c8/${{ matrix.camunda }}
-          DATABASE=elasticsearch docker compose --profile elasticsearch down -v
-        env:
-          DATABASE: elasticsearch
+        working-directory: assets/c8/${{ matrix.camunda }}
+        run: docker compose down -v
 
       - name: Show Camunda logs on failure
         if: failure()
-        run: |
-          cd assets/c8/${{ matrix.camunda }}
-          DATABASE=elasticsearch docker compose --profile elasticsearch logs
-        env:
-          DATABASE: elasticsearch
+        working-directory: assets/c8/${{ matrix.camunda }}
+        run: docker compose logs
 
   release:
     name: Release

.github/workflows/test.yml

@@ -35,12 +35,9 @@ jobs:
         run: npm run test:unit
 
       - name: Start Camunda ${{ matrix.camunda }} with Docker Compose
-        run: |
-          cd assets/c8/${{ matrix.camunda }}
-          DATABASE=elasticsearch docker compose --profile elasticsearch up -d
-        env:
-          DATABASE: elasticsearch
-
+        working-directory: assets/c8/${{ matrix.camunda }}
+        run: docker compose up -d
+          
       - name: Wait for Camunda to be ready
         run: |
           echo "Waiting for Camunda at localhost:8080..."
@@ -76,16 +73,10 @@ jobs:
 
       - name: Stop Camunda
         if: always()
-        run: |
-          cd assets/c8/${{ matrix.camunda }}
-          DATABASE=elasticsearch docker compose --profile elasticsearch down -v
-        env:
-          DATABASE: elasticsearch
+        working-directory: assets/c8/${{ matrix.camunda }}
+        run: docker compose down -v
 
       - name: Show Camunda logs on failure
         if: failure()
-        run: |
-          cd assets/c8/${{ matrix.camunda }}
-          DATABASE=elasticsearch docker compose --profile elasticsearch logs
-        env:
-          DATABASE: elasticsearch
+        working-directory: assets/c8/${{ matrix.camunda }}
+        run: docker compose logs

.gitignore

@@ -72,6 +72,7 @@ web_modules/
 .env.*
 !.env.example
 !.env.database.*
+!assets/**/*/.env
 
 # parcel-bundler cache (https://parceljs.org/)
 .cache
@@ -140,3 +141,7 @@ dist
 # Vite logs files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+
+# Test plugin directories
+c8ctl-test-*
+test-plugin-temp

EXAMPLES.md

@@ -63,6 +63,9 @@ c8 create pi --id=order-process --variables='{"orderId":"12345","amount":100}'
 # Create and wait for completion
 c8 create pi --id=order-process --awaitCompletion
 
+# Create and wait with custom timeout (30 seconds)
+c8 create pi --id=order-process --awaitCompletion --requestTimeout=30000
+
 # Note: --fetchVariables is reserved for future API support
 # All variables are currently returned by default
 ```
@@ -71,6 +74,8 @@ c8 create pi --id=order-process --awaitCompletion
 
 The `await` command is an alias for `create` with `--awaitCompletion`. It uses the Camunda 8 API's built-in server-side waiting to create a process instance and wait for completion.
 
+The `--requestTimeout` option specifies the maximum time in milliseconds to wait for the process instance to complete. By default (or when set to 0), the generic request timeout configured in the cluster is used.
+
 ```bash
 # Create and wait for completion (shorthand)
 c8 await pi --id=order-process
@@ -79,6 +84,9 @@ c8 await process-instance --id=order-process
 # With variables
 c8 await pi --id=order-process --variables='{"orderId":"12345"}'
 
+# With custom timeout (60 seconds)
+c8 await pi --id=order-process --requestTimeout=60000
+
 # Equivalent to:
 c8 create pi --id=order-process --awaitCompletion
 

PLUGIN-HELP.md

@@ -6,9 +6,46 @@ This document describes how c8ctl plugins can provide help text that gets integr
 
 When users load plugins, their commands automatically appear in the help text. Plugins can optionally provide descriptions for their commands to make the help more informative.
 
+## Global Plugin System
+
+c8ctl uses a global plugin system where plugins are installed to a user-specific directory. This means:
+
+- **No local package.json required**: Plugins work from any directory
+- **Global installation**: Plugins are installed to OS-specific directories:
+  - **Linux**: `~/.config/c8ctl/plugins/node_modules`
+  - **macOS**: `~/Library/Application Support/c8ctl/plugins/node_modules`
+  - **Windows**: `%APPDATA%\c8ctl\plugins\node_modules`
+- **Plugin registry**: Tracked in `plugins.json` in the same parent directory
+- **Persistent across projects**: Once loaded, plugins are available everywhere
+- **Centralized management**: All plugins are managed through the c8ctl plugin registry
+- **Cannot override built-in commands**: Plugin commands are executed only if no built-in command matches
+
+> **Note:** You can override the default data directory by setting the `C8CTL_DATA_DIR` environment variable.
+
+## Plugin Registry
+
+The plugin registry (`plugins.json`) maintains a list of all installed plugins with metadata:
+
+```json
+{
+  "plugins": [
+    {
+      "name": "my-plugin",
+      "source": "my-plugin@1.0.0",
+      "installedAt": "2024-01-15T10:30:00.000Z"
+    }
+  ]
+}
+```
+
+Registry locations by OS:
+- **Linux**: `~/.config/c8ctl/plugins.json`
+- **macOS**: `~/Library/Application Support/c8ctl/plugins.json`
+- **Windows**: `%APPDATA%\c8ctl\plugins.json`
+
 ## How It Works
 
-1. **Automatic Discovery**: When `c8ctl help` is invoked, it scans all loaded plugins
+1. **Automatic Discovery**: When `c8ctl help` is invoked, it scans all loaded plugins from the global plugins directory
 2. **Plugin Section**: If plugins are loaded, a "Plugin Commands" section appears at the bottom of the help text
 3. **Command Listing**: Each plugin command is listed with its optional description
 
@@ -83,6 +120,7 @@ export const commands = {
 ## Help Output Example
 
 Without plugins loaded:
+
 ```
 c8ctl - Camunda 8 CLI v2.0.0
 
@@ -95,6 +133,7 @@ Commands:
 ```
 
 With plugins loaded:
+
 ```
 c8ctl - Camunda 8 CLI v2.0.0
 
@@ -121,6 +160,7 @@ The plugin loader ([src/plugin-loader.ts](src/plugin-loader.ts)) provides:
 - `getPluginCommandNames()`: Returns array of command names
 - `getPluginCommandsInfo()`: Returns detailed info including descriptions
 - Automatic metadata extraction during plugin loading
+- Scans the [global plugins directory](#global-plugin-system) for installed plugins
 
 ### Help Command
 
@@ -150,25 +190,59 @@ interface PluginMetadata {
 2. **Keep descriptions concise**: Aim for one line (< 60 characters)
 3. **Use imperative verbs**: Start with action words (Analyze, Deploy, Check, etc.)
 4. **Match command names**: Ensure metadata command names match exported functions
-5. **TypeScript plugins**: The `c8ctl-plugin.js` entry point must be JavaScript. Node.js doesn't support type stripping in `node_modules`. Transpile TypeScript to JavaScript before publishing your plugin.
+5. **Use unique command names**: Plugin commands cannot override built-in commands (see [Command Precedence](#command-precedence))
+6. **TypeScript plugins**: The `c8ctl-plugin.js` entry point must be JavaScript. Node.js doesn't support type stripping in `node_modules`. Transpile TypeScript to JavaScript before publishing your plugin.
+
+## Command Precedence
+
+**Important:** Plugin commands cannot override built-in c8ctl commands. Built-in commands always take precedence.
+
+When c8ctl processes a command, it follows this order:
+
+1. Check for built-in commands (list, get, create, deploy, etc.)
+2. If no built-in command matches, check plugin commands
+3. Execute the matched command
+
+### Example
+
+If a plugin exports a command named `list`:
+
+```javascript
+export const commands = {
+  'list': async (args) => {
+    console.log('This will NEVER execute');
+  }
+};
+```
+
+When users run `c8ctl list profiles`, the built-in `list` command will execute, not the plugin version.
+
+### Recommendation
+
+Choose descriptive, unique names for your plugin commands that don't conflict with built-in commands. For example:
+- ✅ `analyze-process`, `export-data`, `sync-resources`
+- ❌ `list`, `get`, `create`, `deploy`
 
 ## Testing
 
 See [tests/unit/plugin-loader.test.ts](tests/unit/plugin-loader.test.ts) for unit tests that verify:
+
 - `getPluginCommandsInfo()` returns correct structure
 - Help text includes plugin commands
 - Metadata is properly parsed
 
 ## Example Plugin Development Flow
 
 1. Create plugin with commands:
+
 ```typescript
 export const commands = {
   myCommand: async () => { /* ... */ }
 };
 ```
 
-2. Add metadata for help:
+1. Add metadata for help:
+
 ```typescript
 export const metadata = {
   commands: {
@@ -179,12 +253,14 @@ export const metadata = {
 };
 ```
 
-3. Load plugin:
+1. Load plugin:
+
 ```bash
 c8ctl load plugin my-plugin
 ```
 
-4. Verify help includes your command:
+1. Verify help includes your command:
+
 ```bash
 c8ctl help
 ```

README.md

@@ -1,6 +1,6 @@
-# c8ctl - Camunda 8 CLI
+# Cocktail (c8ctl) - Camunda 8 CLI
 
-A minimal-dependency CLI for Camunda 8 operations built on top of `@camunda8/orchestration-cluster-api`.
+c8ctl (_pronounced: "cocktail"_) — a minimal-dependency CLI for Camunda 8 operations built on top of [`@camunda8/orchestration-cluster-api`](https://www.npmjs.com/package/@camunda8/orchestration-cluster-api).
 
 ## Features
 
@@ -109,10 +109,16 @@ c8ctl create process-instance --id=myProcess
 # Create process instance and wait for completion
 c8ctl create pi --id=myProcess --awaitCompletion
 
+# Create process instance with custom timeout (30 seconds)
+c8ctl create pi --id=myProcess --awaitCompletion --requestTimeout=30000
+
 # Await process instance completion (alias for create with --awaitCompletion)
 c8ctl await pi --id=myProcess
 c8ctl await process-instance --id=myProcess
 
+# Await with custom timeout
+c8ctl await pi --id=myProcess --requestTimeout=60000
+
 # Cancel process instance
 c8ctl cancel pi 123456
 
@@ -306,9 +312,24 @@ Debug output is written to stderr with timestamps and won't interfere with norma
 
 ### Plugin Management
 
-c8ctl supports a plugin system that allows extending the CLI with custom commands via npm packages. Plugins are tracked in a registry file (`~/.config/c8ctl/plugins.json` on Linux, similar locations on other platforms) for persistence across npm operations.
+c8ctl supports a global plugin system that allows extending the CLI with custom commands via npm packages. Plugins are installed globally to a user-specific directory and tracked in a registry file.
+
+**Plugin Storage Locations:**
+
+The plugin system uses OS-specific directories:
+
+| OS | Plugins Directory | Registry File |
+|----|-------------------|---------------|
+| **Linux** | `~/.config/c8ctl/plugins/node_modules` | `~/.config/c8ctl/plugins.json` |
+| **macOS** | `~/Library/Application Support/c8ctl/plugins/node_modules` | `~/Library/Application Support/c8ctl/plugins.json` |
+| **Windows** | `%APPDATA%\c8ctl\plugins\node_modules` | `%APPDATA%\c8ctl\plugins.json` |
+
+> **Note:** You can override the data directory with the `C8CTL_DATA_DIR` environment variable.
 
 ```bash
+# Create a new plugin from template
+c8ctl init plugin my-plugin
+
 # Load a plugin from npm registry
 c8ctl load plugin <package-name>
 
@@ -318,7 +339,14 @@ c8ctl load plugin --from file:///path/to/plugin
 c8ctl load plugin --from https://github.com/user/repo
 c8ctl load plugin --from git://github.com/user/repo.git
 
-# Unload a plugin (wraps npm uninstall)
+# Upgrade a plugin to latest or specific version
+c8ctl upgrade plugin <package-name>
+c8ctl upgrade plugin <package-name> 1.2.3
+
+# Downgrade a plugin to a specific version
+c8ctl downgrade plugin <package-name> 1.0.0
+
+# Unload a plugin
 c8ctl unload plugin <package-name>
 
 # List installed plugins (shows sync status)
@@ -333,21 +361,32 @@ c8ctl sync plugins
 c8ctl help
 ```
 
-**Plugin Registry:**
-- Plugins are tracked independently of `package.json` in a registry file
-- The registry serves as the source of truth (local precedence)
+**Global Plugin System:**
+- Plugins are installed to a global directory (OS-specific, see table above)
+- Plugin registry file (`plugins.json`) tracks all installed plugins
+- No local `package.json` is required in your working directory
+- Plugins are available globally from any directory
+- The registry serves as the source of truth for installed plugins
+- Default plugins are bundled with c8ctl and loaded automatically
+- **Plugin commands cannot override built-in commands** - built-in commands always take precedence
 - `c8ctl list plugins` shows sync status:
   - `✓ Installed` - Plugin is in registry and installed
-  - `⚠ Not installed` - Plugin is in registry but not in node_modules (run `sync`)
-  - `⚠ Not in registry` - Plugin is in package.json but not tracked in registry
+  - `⚠ Not installed` - Plugin is in registry but not in global directory (run `sync`)
+  - `⚠ Not in registry` - Plugin is installed but not tracked in registry
 - `c8ctl sync plugins` synchronizes plugins from the registry, rebuilding or reinstalling as needed
 
+**Plugin Development:**
+- Use `c8ctl init plugin <name>` to scaffold a new plugin with TypeScript template
+- Generated scaffold includes all necessary files and build configuration
+- Plugins have access to the c8ctl runtime via `globalThis.c8ctl`
+- See the bundled `hello-world` plugin in `default-plugins/` for a complete example
+
 **Plugin Requirements:**
 - Plugin packages must be regular Node.js modules
 - They must include a `c8ctl-plugin.js` or `c8ctl-plugin.ts` file in the root directory
 - The plugin file must export a `commands` object
 - Optionally export a `metadata` object to provide help text
-- Plugins are installed in `node_modules` like regular npm packages
+- Plugins are installed globally and work from any directory
 - The runtime object `c8ctl` provides environment information to plugins
 - **Important**: `c8ctl-plugin.js` must be JavaScript. Node.js doesn't support type stripping in `node_modules`. If writing in TypeScript, transpile to JS before publishing.
 

assets/c8/8.8/.env

@@ -0,0 +1,3 @@
+# Default configuration for docker compose
+# Activates the elasticsearch profile (vs opensearch)
+COMPOSE_PROFILES=elasticsearch

assets/c8/8.8/docker-compose.yml

@@ -128,9 +128,9 @@ services:
       - 9600:9600
       - 8080:8080
     depends_on:
-      - ${DATABASE}
+      - elasticsearch
     networks:
       - zeebe_network
     env_file:
-      - envs/.env.database.${DATABASE}
+      - envs/.env.database.elasticsearch
 

assets/c8/8.9/.env

@@ -0,0 +1,2 @@
+# Default configuration for docker compose
+CAMUNDA_VERSION=8.9.0-alpha4