camunda-cli 0.2.0 → 0.3.0

package/README.md

@@ -63,7 +63,15 @@ Sequence flows
   Gateway_1jk90v6   Activity_retry    no     ${paid == false}
 ```
 
-**Find the bugs before an instance does.** `lint` checks the deployed model statically.
+**Find the bugs before an instance does.** `lint` checks a model statically. It takes a
+deployed key or a local file, so the usual loop is to check while editing and only then
+deploy:
+
+```bash
+camunda lint ./order-process.bpmn     # no engine and no login needed
+camunda lint order-process            # or the deployed version
+```
+
 Every rule exists because that failure was reproduced against a real engine first:
 
 | Rule | What it catches |
@@ -132,10 +140,28 @@ engine's key-based endpoints answer *"no matching process definition ... and no
 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.
+**`start` and `complete` report what happened next.** A start returning HTTP 200 only means
+the engine accepted it; anything marked async runs after the response. Both commands wait a
+moment, then say whether it failed, whether the instance finished, or which task is now
+waiting, along with the exact command to complete it:
+
+```
+$ camunda start order-process --var amount=700:Integer
+Started order-process v9 as instance 3435051
+
+Now waiting at:
+    3435058  check stock  ops
+camunda complete 3435058 --var quantity=<value>
+
+$ camunda complete 3435058 --var quantity=3
+Task 3435058 completed.
+Instance 3435051 finished in 8.0s.
+```
+
+`--no-wait` skips the follow-up.
+
+**Cleaning up after a test run.** `cancel --key <key>` terminates every running instance of
+a process in one go, which matters because testing a model leaves a trail of them behind.
 
 **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>`

package/bin/camunda.js

@@ -24,7 +24,7 @@ program
       'Start with "camunda inspect <key>" to read a deployed model, and\n' +
       '"camunda diagnose <instanceId>" when an instance misbehaves.'
   )
-  .version('0.2.0')
+  .version('0.3.0')
   .option('--json', 'print the raw API payload instead of a formatted view')
   .option('--no-color', 'never emit colour, even on a terminal')
   .showHelpAfterError()
@@ -66,7 +66,7 @@ withVersion(
   withTenant(
     program
       .command('inspect <keyOrId>')
-      .description('Structure of a deployed model: elements, flow conditions, forms, integrations')
+      .description('Structure of a model: elements, flow conditions, forms, integrations. Accepts a deployed key or a local .bpmn file')
       .option('--no-lint', 'skip the static-check summary at the end')
   )
 ).action(inspectCommand);
@@ -75,7 +75,7 @@ withVersion(
   withTenant(
     program
       .command('lint <keyOrId>')
-      .description('Static checks over a deployed model, before an instance has to find the bugs')
+      .description('Static checks over a model, before an instance has to find the bugs. Accepts a deployed key or a local .bpmn file')
       .option('-a, --all', 'include informational findings')
       .addOption(new Option('-s, --severity <level>', 'only one severity').choices(['error', 'warning', 'info']))
   )
@@ -120,12 +120,15 @@ withVersion(
   )
 ).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);
+withTenant(
+  program
+    .command('cancel [id]')
+    .description('Force-terminate one instance, or every instance of a process with --key')
+    .option('-k, --key <definitionKey>', 'cancel every running instance of this process')
+    .option('-b, --business-key <key>', 'with --key, only instances carrying this business key')
+    .option('-r, --reason <text>', 'recorded against the instances')
+    .option('-y, --yes', 'skip the confirmation prompt')
+).action(cancelCommand);
 
 program
   .command('vars <instanceId>')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camunda-cli",
-  "version": "0.2.0",
+  "version": "0.3.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",

package/src/commands/definitions.js

@@ -1,10 +1,28 @@
-import { writeFileSync } from 'node:fs';
+import { writeFileSync, readFileSync, existsSync, statSync } from 'node:fs';
 import { Client, resolveDefinition } from '../client.js';
 import { requireConfig } from '../config.js';
 import { readProcess } from '../bpmn.js';
 import { lintProcess } from '../lint.js';
 import * as out from '../output.js';
 
+// inspect and lint accept a local .bpmn file as well as a deployed key, because the point
+// of checking a model is to do it while editing, before it reaches an engine. A local file
+// needs no credentials either, so the config lookup only happens for the remote path.
+function isLocalFile(target) {
+  return /\.(bpmn|xml|dmn)$/i.test(target) && existsSync(target) && statSync(target).isFile();
+}
+
+async function loadModel(target, options) {
+  if (isLocalFile(target)) {
+    const xml = readFileSync(target, 'utf8');
+    return { model: readProcess(xml), xml, source: { local: target } };
+  }
+  const client = new Client(requireConfig());
+  const def = await resolveDefinition(client, target, options);
+  const { bpmn20Xml } = await client.processDefinitionXml(def.id);
+  return { model: readProcess(bpmn20Xml), xml: bpmn20Xml, source: { definition: def }, client };
+}
+
 export async function definitionsCommand(options) {
   const client = new Client(requireConfig());
   const query = { maxResults: options.limit ?? 50, sortBy: 'key', sortOrder: 'asc' };
@@ -27,32 +45,41 @@ export async function definitionsCommand(options) {
 // Structural view of a deployed model. None of this is available as a REST resource:
 // it is read out of the deployed BPMN XML, which is the only place the engine keeps it.
 export async function inspectCommand(keyOrId, options) {
-  const client = new Client(requireConfig());
-  const def = await resolveDefinition(client, keyOrId, options);
-  const { bpmn20Xml } = await client.processDefinitionXml(def.id);
-  const model = readProcess(bpmn20Xml);
+  const { model, source, client } = await loadModel(keyOrId, options);
+  const def = source.definition;
 
   let stats = [];
-  try {
-    stats = await client.processDefinitionStatistics(def.id);
-  } catch {
-    /* statistics are optional context, not worth failing the command over */
+  if (client && def) {
+    try {
+      stats = await client.processDefinitionStatistics(def.id);
+    } catch {
+      /* statistics are optional context, not worth failing the command over */
+    }
   }
   const liveByActivity = new Map(stats.map((s) => [s.id, s]));
 
   if (out.isJsonMode()) {
-    return out.json({ definition: def, process: stripRaw(model), statistics: stats });
+    return out.json({ definition: def ?? { file: source.local }, process: stripRaw(model), statistics: stats });
   }
 
-  out.heading(`${def.name || def.key}`);
-  out.kv([
-    ['key', def.key],
-    ['id', def.id],
-    ['version', def.version],
-    ['tenant', def.tenantId ?? '-'],
-    ['suspended', def.suspended ? 'yes' : 'no'],
-    ['executable', model.executable ? 'yes' : 'no'],
-  ]);
+  out.heading(def ? def.name || def.key : model.name || model.id);
+  out.kv(
+    def
+      ? [
+          ['key', def.key],
+          ['id', def.id],
+          ['version', def.version],
+          ['tenant', def.tenantId ?? '-'],
+          ['suspended', def.suspended ? 'yes' : 'no'],
+          ['executable', model.executable ? 'yes' : 'no'],
+        ]
+      : [
+          ['file', source.local],
+          ['process id', model.id],
+          ['executable', model.executable ? 'yes' : 'no'],
+          ['status', 'not deployed, read from disk'],
+        ]
+  );
 
   if (model.lanes.length > 0) {
     out.line('\nLanes');
@@ -114,24 +141,22 @@ export async function inspectCommand(keyOrId, options) {
 }
 
 export async function lintCommand(keyOrId, options) {
-  const client = new Client(requireConfig());
-  const def = await resolveDefinition(client, keyOrId, options);
-  const { bpmn20Xml } = await client.processDefinitionXml(def.id);
-  const model = readProcess(bpmn20Xml);
+  const { model, source } = await loadModel(keyOrId, options);
+  const label = source.definition ? `${source.definition.key} v${source.definition.version}` : source.local;
   const findings = lintProcess(model);
 
   const wanted = options.severity
     ? findings.filter((f) => f.severity === options.severity)
     : findings.filter((f) => options.all || f.severity !== 'info');
 
-  if (out.isJsonMode()) return out.json({ definition: def.id, findings: wanted });
+  if (out.isJsonMode()) return out.json({ source: label, findings: wanted });
 
   if (wanted.length === 0) {
-    out.line(`${def.key} v${def.version}: nothing to report.`);
+    out.line(`${label}: nothing to report.`);
     return;
   }
 
-  out.heading(`${def.key} v${def.version}`);
+  out.heading(label);
   for (const f of wanted) {
     const tag = f.severity === 'error' ? 'ERROR  ' : f.severity === 'warning' ? 'WARNING' : 'INFO   ';
     out.line(`\n${tag} ${f.rule}  ${f.element}`);

package/src/commands/diagnose.js

@@ -225,15 +225,18 @@ export async function stacktraceCommand(jobId, options) {
   if (omitted > 0) out.note(`  ... ${omitted} engine-internal frame(s) hidden, use --full for everything`);
 }
 
-// The execution trace. Ordering matters here: several activities routinely share a
-// millisecond, so ties are broken by following the sequence flows rather than trusting
-// the timestamp alone.
+// The execution trace, in the order the engine actually took the steps.
+//
+// Sorting by startTime looks right and is not: a gateway and the events either side of it
+// routinely share a millisecond, and the resulting order is arbitrary within that tie, so
+// a start event can appear halfway down the list. `occurrence` is the engine's own
+// execution sequence and is the only field that reflects real order.
 export async function traceCommand(id, options) {
   const client = new Client(requireConfig());
   const activities = await client.historyActivityInstances({
     processInstanceId: id,
     maxResults: options.limit ?? 200,
-    sortBy: 'startTime',
+    sortBy: 'occurrence',
     sortOrder: 'asc',
   });
 

package/src/commands/instances.js

@@ -2,6 +2,8 @@ import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { Client, parseVariableFlags, resolveDefinition } from '../client.js';
 import { requireConfig } from '../config.js';
+import { readProcess } from '../bpmn.js';
+import { reportNextState, suggestCompletion } from '../followup.js';
 import * as out from '../output.js';
 
 export async function instancesCommand(options) {
@@ -117,46 +119,72 @@ export async function startCommand(keyOrId, options) {
     variables,
   });
 
-  // A start returning 200 only means the engine accepted it. Anything marked async runs
-  // after the response, so a failure there shows up as a job or incident a moment later
-  // rather than in this reply.
-  let trouble = { incidents: [], jobs: [] };
-  if (!options.noWait) {
-    await new Promise((r) => setTimeout(r, options.wait ?? 1200));
-    const [incidents, jobs] = await Promise.all([
-      client.incidents({ processInstanceId: result.id }).catch(() => []),
-      client.jobs({ processInstanceId: result.id, withException: true }).catch(() => []),
-    ]);
-    trouble = { incidents, jobs };
-  }
-
-  if (out.isJsonMode()) return out.json({ ...result, ...trouble });
+  if (out.isJsonMode() && options.noWait) return out.json(result);
 
   out.line(`Started ${def.key} v${def.version} as instance ${result.id}`);
   if (result.businessKey) out.note(`business key ${result.businessKey}`);
+  if (options.noWait) return;
 
-  if (trouble.incidents.length > 0 || trouble.jobs.length > 0) {
-    const msg = trouble.incidents[0]?.incidentMessage || trouble.jobs[0]?.exceptionMessage;
-    out.problem(`\nIt already failed after starting: ${msg}`);
-    out.note(`Run: camunda diagnose ${result.id}`);
-    process.exitCode = 1;
+  // A start returning 200 only means the engine accepted it. Anything marked async runs
+  // after the response, so both a failure and the first user task appear a moment later
+  // rather than in this reply.
+  const next = await reportNextState(client, result.id, { wait: options.wait ?? 1200 });
+  if (next.failed) process.exitCode = 1;
+  else if (next.tasks.length === 1) {
+    out.note(await suggestCompletion(client, next.tasks[0], readProcess));
   }
 }
 
+// Takes either one id or a whole definition's worth of instances. Testing a model leaves
+// a trail of instances behind, and clearing them one confirmation at a time is enough
+// friction that they tend to get left running instead.
 export async function cancelCommand(id, options) {
   const client = new Client(requireConfig());
 
+  if (!id && !options.key) {
+    throw new Error('Give an instance id, or --key <definitionKey> to cancel every running instance of one process.');
+  }
+
+  let targets;
+  if (id) {
+    targets = [id];
+  } else {
+    const query = { processDefinitionKey: options.key, maxResults: 1000 };
+    if (options.tenant) query.tenantIdIn = options.tenant;
+    if (options.businessKey) query.businessKey = options.businessKey;
+    const found = await client.processInstances(query);
+    targets = found.map((i) => i.id);
+    if (targets.length === 0) return out.note(`No running instances of ${options.key}.`);
+  }
+
   if (!options.yes) {
     const rl = createInterface({ input: stdin, output: stdout });
+    const what =
+      targets.length === 1
+        ? `Force-terminating ${targets[0]}`
+        : `Force-terminating all ${targets.length} running instances of ${options.key}`;
+    const expect = targets.length === 1 ? targets[0] : String(targets.length);
     const answer = await rl.question(
-      `Force-terminating ${id} cannot be undone (it ends as EXTERNALLY_TERMINATED, not COMPLETED).\nType the instance id to confirm: `
+      `${what} cannot be undone (they end as EXTERNALLY_TERMINATED, not COMPLETED).\nType "${expect}" to confirm: `
     );
     rl.close();
-    if (answer.trim() !== id) return out.note('Aborted, the id did not match.');
+    if (answer.trim() !== expect) return out.note('Aborted, that did not match.');
+  }
+
+  let done = 0;
+  const failures = [];
+  for (const target of targets) {
+    try {
+      await client.deleteProcessInstance(target, { reason: options.reason });
+      done++;
+    } catch (err) {
+      failures.push(`${target}: ${err.message}`);
+    }
   }
 
-  await client.deleteProcessInstance(id, { reason: options.reason });
-  out.line(`Instance ${id} terminated.`);
+  out.line(`Terminated ${done} instance(s).`);
+  for (const f of failures) out.problem(`  ${f}`);
+  if (failures.length > 0) process.exitCode = 1;
 }
 
 export async function varsCommand(id, options) {

package/src/commands/tasks.js

@@ -1,6 +1,7 @@
 import { Client, parseVariableFlags } from '../client.js';
 import { requireConfig } from '../config.js';
 import { readProcess } from '../bpmn.js';
+import { reportNextState, suggestCompletion } from '../followup.js';
 import { unwrapError, explain } from '../errors.js';
 import * as out from '../output.js';
 
@@ -84,6 +85,13 @@ export async function completeCommand(id, options) {
   const client = new Client(requireConfig());
   const variables = parseVariableFlags(options.var);
 
+  // The task is gone once it completes, so its instance has to be noted beforehand for
+  // the follow-up to have something to report on.
+  const instanceId = await client
+    .task(id)
+    .then((t) => t.processInstanceId)
+    .catch(() => null);
+
   try {
     await client.completeTask(id, variables);
   } catch (err) {
@@ -108,11 +116,12 @@ export async function completeCommand(id, options) {
   }
 
   out.line(`Task ${id} completed.`);
+  if (options.noWait || !instanceId) return;
 
-  if (!options.noWait) {
-    await new Promise((r) => setTimeout(r, options.wait ?? 1000));
-    const task = await client.task(id).catch(() => null);
-    void task;
+  const next = await reportNextState(client, instanceId, { wait: options.wait ?? 1000 });
+  if (next.failed) process.exitCode = 1;
+  else if (next.tasks.length === 1) {
+    out.note(await suggestCompletion(client, next.tasks[0], readProcess));
   }
 }
 

package/src/followup.js

@@ -0,0 +1,60 @@
+// What happened after an action that moves a process forward.
+//
+// Both starting an instance and completing a task leave the caller needing the same three
+// answers: did it break, did it finish, and what is waiting now. Without them every step of
+// driving a process costs an extra round trip to work out where it went, which is most of
+// the effort in testing a model with more than two steps.
+
+import { unwrapError } from './errors.js';
+import * as out from './output.js';
+
+export async function reportNextState(client, instanceId, { wait = 1000 } = {}) {
+  if (wait) await new Promise((r) => setTimeout(r, wait));
+
+  const [historic, incidents, jobs, tasks] = await Promise.all([
+    client.historyProcessInstance(instanceId).catch(() => null),
+    client.incidents({ processInstanceId: instanceId }).catch(() => []),
+    client.jobs({ processInstanceId: instanceId, withException: true }).catch(() => []),
+    client.tasks({ processInstanceId: instanceId }).catch(() => []),
+  ]);
+
+  const failure = incidents[0]?.incidentMessage || jobs[0]?.exceptionMessage || null;
+  const state = historic?.state ?? null;
+
+  if (failure) {
+    out.problem(`\nIt failed after this step: ${unwrapError(failure).message}`);
+    out.note(`camunda diagnose ${instanceId}`);
+    return { state, failed: true, tasks };
+  }
+
+  if (state && state !== 'ACTIVE') {
+    const label = state === 'COMPLETED' ? 'finished' : `ended as ${state}`;
+    out.line(`Instance ${instanceId} ${label}${historic.durationInMillis ? ` in ${out.formatDuration(historic.durationInMillis)}` : ''}.`);
+    return { state, failed: false, tasks: [] };
+  }
+
+  if (tasks.length > 0) {
+    out.line(tasks.length === 1 ? '\nNow waiting at:' : `\nNow waiting at ${tasks.length} tasks:`);
+    out.table(null, tasks.map((t) => [`  ${t.id}`, out.truncate(t.name, 34), t.assignee ?? 'unassigned']));
+    return { state, failed: false, tasks };
+  }
+
+  out.note(`\nStill running, not sitting at a user task. camunda instance ${instanceId}`);
+  return { state, failed: false, tasks: [] };
+}
+
+// The form fields a task needs, read from the deployed model. AlurKerja keeps its form in
+// an extension attribute the engine's own form endpoints do not read, so this goes through
+// the XML instead.
+export async function suggestCompletion(client, task, readProcess) {
+  try {
+    const { bpmn20Xml } = await client.processDefinitionXml(task.processDefinitionId);
+    const model = readProcess(bpmn20Xml);
+    const node = model.nodes.find((n) => n.id === task.taskDefinitionKey);
+    const writable = (node?.formFields ?? []).filter((f) => !f.disabled);
+    if (writable.length === 0) return `camunda complete ${task.id}`;
+    return `camunda complete ${task.id} ${writable.map((f) => `--var ${f.name}=<value>`).join(' ')}`;
+  } catch {
+    return `camunda complete ${task.id}`;
+  }
+}