@camunda8/cli 2.0.0-alpha.1 → 2.0.0-alpha.10

package/README.md

@@ -5,15 +5,22 @@ A minimal-dependency CLI for Camunda 8 operations built on top of `@camunda8/orc
 ## Features
 
 - **Minimal Dependencies**: Only one runtime dependency (`@camunda8/orchestration-cluster-api`)
-- **Native TypeScript**: Runs directly with Node.js 22.18+ (no compilation needed)
 - **Multi-Tenant Support**: Full support for multi-tenancy across all operations
 - **Profile Management**: Store and manage multiple cluster configurations
 - **Camunda Modeler Integration**: Automatically import and use profiles from Camunda Modeler
 - **Plugin System**: Extend c8ctl with custom commands via npm packages
-- **Session State**: Maintain active profile, tenant, and output preferences
-- **Building Block Deployment**: Automatic prioritization of `_bb-` folders during deployment
+- **Building Block Deployment**: Automatic prioritization of `*_bb-*` folders during deployment, marked with 🧱 in results
+- **Process Application Support**: Resources in folders with `.process-application` file marked with 📦 in results
+- **Enhanced Deployment Results**: Table view showing file paths, visual indicators, resource details, and versions
+- **Watch Mode**: Monitors a folder for changes to `*.{bpmn,dmn,form}` and auto-redeploys 
 - **Flexible Output**: Switch between human-readable text and JSON output modes
 
+## Beware the 🤖
+
+*Full transparency*:  
+this cli is also a pilot-coding experiment.  
+Guided by humans, the codebase is (mostly) built by your friendly neighborhood LLM, fully dogfooding the Human-in-the-Loop pattern.
+
 ## Architecture
 
 ### Core Components
@@ -57,38 +64,103 @@ After installation, the CLI is available as `c8ctl` (or its alias `c8`).
 
 ## Usage
 
-### Basic Commands
+### Getting Help
 
 ```bash
-# Show help
+# Show general help
 c8ctl help
 
+# Show detailed help for specific commands with all flags
+c8ctl help list      # Shows all list resources and their flags
+c8ctl help get       # Shows all get resources and their flags
+c8ctl help create    # Shows all create resources and their flags
+c8ctl help complete  # Shows all complete resources and their flags
+
 # Show version
 c8ctl --version
+```
 
-# List process instances (using alias 'pi')
-c8ctl list pi
-# Or using full command name
-c8ctl list process-instances
+### Basic Commands
 
-# Get process instance by key
-c8ctl get pi 123456
-c8ctl get process-instance 123456
+```bash
+# List and get resources (use aliases pi, pd, ut, inc for convenience)
+c8ctl list pi                          # List process instances
+c8ctl list pd                          # List process definitions
+c8ctl get pi 123456                    # Get process instance by key
+c8ctl get pi 123456 --variables        # Get process instance with variables
+c8ctl get pd 123456 --xml              # Get process definition as XML
 
 # Create process instance
-c8ctl create pi --bpmnProcessId=myProcess
-c8ctl create process-instance --bpmnProcessId=myProcess
+c8ctl create pi --id=myProcess
+c8ctl create process-instance --id=myProcess
+
+# Create process instance and wait for completion
+c8ctl create pi --id=myProcess --awaitCompletion
+
+# Await process instance completion (alias for create with --awaitCompletion)
+c8ctl await pi --id=myProcess
+c8ctl await process-instance --id=myProcess
 
-# Deploy BPMN file
-c8ctl deploy ./my-process.bpmn
+# Cancel process instance
+c8ctl cancel pi 123456
 
-# Deploy current directory
-c8ctl deploy
+# Get forms
+c8ctl get form 123456                        # Get form (searches both user task and process definition)
+c8ctl get form 123456 --ut                   # Get form for user task only
+c8ctl get form 123456 --pd                   # Get start form for process definition only
 
-# Deploy and start process (run)
-c8ctl run ./my-process.bpmn
+# Deploy and run
+c8ctl deploy ./my-process.bpmn         # Deploy a single file
+c8ctl deploy                           # Deploy current directory
+c8ctl run ./my-process.bpmn            # Deploy and start process
+c8ctl watch                            # Watch for changes and auto-deploy
 ```
 
+For comprehensive examples of all commands and their flags, see [EXAMPLES.md](EXAMPLES.md).
+
+### Shell Completion
+
+c8ctl supports shell completion for `bash`, `zsh`, and `fish`. To enable completion:
+
+#### Bash
+
+```bash
+# Generate and source completion script
+c8ctl completion bash > ~/.c8ctl-completion.bash
+echo 'source ~/.c8ctl-completion.bash' >> ~/.bashrc
+source ~/.bashrc
+```
+
+Or for immediate use in the current session:
+
+```bash
+source <(c8ctl completion bash)
+```
+
+#### Zsh
+
+```bash
+# Generate and source completion script
+c8ctl completion zsh > ~/.c8ctl-completion.zsh
+echo 'source ~/.c8ctl-completion.zsh' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Or for immediate use in the current session:
+
+```bash
+source <(c8ctl completion zsh)
+```
+
+#### Fish
+
+```bash
+# Generate and install completion script
+c8ctl completion fish > ~/.config/fish/completions/c8ctl.fish
+```
+
+Fish will automatically load the completion on next shell start.
+
 ### Credential Resolution
 
 Credentials are resolved in the following order:
@@ -209,7 +281,7 @@ 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.
+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.
 
 ```bash
 # Load a plugin from npm registry
@@ -224,13 +296,27 @@ c8ctl load plugin --from git://github.com/user/repo.git
 # Unload a plugin (wraps npm uninstall)
 c8ctl unload plugin <package-name>
 
-# List installed plugins
+# List installed plugins (shows sync status)
 c8ctl list plugins
 
+# Synchronize plugins from registry
+# - First tries npm rebuild for installed plugins
+# - Falls back to fresh npm install if rebuild fails
+c8ctl sync plugins
+
 # View help including plugin commands
 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)
+- `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
+- `c8ctl sync plugins` synchronizes plugins from the registry, rebuilding or reinstalling as needed
+
 **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
@@ -265,6 +351,7 @@ When plugins are loaded, their commands automatically appear in `c8ctl help` out
 ### Resource Aliases
 
 - `pi` = process-instance(s)
+- `pd` = process-definition(s)
 - `ut` = user-task(s)
 - `inc` = incident(s)
 - `msg` = message
@@ -275,9 +362,32 @@ When plugins are loaded, their commands automatically appear in `c8ctl help` out
 c8ctl <verb> <resource> [arguments] [flags]
 ```
 
-**Verbs**: list, get, create, cancel, complete, fail, activate, resolve, publish, correlate, deploy, run, add, remove, use, output
-
-**Resources**: process-instance, user-task, incident, job, message, topology, profile, tenant
+**Verbs**: 
+- `list` - List resources
+- `get` - Get resource by key
+- `create` - Create resource
+- `cancel` - Cancel resource
+- `complete` - Complete resource
+- `fail` - Fail a job
+- `activate` - Activate jobs
+- `resolve` - Resolve incident
+- `publish` - Publish message
+- `correlate` - Correlate message
+- `deploy` - Deploy BPMN/DMN/forms
+- `run` - Deploy and start process
+- `watch` (alias: `w`) - Watch for changes and auto-deploy
+- `add` - Add a profile
+- `remove` (alias: `rm`) - Remove a profile
+- `load` - Load a plugin
+- `unload` - Unload a plugin
+- `sync` - Synchronize plugins
+- `use` - Set active profile or tenant
+- `output` - Set output format
+- `completion` - Generate shell completion script
+
+**Resources**: process-instance (pi), process-definition (pd), user-task (ut), incident (inc), job, jobs, message (msg), topology, profile, tenant, plugin
+
+**Tip**: Run `c8ctl help <command>` to see detailed help for specific commands with all available flags.
 
 ## Testing
 
@@ -302,6 +412,9 @@ Integration tests require a running Camunda 8 instance at `http://localhost:8080
 
 ## Development
 
+- **Native TypeScript**: Runs directly with Node.js 22.18+ (no compilation needed)
+
+
 ### Project Structure
 
 ```
@@ -354,7 +467,7 @@ c8ctl <command>
 - `CAMUNDA_BASE_URL`: Cluster base URL
 - `CAMUNDA_CLIENT_ID`: OAuth client ID
 - `CAMUNDA_CLIENT_SECRET`: OAuth client secret
-- `CAMUNDA_AUDIENCE`: OAuth audience
+- `CAMUNDA_TOKEN_AUDIENCE`: OAuth token audience
 - `CAMUNDA_OAUTH_URL`: OAuth token endpoint
 - `CAMUNDA_DEFAULT_TENANT_ID`: Default tenant ID
 
@@ -364,13 +477,14 @@ c8ctl <command>
 
 Configuration is stored in platform-specific user data directories:
 
-- **Linux**: `~/.local/share/c8ctl/`
+- **Linux**: `~/.config/c8ctl/`
 - **macOS**: `~/Library/Application Support/c8ctl/`
 - **Windows**: `%APPDATA%\c8ctl\`
 
 Files:
 - `profiles.json`: Saved cluster configurations
 - `session.json`: Active profile, tenant, and output mode
+- `plugins.json`: Plugin registry tracking installed plugins
 
 ### Camunda Modeler Configuration
 
@@ -388,7 +502,7 @@ Modeler profiles are:
 
 ## License
 
-MIT
+Apache 2.0 - see LICENSE.md 
 
 ## Contributing
 

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAG9F;;GAEG;AACH,wBAAgB,YAAY,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa,CAgChE"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAuB,KAAK,aAAa,EAAuB,MAAM,qCAAqC,CAAC;AAGnH;;GAEG;AACH,wBAAgB,YAAY,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa,CAgChE"}

package/dist/client.js

@@ -18,7 +18,7 @@ export function createClient(profileFlag) {
         sdkConfig.CAMUNDA_CLIENT_ID = config.clientId;
         sdkConfig.CAMUNDA_CLIENT_SECRET = config.clientSecret;
         if (config.audience) {
-            sdkConfig.CAMUNDA_OAUTH_AUDIENCE = config.audience;
+            sdkConfig.CAMUNDA_TOKEN_AUDIENCE = config.audience;
         }
         if (config.oAuthUrl) {
             sdkConfig.CAMUNDA_OAUTH_URL = config.oAuthUrl;

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAsB,MAAM,qCAAqC,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,WAAoB;IAC/C,MAAM,MAAM,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAEjD,kCAAkC;IAClC,MAAM,SAAS,GAAQ;QACrB,oBAAoB,EAAE,MAAM,CAAC,OAAO;KACrC,CAAC;IAEF,qCAAqC;IACrC,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QAC3C,SAAS,CAAC,qBAAqB,GAAG,OAAO,CAAC;QAC1C,SAAS,CAAC,iBAAiB,GAAG,MAAM,CAAC,QAAQ,CAAC;QAC9C,SAAS,CAAC,qBAAqB,GAAG,MAAM,CAAC,YAAY,CAAC;QACtD,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,SAAS,CAAC,sBAAsB,GAAG,MAAM,CAAC,QAAQ,CAAC;QACrD,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,SAAS,CAAC,iBAAiB,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChD,CAAC;IACH,CAAC;IACD,0CAA0C;SACrC,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC5C,SAAS,CAAC,qBAAqB,GAAG,OAAO,CAAC;QAC1C,SAAS,CAAC,2BAA2B,GAAG,MAAM,CAAC,QAAQ,CAAC;QACxD,SAAS,CAAC,2BAA2B,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC1D,CAAC;IACD,oBAAoB;SACf,CAAC;QACJ,SAAS,CAAC,qBAAqB,GAAG,MAAM,CAAC;IAC3C,CAAC;IAED,OAAO,mBAAmB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;AACpD,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAA2C,MAAM,qCAAqC,CAAC;AACnH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,WAAoB;IAC/C,MAAM,MAAM,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAEjD,kCAAkC;IAClC,MAAM,SAAS,GAAsC;QACnD,oBAAoB,EAAE,MAAM,CAAC,OAAO;KACrC,CAAC;IAEF,qCAAqC;IACrC,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QAC3C,SAAS,CAAC,qBAAqB,GAAG,OAAO,CAAC;QAC1C,SAAS,CAAC,iBAAiB,GAAG,MAAM,CAAC,QAAQ,CAAC;QAC9C,SAAS,CAAC,qBAAqB,GAAG,MAAM,CAAC,YAAY,CAAC;QACtD,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,SAAS,CAAC,sBAAsB,GAAG,MAAM,CAAC,QAAQ,CAAC;QACrD,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,SAAS,CAAC,iBAAiB,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChD,CAAC;IACH,CAAC;IACD,0CAA0C;SACrC,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC5C,SAAS,CAAC,qBAAqB,GAAG,OAAO,CAAC;QAC1C,SAAS,CAAC,2BAA2B,GAAG,MAAM,CAAC,QAAQ,CAAC;QACxD,SAAS,CAAC,2BAA2B,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC1D,CAAC;IACD,oBAAoB;SACf,CAAC;QACJ,SAAS,CAAC,qBAAqB,GAAG,MAAM,CAAC;IAC3C,CAAC;IAED,OAAO,mBAAmB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;AACpD,CAAC"}

package/dist/commands/completion.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shell completion commands
+ */
+/**
+ * Show completion command
+ */
+export declare function showCompletion(shell?: string): void;
+//# sourceMappingURL=completion.d.ts.map

package/dist/commands/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AAAA;;GAEG;AA8pBH;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA0BnD"}