camunda-cli 0.2.0

package/README.md

@@ -0,0 +1,167 @@
+# camunda-cli
+
+Command-line client for **self-hosted Camunda 7**, aimed at the two things that take the
+most time when developing BPMN: understanding a model that is already deployed, and working
+out why an instance is stuck. Not affiliated with Camunda GmbH.
+
+Built and verified against Camunda 7.24 on a live multi-tenant deployment.
+
+```
+$ camunda lint order-process
+
+ERROR   uncovered-value  Gateway_1jk90v6
+        "amount check" branches on amount > 300 and amount < 300, so amount == 300 matches
+        neither branch and the instance will fail there.
+
+ERROR   variable-name-mismatch  flow Flow_0jpsuir (retry)
+        Reads "input_huruf", which nothing in this process writes, while a form here writes
+        "input_9ltnt". These names look related, so this is most likely a typo: the
+        expression throws "Cannot resolve identifier 'input_huruf'" the moment it is evaluated.
+```
+
+## Install
+
+```bash
+npm install -g camunda-cli
+camunda login https://your-host/engine-rest
+```
+
+`login` prompts for a username and password and stores them in
+`~/.config/camunda-cli/config.json` with mode `0600`. Camunda 7's REST API authenticates
+with HTTP Basic on every request and has no token to exchange, so the password is kept
+rather than a session. It is sent only to the engine you configured.
+
+Installing globally without root:
+
+```bash
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"
+npm install -g camunda-cli
+```
+
+## What it is for
+
+**Read a deployed model.** Much of what you need while debugging — which variable a gateway
+condition reads, whether a step is async, what a service task is actually wired to — is only
+in the deployed XML, not behind any REST resource. `inspect` reads it out and lays it flat.
+
+```bash
+camunda inspect order-process
+```
+
+```
+Flow nodes
+  TYPE              ID                NAME              LIVE      DETAIL
+  startEvent        StartEvent_1      order received              1 field(s)
+  userTask          Activity_11j96l5  check stock       [3 here]  assignee=ops 2 field(s)
+  serviceTask       Activity_0dfmi5x  charge card                 async:before addon=payments/charge#98
+  exclusiveGateway  Gateway_1jk90v6   paid?
+
+Sequence flows
+  FROM              TO                LABEL  CONDITION
+  Gateway_1jk90v6   Event_0ufajup     yes    ${paid == true}
+  Gateway_1jk90v6   Activity_retry    no     ${paid == false}
+```
+
+**Find the bugs before an instance does.** `lint` checks the deployed model statically.
+Every rule exists because that failure was reproduced against a real engine first:
+
+| Rule | What it catches |
+|---|---|
+| `uncovered-value` | `> N` and `< N` branches that leave `== N` with nowhere to go (`ENGINE-02004`) |
+| `no-default-flow` | Every branch conditional, no default: any instance where they all fail stops dead |
+| `variable-name-mismatch` | A condition reads `foo` while the form writes `foo_2`, so the expression throws |
+| `unwritten-variable` | A direct `${x}` read where nothing sets `x`; throws instead of yielding null |
+| `initiator-expression` | `${initiator}`, which exists only when started through AlurKerja's API |
+| `no-op-service-task` | A service task with no implementation behind it |
+| `addon-without-config` | An integration call with no config bound |
+| `unreachable`, `dead-end`, `dangling-flow` | Structural mistakes |
+
+`deploy` runs the same checks and refuses to push a model with blocking issues, unless you
+pass `--skip-lint`.
+
+**Work out why an instance is stuck.** `diagnose` gathers what is scattered across several
+endpoints and unpacks it:
+
+```bash
+camunda diagnose 3426894
+```
+
+```
+Stopped at
+    Activity_CekSisaKuota  transition  Check Remaining Quota
+
+1 problem(s)
+
+  open incident at 2026-08-13 08:19:33
+  failing element: Activity_TinjauPengajuan
+  job attached to:  Activity_CekSisaKuota  (the async marker sits here, the error came from
+                    the element above)
+  Unknown property used in expression: ${initiator}. Cause: Cannot resolve identifier 'initiator'
+```
+
+It reads more than `/incident`, because several real failures are invisible there. A step
+that fails inside the caller's transaction leaves no incident and no job behind at all; an
+incident points at the activity holding the job, which is often not the activity that
+failed; and a resolved incident disappears from `/incident` entirely.
+
+It also unpacks nested integration errors. An addon failure arrives as a REST message
+wrapping a Java exception wrapping a JSON body whose `output` field is itself JSON. The
+sentence you need is at the bottom, so that is what gets printed first.
+
+## Commands
+
+```
+Session      login  logout  whoami
+Models       definitions  inspect  lint  xml  stats
+Instances    instances  instance  start  cancel  vars  set-var
+Diagnosis    diagnose  trace  incidents  jobs  stacktrace
+Tasks        tasks  task  complete  claim
+Deployment   deployments  deploy  undeploy
+Events       message  subscriptions
+Repair       retry  run-job
+Identity     users  groups  tenants
+```
+
+`camunda <command> --help` for the options on any of them.
+
+## Notes that save time
+
+**Tenants.** On a shared engine the same process key exists under many tenants, and the
+engine's key-based endpoints answer *"no matching process definition ... and no tenant-id"*,
+which reads like the process is missing when it is not. Every command taking a key accepts
+`--tenant`, and an ambiguous key lists the candidates rather than guessing.
+
+**`start` waits before reporting success.** A start returning HTTP 200 only means the engine
+accepted it; anything marked async runs after the response. `start` looks for a failure a
+moment later and reports it, instead of leaving you with a green message and a broken
+instance. `--no-wait` skips that.
+
+**Variable types matter.** `--var n=300` sends a string, and `"300" > 200` is a string
+comparison. Use `--var n=300:Integer` where a gateway compares numerically, or `name:=<json>`
+for structured values.
+
+**Transient 401s are retried.** A load-balanced engine will intermittently reject a valid
+credential while a replica is unhealthy: five consecutive 401s followed by five 200s, same
+credential, seconds apart, is a real pattern observed in production. Requests are retried so
+this does not get misread as a wrong password. A 4xx carrying a real Camunda error body is
+never retried.
+
+**Output is meant to be piped.** No box-drawing characters, and no colour unless stdout is a
+terminal. Every command takes `--json` for the raw API payload.
+
+## Requirements
+
+- Node.js 18+
+- A Camunda 7 engine with its REST API enabled
+
+## Not covered
+
+DMN evaluation, batch operations, instance migration and modification, and authorization
+management. These are deliberate omissions rather than oversights: the command surface here
+covers what came up repeatedly while developing and debugging processes, not all 300-odd
+REST endpoints. Pull requests welcome.
+
+## License
+
+MIT

package/bin/camunda.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+import { Command, Option } from 'commander';
+import { configureOutput, isJsonMode } from '../src/output.js';
+import { unwrapError, explain } from '../src/errors.js';
+import { loginCommand, logoutCommand, whoamiCommand } from '../src/commands/session.js';
+import { definitionsCommand, inspectCommand, lintCommand, xmlCommand, statsCommand } from '../src/commands/definitions.js';
+import { instancesCommand, instanceCommand, startCommand, cancelCommand, varsCommand } from '../src/commands/instances.js';
+import { diagnoseCommand, incidentsCommand, jobsCommand, stacktraceCommand, traceCommand } from '../src/commands/diagnose.js';
+import { tasksCommand, taskCommand, completeCommand, claimCommand } from '../src/commands/tasks.js';
+import { deploymentsCommand, deployCommand, undeployCommand } from '../src/commands/deploy.js';
+import {
+  retryCommand, runJobCommand, setVarCommand, messageCommand, subscriptionsCommand,
+  usersCommand, groupsCommand, tenantsCommand,
+} from '../src/commands/ops.js';
+
+const program = new Command();
+const int = (v) => parseInt(v, 10);
+const collect = (v, prev) => [...prev, v];
+
+program
+  .name('camunda')
+  .description(
+    'Command-line client for self-hosted Camunda 7.\n\n' +
+      'Start with "camunda inspect <key>" to read a deployed model, and\n' +
+      '"camunda diagnose <instanceId>" when an instance misbehaves.'
+  )
+  .version('0.2.0')
+  .option('--json', 'print the raw API payload instead of a formatted view')
+  .option('--no-color', 'never emit colour, even on a terminal')
+  .showHelpAfterError()
+  .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.opts();
+    configureOutput({ json: opts.json, color: opts.color });
+  });
+
+// Shared option shapes. Multi-tenancy is not optional in practice: the same process key
+// lives under many tenants in a shared engine, and every key-based lookup needs it.
+const withTenant = (cmd) => cmd.option('-t, --tenant <tenantId>', 'restrict to one tenant');
+const withVersion = (cmd) => cmd.option('--pd-version <n>', 'a specific definition version instead of the latest', int);
+
+// --- session ---------------------------------------------------------------
+program
+  .command('login <url>')
+  .description('Store credentials for an engine (the URL may omit /engine-rest)')
+  .option('-u, --username <username>', 'prompted for if omitted')
+  .option('-p, --password <password>', 'prompted for if omitted, which keeps it out of your shell history')
+  .option('--no-suffix', 'use the URL exactly as given')
+  .action(loginCommand);
+
+program.command('logout').description('Forget the stored credentials').action(logoutCommand);
+program.command('whoami').description('Which engine is configured, and its current totals').action(whoamiCommand);
+
+// --- reading models --------------------------------------------------------
+withTenant(
+  program
+    .command('definitions')
+    .alias('defs')
+    .description('List deployed process definitions')
+    .option('-k, --key <substring>', 'match the definition key')
+    .option('-n, --name <substring>', 'match the definition name')
+    .option('-l, --latest', 'only the newest version of each')
+    .option('--limit <n>', 'maximum rows', int)
+).action(definitionsCommand);
+
+withVersion(
+  withTenant(
+    program
+      .command('inspect <keyOrId>')
+      .description('Structure of a deployed model: elements, flow conditions, forms, integrations')
+      .option('--no-lint', 'skip the static-check summary at the end')
+  )
+).action(inspectCommand);
+
+withVersion(
+  withTenant(
+    program
+      .command('lint <keyOrId>')
+      .description('Static checks over a deployed model, before an instance has to find the bugs')
+      .option('-a, --all', 'include informational findings')
+      .addOption(new Option('-s, --severity <level>', 'only one severity').choices(['error', 'warning', 'info']))
+  )
+).action(lintCommand);
+
+withVersion(
+  withTenant(program.command('xml <keyOrId>').description('The deployed BPMN XML').option('-o, --output <file>', 'write to a file'))
+).action(xmlCommand);
+
+withVersion(
+  withTenant(program.command('stats <keyOrId>').description('How many instances sit at each element, and what is failing there'))
+).action(statsCommand);
+
+// --- instances -------------------------------------------------------------
+withTenant(
+  program
+    .command('instances')
+    .alias('ps')
+    .description('Running instances, or finished ones with --history')
+    .option('-k, --key <definitionKey>')
+    .option('-b, --business-key <key>')
+    .option('-i, --with-incident', 'only instances that have an incident')
+    .option('-H, --history', 'search history instead of running instances')
+    .addOption(new Option('--state <state>', 'with --history').choices(['finished', 'unfinished', 'completed', 'externallyTerminated', 'internallyTerminated']))
+    .option('--limit <n>', 'maximum rows', int)
+).action(instancesCommand);
+
+program
+  .command('instance <id>')
+  .description('One instance: state, where it currently sits, tasks, variables')
+  .action(instanceCommand);
+
+withVersion(
+  withTenant(
+    program
+      .command('start <keyOrId>')
+      .description('Start an instance, then check whether it failed immediately afterwards')
+      .option('-b, --business-key <key>')
+      .option('--var <name=value>', 'repeatable; name=value, name=value:Type, or name:=<json>', collect, [])
+      .option('--no-wait', 'do not look for asynchronous failures after starting')
+      .option('--wait <ms>', 'how long to wait before that check', int)
+  )
+).action(startCommand);
+
+program
+  .command('cancel <id>')
+  .description('Force-terminate a running instance; it ends as EXTERNALLY_TERMINATED')
+  .option('-r, --reason <text>', 'recorded against the instance')
+  .option('-y, --yes', 'skip the confirmation prompt')
+  .action(cancelCommand);
+
+program
+  .command('vars <instanceId>')
+  .description('Variables on an instance, or every write to them with --history')
+  .option('-H, --history', 'each individual update, oldest first')
+  .option('--limit <n>', 'maximum rows', int)
+  .action(varsCommand);
+
+program
+  .command('set-var <instanceId> <name=value>')
+  .description('Overwrite a variable on a running instance')
+  .addOption(new Option('--type <type>').choices(['String', 'Integer', 'Long', 'Double', 'Boolean', 'Json']).default('String'))
+  .action(setVarCommand);
+
+// --- diagnosis -------------------------------------------------------------
+program
+  .command('diagnose <instanceId>')
+  .alias('why')
+  .description('Why an instance is stuck or failed, with the nested integration errors unpacked')
+  .option('--stacktrace', 'include the Java frames behind each failure')
+  .action(diagnoseCommand);
+
+program
+  .command('trace <instanceId>')
+  .description('Every activity this instance has been through, in order')
+  .option('--limit <n>', 'maximum rows', int)
+  .action(traceCommand);
+
+withTenant(
+  program
+    .command('incidents')
+    .description('Open incidents, or every recorded one with --history')
+    .option('-i, --instance <processInstanceId>')
+    .option('-k, --key <definitionKey>')
+    .option('-H, --history', 'include incidents that were already resolved')
+    .option('--limit <n>', 'maximum rows', int)
+).action(incidentsCommand);
+
+program
+  .command('jobs')
+  .description('Pending and failed jobs')
+  .option('-i, --instance <processInstanceId>')
+  .option('-k, --key <definitionKey>')
+  .option('-f, --failed', 'only jobs carrying an exception')
+  .option('--limit <n>', 'maximum rows', int)
+  .action(jobsCommand);
+
+program
+  .command('stacktrace <jobId>')
+  .description('The stack trace behind a failed job, engine internals filtered out')
+  .option('--full', 'every frame, unfiltered')
+  .action(stacktraceCommand);
+
+// --- tasks -----------------------------------------------------------------
+withTenant(
+  program
+    .command('tasks')
+    .description('Open human tasks')
+    .option('-a, --assignee <userId>')
+    .option('-i, --instance <processInstanceId>')
+    .option('-k, --key <definitionKey>')
+    .option('-u, --unassigned')
+    .option('--limit <n>', 'maximum rows', int)
+).action(tasksCommand);
+
+program.command('task <id>').description('One task, with the form fields needed to complete it').action(taskCommand);
+
+program
+  .command('complete <taskId>')
+  .description('Complete a task; anything it triggers synchronously is reported here')
+  .option('--var <name=value>', 'repeatable; name=value, name=value:Type, or name:=<json>', collect, [])
+  .option('--no-wait', 'skip the follow-up check')
+  .action(completeCommand);
+
+program
+  .command('claim <taskId>')
+  .description('Assign a task to yourself or someone else')
+  .option('-u, --user <userId>', 'defaults to the logged-in user')
+  .option('--unclaim', 'remove the assignee instead')
+  .action(claimCommand);
+
+// --- deployment ------------------------------------------------------------
+withTenant(
+  program
+    .command('deployments')
+    .description('Recent deployments')
+    .option('-n, --name <substring>')
+    .option('--limit <n>', 'maximum rows', int)
+).action(deploymentsCommand);
+
+withTenant(
+  program
+    .command('deploy <files...>')
+    .description('Deploy BPMN or DMN files, refusing models with blocking issues')
+    .option('-n, --name <name>', 'deployment name')
+    .option('--skip-lint', 'deploy without the static checks')
+).action(deployCommand);
+
+program
+  .command('undeploy <deploymentId>')
+  .description('Delete a deployment')
+  .option('--cascade', 'also delete its instances and their history')
+  .action(undeployCommand);
+
+// --- events ----------------------------------------------------------------
+program
+  .command('message <name>')
+  .description('Correlate a message to whatever is waiting for it')
+  .option('-i, --instance <processInstanceId>')
+  .option('-b, --business-key <key>')
+  .option('--all', 'correlate to every match rather than requiring exactly one')
+  .action(messageCommand);
+
+program
+  .command('subscriptions')
+  .description('What is currently waiting on a message or signal')
+  .option('-i, --instance <processInstanceId>')
+  .addOption(new Option('--type <type>').choices(['message', 'signal', 'compensate', 'conditional']))
+  .option('--limit <n>', 'maximum rows', int)
+  .action(subscriptionsCommand);
+
+// --- repair ----------------------------------------------------------------
+program
+  .command('retry <jobId>')
+  .description('Give a failed job its retries back so it runs again')
+  .option('-r, --retries <n>', 'defaults to 1', int)
+  .option('--now', 'run it immediately instead of waiting for the scheduler')
+  .action(retryCommand);
+
+program.command('run-job <jobId>').description('Execute a pending job right now').action(runJobCommand);
+
+// --- identity --------------------------------------------------------------
+program
+  .command('users')
+  .description('Engine-local users (these are not your business users when an identity provider is in front)')
+  .option('-s, --search <substring>')
+  .option('--limit <n>', 'maximum rows', int)
+  .action(usersCommand);
+
+program.command('groups').description('Engine-local groups').option('--limit <n>', 'maximum rows', int).action(groupsCommand);
+
+program
+  .command('tenants')
+  .description('Tenants known to the engine')
+  .option('-s, --search <substring>')
+  .option('--limit <n>', 'maximum rows', int)
+  .action(tenantsCommand);
+
+program.parseAsync(process.argv).catch((err) => {
+  if (isJsonMode()) {
+    console.error(JSON.stringify({ error: err.message, status: err.status ?? null, body: err.body ?? null }, null, 2));
+    process.exit(1);
+  }
+  const unwrapped = unwrapError(err.body?.message || err.message);
+  console.error(unwrapped.message);
+  for (const layer of unwrapped.layers) {
+    const text = typeof layer.value === 'string' ? layer.value : JSON.stringify(layer.value, null, 2);
+    console.error(`\n${layer.label}:`);
+    for (const l of text.split('\n')) console.error(`  ${l}`);
+  }
+  const hint = explain(err.body?.message || err.message);
+  if (hint) console.error(`\n${hint}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "camunda-cli",
+  "version": "0.2.0",
+  "description": "Command-line client for self-hosted Camunda 7: inspect and lint deployed BPMN models, and diagnose why an instance is stuck",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itsanla/camunda-cli.git"
+  },
+  "bin": {
+    "camunda": "bin/camunda.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "camunda",
+    "camunda7",
+    "bpmn",
+    "cli",
+    "self-hosted",
+    "workflow",
+    "lint",
+    "debugging"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5"
+  }
+}