Merge branch 'main' into feat/process-instance-diagram

Author: vobu

.gitignore

@@ -140,3 +140,7 @@ dist
 # Vite logs files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+
+# Test plugin directories
+c8ctl-test-*
+test-plugin-temp

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

@@ -308,9 +308,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>
 
@@ -320,7 +335,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)
@@ -335,21 +357,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.
 

default-plugins/hello-world/README.md

@@ -0,0 +1,158 @@
+# c8ctl-plugin-hello-world
+
+A default "hello world" plugin for c8ctl that demonstrates the complete plugin API and lifecycle.
+
+## Purpose
+
+This plugin serves multiple purposes:
+
+1. **Example**: Shows how to create a fully compliant c8ctl plugin
+2. **Documentation**: Demonstrates all plugin API features
+3. **Testing**: Validates the plugin system is working correctly
+4. **Template**: Provides a reference implementation for new plugins
+
+## Features
+
+- ✅ Complete metadata for help integration
+- ✅ Command that displays runtime information
+- ✅ Argument handling demonstration
+- ✅ Compliant with plugin API requirements
+- ✅ Loaded by default as an essential plugin
+
+## Usage
+
+This plugin is loaded automatically with c8ctl. Try it:
+
+```bash
+c8ctl hello-world
+c8ctl hello-world arg1 arg2 arg3
+```
+
+## Plugin Structure
+
+```
+hello-world/
+├── package.json           # Package metadata with c8ctl keywords
+├── c8ctl-plugin.js        # Plugin implementation (ES6 module)
+└── README.md              # This file
+```
+
+## Requirements
+
+- Package must have `c8ctl` or `c8ctl-plugin` in keywords
+- Must export `commands` object with command functions
+- Optionally export `metadata` object for help text
+- Entry point must be `c8ctl-plugin.js` (or .ts)
+
+## Plugin API
+
+### Storage Locations
+
+Plugins are stored in OS-specific directories:
+
+| OS | Plugin 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:** Override with `C8CTL_DATA_DIR` environment variable if needed.
+
+### Runtime Access
+
+The plugin can access c8ctl runtime via `globalThis.c8ctl`:
+
+```javascript
+globalThis.c8ctl = {
+  version: string;          // c8ctl version
+  nodeVersion: string;      // Node.js version
+  platform: string;         // OS platform
+  arch: string;             // CPU architecture
+  cwd: string;              // Current working directory
+  outputMode: 'text' | 'json';  // Output format
+  activeProfile?: string;   // Active connection profile
+  activeTenant?: string;    // Active tenant
+};
+```
+
+### Command Implementation
+
+Commands receive arguments and return promises:
+
+```javascript
+export const commands = {
+  'command-name': async (args) => {
+    // args is an array of strings
+    // Use console.log for output
+    // Return a promise or async function
+  },
+};
+```
+
+### Metadata
+
+Provide help text via metadata export:
+
+```javascript
+export const metadata = {
+  name: 'plugin-name',
+  description: 'Plugin description',
+  commands: {
+    'command-name': {
+      description: 'Command description shown in help',
+    },
+  },
+};
+```
+
+## Important Limitations
+
+### Command Precedence
+
+**Plugin commands cannot override built-in commands.** The c8ctl CLI always checks for built-in commands first. If a plugin exports a command with the same name as a built-in command (e.g., `list`, `get`, `create`), the built-in command will always execute, and the plugin command will be ignored.
+
+For example, if a plugin tries to export a `list` command:
+
+```javascript
+export const commands = {
+  'list': async (args) => {
+    console.log('This will NEVER execute');
+  }
+};
+```
+
+When users run `c8ctl list`, the built-in `list` command will execute instead. Choose unique command names for your plugins to avoid conflicts.
+
+## Development
+
+To create a similar plugin:
+
+1. Use the scaffolding command:
+
+   ```bash
+   c8ctl init plugin my-plugin
+   ```
+
+2. Or manually create the structure following this example
+
+3. Test locally:
+
+   ```bash
+   c8ctl load plugin --from file:///path/to/plugin
+   ```
+
+4. Publish to npm:
+
+   ```bash
+   npm publish
+   ```
+
+5. Users can install:
+
+   ```bash
+   c8ctl load plugin your-plugin-name
+   ```
+
+## License
+
+You decide, but our [own Drink-ware](/LICENSE.md) is of course the most fitting :)