@camunda8/cli 2.0.0-alpha.4 → 2.0.0-alpha.6

package/README.md

@@ -64,56 +64,54 @@ 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
-
-# List process definitions (using alias 'pd')
-c8ctl list pd
-c8ctl list process-definitions
-
-# Get process instance by key
-c8ctl get pi 123456
-c8ctl get process-instance 123456
-
-# Get process definition by key
-c8ctl get pd 123456
-c8ctl get process-definition 123456
+### Basic Commands
 
-# Get process definition XML
-c8ctl get pd 123456 --xml
+```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 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
 
-# Deploy BPMN file
-c8ctl deploy ./my-process.bpmn
+# Create process instance and wait for completion
+c8ctl create pi --id=myProcess --awaitCompletion
 
-# Deploy current directory
-c8ctl deploy
+# Await process instance completion (alias for create with --awaitCompletion)
+c8ctl await pi --id=myProcess
+c8ctl await process-instance --id=myProcess
 
-# Deploy from multiple paths
-c8ctl deploy ./processes ./forms ./building-blocks
+# Cancel process instance
+c8ctl cancel pi 123456
 
-# Watch mode (using alias 'w')
-c8ctl w
-c8ctl watch
-
-# 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:
@@ -277,7 +275,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
@@ -292,13 +290,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
@@ -344,9 +356,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, process-definition, 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
 
@@ -436,13 +471,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
 

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

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

package/dist/commands/completion.js

@@ -18,13 +18,14 @@ _c8ctl_completions() {
   cword=\${COMP_CWORD}
 
   # Commands (verbs)
-  local verbs="list get create cancel complete fail activate resolve publish correlate deploy run watch add remove rm load unload use output completion help"
+  local verbs="list get create cancel await complete fail activate resolve publish correlate deploy run watch add remove rm load unload sync use output completion help"
   
   # Resources by verb
   local list_resources="process-instances process-instance pi user-tasks user-task ut incidents incident inc jobs profiles profile plugins plugin"
-  local get_resources="process-instance pi topology"
+  local get_resources="process-instance pi process-definition pd topology"
   local create_resources="process-instance pi"
   local cancel_resources="process-instance pi"
+  local await_resources="process-instance pi"
   local complete_resources="user-task ut job"
   local fail_resources="job"
   local activate_resources="jobs"
@@ -35,12 +36,14 @@ _c8ctl_completions() {
   local remove_resources="profile"
   local load_resources="plugin"
   local unload_resources="plugin"
+  local sync_resources="plugin plugins"
   local use_resources="profile tenant"
   local output_resources="json text"
   local completion_resources="bash zsh fish"
+  local help_resources="list get create complete"
 
   # Global flags
-  local flags="--help --version --profile --from --all --bpmnProcessId --processInstanceKey --variables --state --assignee --type --correlationKey --timeToLive --maxJobsToActivate --timeout --worker --retries --errorMessage --baseUrl --clientId --clientSecret --audience --oAuthUrl --defaultTenantId --version_num"
+  local flags="--help --version --profile --from --all --bpmnProcessId --id --processInstanceKey --variables --state --assignee --type --correlationKey --timeToLive --maxJobsToActivate --timeout --worker --retries --errorMessage --baseUrl --clientId --clientSecret --audience --oAuthUrl --defaultTenantId --awaitCompletion --fetchVariables"
 
   case \${cword} in
     1)
@@ -63,6 +66,9 @@ _c8ctl_completions() {
         cancel)
           COMPREPLY=( \$(compgen -W "\${cancel_resources}" -- "\${cur}") )
           ;;
+        await)
+          COMPREPLY=( \$(compgen -W "\${await_resources}" -- "\${cur}") )
+          ;;
         complete)
           COMPREPLY=( \$(compgen -W "\${complete_resources}" -- "\${cur}") )
           ;;
@@ -93,6 +99,9 @@ _c8ctl_completions() {
         unload)
           COMPREPLY=( \$(compgen -W "\${unload_resources}" -- "\${cur}") )
           ;;
+        sync)
+          COMPREPLY=( \$(compgen -W "\${sync_resources}" -- "\${cur}") )
+          ;;
         use)
           COMPREPLY=( \$(compgen -W "\${use_resources}" -- "\${cur}") )
           ;;
@@ -102,6 +111,9 @@ _c8ctl_completions() {
         completion)
           COMPREPLY=( \$(compgen -W "\${completion_resources}" -- "\${cur}") )
           ;;
+        help)
+          COMPREPLY=( \$(compgen -W "\${help_resources}" -- "\${cur}") )
+          ;;
         deploy|run|watch)
           # Complete with files
           COMPREPLY=( \$(compgen -f -- "\${cur}") )
@@ -137,6 +149,7 @@ _c8ctl() {
     'get:Get resource by key'
     'create:Create resource'
     'cancel:Cancel resource'
+    'await:Await resource completion'
     'complete:Complete resource'
     'fail:Fail a job'
     'activate:Activate jobs by type'
@@ -151,10 +164,11 @@ _c8ctl() {
     'rm:Remove a profile'
     'load:Load a c8ctl plugin'
     'unload:Unload a c8ctl plugin'
+    'sync:Synchronize plugins from registry'
     'use:Set active profile or tenant'
     'output:Set output format'
     'completion:Generate shell completion script'
-    'help:Show help'
+    'help:Show help or detailed help for a command'
   )
 
   flags=(
@@ -166,6 +180,7 @@ _c8ctl() {
     '--from[Load plugin from URL]:url:'
     '--all[Show all results]'
     '--bpmnProcessId[Process definition ID]:id:'
+    '--id[Process definition ID (alias for --bpmnProcessId)]:id:'
     '--processInstanceKey[Process instance key]:key:'
     '--variables[JSON variables]:json:'
     '--state[Filter by state]:state:'
@@ -184,7 +199,9 @@ _c8ctl() {
     '--audience[OAuth audience]:audience:'
     '--oAuthUrl[OAuth token endpoint]:url:'
     '--defaultTenantId[Default tenant ID]:id:'
-    '--version_num[Process definition version]:version:'
+    '--version[Process definition version]:version:'
+    '--awaitCompletion[Wait for process instance to complete]'
+    '--fetchVariables[Comma-separated variable names]:variables:'
   )
 
   case \$CURRENT in
@@ -216,6 +233,8 @@ _c8ctl() {
           resources=(
             'process-instance:Get process instance'
             'pi:Get process instance'
+            'process-definition:Get process definition'
+            'pd:Get process definition'
             'topology:Get cluster topology'
           )
           _describe 'resource' resources
@@ -234,6 +253,13 @@ _c8ctl() {
           )
           _describe 'resource' resources
           ;;
+        await)
+          resources=(
+            'process-instance:Await process instance completion'
+            'pi:Await process instance completion'
+          )
+          _describe 'resource' resources
+          ;;
         complete)
           resources=(
             'user-task:Complete user task'
@@ -299,6 +325,13 @@ _c8ctl() {
           )
           _describe 'resource' resources
           ;;
+        sync)
+          resources=(
+            'plugin:Synchronize plugin'
+            'plugins:Synchronize plugins'
+          )
+          _describe 'resource' resources
+          ;;
         use)
           resources=(
             'profile:Set active profile'
@@ -321,6 +354,15 @@ _c8ctl() {
           )
           _describe 'resource' resources
           ;;
+        help)
+          resources=(
+            'list:Show list command help'
+            'get:Show get command help'
+            'create:Show create command help'
+            'complete:Show complete command help'
+          )
+          _describe 'resource' resources
+          ;;
         deploy|run|watch)
           _files
           ;;
@@ -358,6 +400,8 @@ complete -c c8ctl -l all -d 'Show all results'
 complete -c c8 -l all -d 'Show all results'
 complete -c c8ctl -l bpmnProcessId -d 'Process definition ID' -r
 complete -c c8 -l bpmnProcessId -d 'Process definition ID' -r
+complete -c c8ctl -l id -d 'Process definition ID (alias for --bpmnProcessId)' -r
+complete -c c8 -l id -d 'Process definition ID (alias for --bpmnProcessId)' -r
 complete -c c8ctl -l processInstanceKey -d 'Process instance key' -r
 complete -c c8 -l processInstanceKey -d 'Process instance key' -r
 complete -c c8ctl -l variables -d 'JSON variables' -r
@@ -394,8 +438,12 @@ complete -c c8ctl -l oAuthUrl -d 'OAuth token endpoint' -r
 complete -c c8 -l oAuthUrl -d 'OAuth token endpoint' -r
 complete -c c8ctl -l defaultTenantId -d 'Default tenant ID' -r
 complete -c c8 -l defaultTenantId -d 'Default tenant ID' -r
-complete -c c8ctl -l version_num -d 'Process definition version' -r
-complete -c c8 -l version_num -d 'Process definition version' -r
+complete -c c8ctl -l version -d 'Process definition version' -r
+complete -c c8 -l version -d 'Process definition version' -r
+complete -c c8ctl -l awaitCompletion -d 'Wait for process instance to complete'
+complete -c c8 -l awaitCompletion -d 'Wait for process instance to complete'
+complete -c c8ctl -l fetchVariables -d 'Comma-separated variable names' -r
+complete -c c8 -l fetchVariables -d 'Comma-separated variable names' -r
 
 # Commands (verbs) - only suggest when no command is given yet
 complete -c c8ctl -n '__fish_use_subcommand' -a 'list' -d 'List resources'
@@ -406,6 +454,8 @@ complete -c c8ctl -n '__fish_use_subcommand' -a 'create' -d 'Create resource'
 complete -c c8 -n '__fish_use_subcommand' -a 'create' -d 'Create resource'
 complete -c c8ctl -n '__fish_use_subcommand' -a 'cancel' -d 'Cancel resource'
 complete -c c8 -n '__fish_use_subcommand' -a 'cancel' -d 'Cancel resource'
+complete -c c8ctl -n '__fish_use_subcommand' -a 'await' -d 'Await resource completion'
+complete -c c8 -n '__fish_use_subcommand' -a 'await' -d 'Await resource completion'
 complete -c c8ctl -n '__fish_use_subcommand' -a 'complete' -d 'Complete resource'
 complete -c c8 -n '__fish_use_subcommand' -a 'complete' -d 'Complete resource'
 complete -c c8ctl -n '__fish_use_subcommand' -a 'fail' -d 'Fail a job'
@@ -434,12 +484,14 @@ complete -c c8ctl -n '__fish_use_subcommand' -a 'load' -d 'Load a c8ctl plugin'
 complete -c c8 -n '__fish_use_subcommand' -a 'load' -d 'Load a c8ctl plugin'
 complete -c c8ctl -n '__fish_use_subcommand' -a 'unload' -d 'Unload a c8ctl plugin'
 complete -c c8 -n '__fish_use_subcommand' -a 'unload' -d 'Unload a c8ctl plugin'
+complete -c c8ctl -n '__fish_use_subcommand' -a 'sync' -d 'Synchronize plugins from registry'
+complete -c c8 -n '__fish_use_subcommand' -a 'sync' -d 'Synchronize plugins from registry'
 complete -c c8ctl -n '__fish_use_subcommand' -a 'use' -d 'Set active profile or tenant'
 complete -c c8 -n '__fish_use_subcommand' -a 'use' -d 'Set active profile or tenant'
 complete -c c8ctl -n '__fish_use_subcommand' -a 'output' -d 'Set output format'
 complete -c c8 -n '__fish_use_subcommand' -a 'output' -d 'Set output format'
-complete -c c8ctl -n '__fish_use_subcommand' -a 'help' -d 'Show help'
-complete -c c8 -n '__fish_use_subcommand' -a 'help' -d 'Show help'
+complete -c c8ctl -n '__fish_use_subcommand' -a 'help' -d 'Show help or detailed help for a command'
+complete -c c8 -n '__fish_use_subcommand' -a 'help' -d 'Show help or detailed help for a command'
 complete -c c8ctl -n '__fish_use_subcommand' -a 'completion' -d 'Generate shell completion script'
 complete -c c8 -n '__fish_use_subcommand' -a 'completion' -d 'Generate shell completion script'
 
@@ -478,6 +530,10 @@ complete -c c8ctl -n '__fish_seen_subcommand_from get' -a 'process-instance' -d
 complete -c c8 -n '__fish_seen_subcommand_from get' -a 'process-instance' -d 'Get process instance'
 complete -c c8ctl -n '__fish_seen_subcommand_from get' -a 'pi' -d 'Get process instance'
 complete -c c8 -n '__fish_seen_subcommand_from get' -a 'pi' -d 'Get process instance'
+complete -c c8ctl -n '__fish_seen_subcommand_from get' -a 'process-definition' -d 'Get process definition'
+complete -c c8 -n '__fish_seen_subcommand_from get' -a 'process-definition' -d 'Get process definition'
+complete -c c8ctl -n '__fish_seen_subcommand_from get' -a 'pd' -d 'Get process definition'
+complete -c c8 -n '__fish_seen_subcommand_from get' -a 'pd' -d 'Get process definition'
 complete -c c8ctl -n '__fish_seen_subcommand_from get' -a 'topology' -d 'Get cluster topology'
 complete -c c8 -n '__fish_seen_subcommand_from get' -a 'topology' -d 'Get cluster topology'
 
@@ -493,6 +549,12 @@ complete -c c8 -n '__fish_seen_subcommand_from cancel' -a 'process-instance' -d
 complete -c c8ctl -n '__fish_seen_subcommand_from cancel' -a 'pi' -d 'Cancel process instance'
 complete -c c8 -n '__fish_seen_subcommand_from cancel' -a 'pi' -d 'Cancel process instance'
 
+# Resources for 'await' command
+complete -c c8ctl -n '__fish_seen_subcommand_from await' -a 'process-instance' -d 'Await process instance completion'
+complete -c c8 -n '__fish_seen_subcommand_from await' -a 'process-instance' -d 'Await process instance completion'
+complete -c c8ctl -n '__fish_seen_subcommand_from await' -a 'pi' -d 'Await process instance completion'
+complete -c c8 -n '__fish_seen_subcommand_from await' -a 'pi' -d 'Await process instance completion'
+
 # Resources for 'complete' command
 complete -c c8ctl -n '__fish_seen_subcommand_from complete' -a 'user-task' -d 'Complete user task'
 complete -c c8 -n '__fish_seen_subcommand_from complete' -a 'user-task' -d 'Complete user task'
@@ -545,6 +607,12 @@ complete -c c8 -n '__fish_seen_subcommand_from load' -a 'plugin' -d 'Load plugin
 complete -c c8ctl -n '__fish_seen_subcommand_from unload' -a 'plugin' -d 'Unload plugin'
 complete -c c8 -n '__fish_seen_subcommand_from unload' -a 'plugin' -d 'Unload plugin'
 
+# Resources for 'sync' command
+complete -c c8ctl -n '__fish_seen_subcommand_from sync' -a 'plugin' -d 'Synchronize plugin'
+complete -c c8 -n '__fish_seen_subcommand_from sync' -a 'plugin' -d 'Synchronize plugin'
+complete -c c8ctl -n '__fish_seen_subcommand_from sync' -a 'plugins' -d 'Synchronize plugins'
+complete -c c8 -n '__fish_seen_subcommand_from sync' -a 'plugins' -d 'Synchronize plugins'
+
 # Resources for 'use' command
 complete -c c8ctl -n '__fish_seen_subcommand_from use' -a 'profile' -d 'Set active profile'
 complete -c c8 -n '__fish_seen_subcommand_from use' -a 'profile' -d 'Set active profile'
@@ -564,6 +632,16 @@ complete -c c8ctl -n '__fish_seen_subcommand_from completion' -a 'zsh' -d 'Gener
 complete -c c8 -n '__fish_seen_subcommand_from completion' -a 'zsh' -d 'Generate zsh completion'
 complete -c c8ctl -n '__fish_seen_subcommand_from completion' -a 'fish' -d 'Generate fish completion'
 complete -c c8 -n '__fish_seen_subcommand_from completion' -a 'fish' -d 'Generate fish completion'
+
+# Resources for 'help' command
+complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'list' -d 'Show list command help'
+complete -c c8 -n '__fish_seen_subcommand_from help' -a 'list' -d 'Show list command help'
+complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'get' -d 'Show get command help'
+complete -c c8 -n '__fish_seen_subcommand_from help' -a 'get' -d 'Show get command help'
+complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'create' -d 'Show create command help'
+complete -c c8 -n '__fish_seen_subcommand_from help' -a 'create' -d 'Show create command help'
+complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'complete' -d 'Show complete command help'
+complete -c c8 -n '__fish_seen_subcommand_from help' -a 'complete' -d 'Show complete command help'
 `;
 }
 /**

package/dist/commands/completion.js.map

@@ -1 +1 @@
-{"version":3,"file":"completion.js","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;GAEG;AACH,SAAS,sBAAsB;IAC7B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmHR,CAAC;AACF,CAAC;AAED;;GAEG;AACH,SAAS,qBAAqB;IAC5B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8MR,CAAC;AACF,CAAC;AAED;;GAEG;AACH,SAAS,sBAAsB;IAC7B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiOR,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAE3B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC1E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,eAAe,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAE5C,QAAQ,eAAe,EAAE,CAAC;QACxB,KAAK,MAAM;YACT,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC,CAAC;YACtC,MAAM;QACR,KAAK,KAAK;YACR,OAAO,CAAC,GAAG,CAAC,qBAAqB,EAAE,CAAC,CAAC;YACrC,MAAM;QACR,KAAK,MAAM;YACT,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC,CAAC;YACtC,MAAM;QACR;YACE,MAAM,CAAC,KAAK,CAAC,kBAAkB,KAAK,EAAE,CAAC,CAAC;YACxC,MAAM,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;YACjD,MAAM,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;YACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACH,CAAC"}
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;GAEG;AACH,SAAS,sBAAsB;IAC7B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+HR,CAAC;AACF,CAAC;AAED;;GAEG;AACH,SAAS,qBAAqB;IAC5B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4OR,CAAC;AACF,CAAC;AAED;;GAEG;AACH,SAAS,sBAAsB;IAC7B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqQR,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAE3B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC1E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,eAAe,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAE5C,QAAQ,eAAe,EAAE,CAAC;QACxB,KAAK,MAAM;YACT,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC,CAAC;YACtC,MAAM;QACR,KAAK,KAAK;YACR,OAAO,CAAC,GAAG,CAAC,qBAAqB,EAAE,CAAC,CAAC;YACrC,MAAM;QACR,KAAK,MAAM;YACT,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC,CAAC;YACtC,MAAM;QACR;YACE,MAAM,CAAC,KAAK,CAAC,kBAAkB,KAAK,EAAE,CAAC,CAAC;YACxC,MAAM,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;YACjD,MAAM,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;YACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACH,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"deployments.d.ts","sourceRoot":"","sources":["../../src/commands/deployments.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgMH;;GAEG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgMhB"}
+{"version":3,"file":"deployments.d.ts","sourceRoot":"","sources":["../../src/commands/deployments.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgMH;;GAEG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+KhB"}

package/dist/commands/deployments.js

@@ -167,8 +167,8 @@ export async function deploy(paths, options) {
     const logger = getLogger();
     const client = createClient(options.profile);
     const tenantId = resolveTenantId(options.profile);
+    const resources = [];
     try {
-        const resources = [];
         // Store the base paths for relative path calculation
         const basePaths = paths.length === 0 ? [process.cwd()] : paths;
         if (paths.length === 0) {
@@ -318,24 +318,145 @@ export async function deploy(paths, options) {
         }
     }
     catch (error) {
-        // Log detailed error information
-        if (error && typeof error === 'object') {
-            const err = error;
-            logger.error('Failed to deploy resources', error);
-            if (err.response) {
-                console.error('API Response:', err.response);
-            }
-            if (err.message) {
-                console.error('Error message:', err.message);
-            }
-            if (err.cause) {
-                console.error('Error cause:', err.cause);
+        handleDeploymentError(error, resources, logger);
+    }
+}
+/**
+ * Format and display deployment errors with actionable guidance
+ */
+function handleDeploymentError(error, resources, logger) {
+    const raw = (error && typeof error === 'object') ? error : {};
+    // Try to interpret common transport/network issues first for actionable guidance
+    const deriveNetworkErrorTitle = (err) => {
+        const anyErr = err;
+        const code = typeof anyErr?.code === 'string'
+            ? anyErr.code
+            : (typeof anyErr?.cause?.code === 'string'
+                ? anyErr.cause.code
+                : undefined);
+        if (!code && typeof anyErr?.name === 'string') {
+            // Handle fetch/abort style errors
+            if (anyErr.name === 'AbortError') {
+                return 'Request to Camunda cluster timed out or was aborted. Please check your network connection and try again.';
             }
         }
+        switch (code) {
+            case 'ECONNREFUSED':
+                return 'Cannot connect to Camunda cluster (connection refused). Verify the endpoint URL and that the cluster is reachable.';
+            case 'ENOTFOUND':
+                return 'Cannot resolve Camunda cluster host. Check the cluster URL and your DNS/network configuration.';
+            case 'EHOSTUNREACH':
+                return 'Camunda cluster host is unreachable. Check VPN/proxy settings and your network connectivity.';
+            case 'ECONNRESET':
+                return 'Connection to Camunda cluster was reset. Retry the operation and check for intermittent network issues.';
+            case 'ETIMEDOUT':
+                return 'Request to Camunda cluster timed out. Check your network connection and consider retrying.';
+            default:
+                return undefined;
+        }
+    };
+    // Extract RFC 9457 Problem Detail fields and other useful signals
+    const problemTitle = typeof raw.title === 'string' ? raw.title : undefined;
+    const networkTitle = deriveNetworkErrorTitle(error);
+    const errorInstanceTitle = error instanceof Error && typeof error.message === 'string' && error.message
+        ? error.message
+        : undefined;
+    const messageFieldTitle = typeof raw.message === 'string' ? raw.message : undefined;
+    const title = problemTitle ??
+        networkTitle ??
+        errorInstanceTitle ??
+        messageFieldTitle ??
+        'Unknown error (unexpected error format; re-run with increased logging or check network configuration).';
+    const detail = typeof raw.detail === 'string' ? raw.detail : undefined;
+    const status = typeof raw.status === 'number' ? raw.status : undefined;
+    // Display the main error
+    logger.error('Deployment failed', new Error(title));
+    // Display the detailed error message if available
+    if (detail) {
+        console.error('\n' + formatDeploymentErrorDetail(detail));
+    }
+    // Provide actionable hints based on error type
+    console.error('');
+    printDeploymentHints(title, detail, status, resources);
+    process.exit(1);
+}
+/**
+ * Format the error detail for better readability
+ */
+function formatDeploymentErrorDetail(detail) {
+    // The detail often contains embedded newlines, format them nicely
+    const lines = detail.split('\n').map(line => line.trim()).filter(Boolean);
+    // Find the main message and the file-specific errors
+    const result = [];
+    let inFileError = false;
+    for (const line of lines) {
+        if (line.startsWith("'") && (line.includes('.bpmn') || line.includes('.dmn') || line.includes('.form'))) {
+            // This is a file-specific error
+            inFileError = true;
+            result.push(`  📄 ${line}`);
+        }
+        else if (line.startsWith('- Element:')) {
+            result.push(`     ${line}`);
+        }
+        else if (line.startsWith('- ERROR:') || line.startsWith('- WARNING:')) {
+            const icon = line.startsWith('- ERROR:') ? '❌' : '⚠️';
+            result.push(`     ${icon} ${line.substring(2)}`);
+        }
+        else if (inFileError && line.startsWith('-')) {
+            result.push(`     ${line}`);
+        }
         else {
-            logger.error('Failed to deploy resources', error);
+            result.push(`  ${line}`);
+        }
+    }
+    return result.join('\n');
+}
+/**
+ * Print actionable hints based on the error type
+ */
+function printDeploymentHints(title, detail, status, resources) {
+    const hints = [];
+    if (title === 'INVALID_ARGUMENT') {
+        if (detail?.includes('Must reference a message')) {
+            hints.push('💡 A message start event or intermediate catch event is missing a message reference.');
+            hints.push('   Open the BPMN file in Camunda Modeler and configure the message name.');
+        }
+        if (detail?.includes('duplicate')) {
+            hints.push('💡 Resource IDs must be unique within a deployment.');
+            hints.push('   Check for duplicate process/decision IDs in your files.');
+        }
+        if (detail?.includes('parsing') || detail?.includes('syntax')) {
+            hints.push('💡 The resource file contains syntax errors.');
+            hints.push('   Validate the file in Camunda Modeler or check the XML/JSON structure.');
+        }
+    }
+    else if (title === 'RESOURCE_EXHAUSTED') {
+        hints.push('💡 The server is under heavy load (backpressure).');
+        hints.push('   Wait a moment and retry the deployment.');
+    }
+    else if (title === 'NOT_FOUND' || status === 404) {
+        hints.push('💡 The Camunda server could not be reached or the endpoint was not found.');
+        hints.push('   Check your connection settings with: c8 list profiles');
+    }
+    else if (title === 'UNAUTHENTICATED' || title === 'PERMISSION_DENIED' || status === 401 || status === 403) {
+        hints.push('💡 Authentication or authorization failed.');
+        hints.push('   Check your credentials and permissions for the current profile.');
+    }
+    else {
+        hints.push('💡 Review the error message above for specific issues.');
+        hints.push('   You may need to fix the resource files before deploying.');
+    }
+    // Show which files were being deployed
+    if (resources.length > 0) {
+        hints.push('');
+        hints.push(`📁 Resources attempted (${resources.length}):`);
+        resources.slice(0, 5).forEach(r => {
+            hints.push(`   - ${r.relativePath || r.name}`);
+        });
+        if (resources.length > 5) {
+            hints.push(`   ... and ${resources.length - 5} more`);
         }
-        process.exit(1);
     }
+    hints.forEach(h => console.error(h));
 }
 //# sourceMappingURL=deployments.js.map