camunda-cli 0.2.0

package/src/commands/session.js

@@ -0,0 +1,112 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { Client } from '../client.js';
+import { saveConfig, clearConfig, requireConfig } from '../config.js';
+import * as out from '../output.js';
+
+const CTRL_C = '\x03';
+const BACKSPACE = /[\x7f\x08]/;
+
+// readline echoes what you type; this mutes it for the password prompt only.
+function askHidden(question) {
+  stdout.write(question);
+  let buffer = '';
+  return new Promise((resolve) => {
+    const cleanup = () => {
+      stdin.setRawMode?.(false);
+      stdin.pause();
+      stdin.removeListener('data', onData);
+    };
+    const onData = (chunk) => {
+      const char = chunk.toString();
+      if (char === '\n' || char === '\r') {
+        cleanup();
+        stdout.write('\n');
+        resolve(buffer);
+        return;
+      }
+      if (char === CTRL_C) {
+        cleanup();
+        stdout.write('\n');
+        process.exit(1);
+      }
+      if (BACKSPACE.test(char)) {
+        buffer = buffer.slice(0, -1);
+        return;
+      }
+      buffer += char;
+    };
+    stdin.setRawMode?.(true);
+    stdin.resume();
+    stdin.on('data', onData);
+  });
+}
+
+export async function loginCommand(url, options) {
+  let baseUrl = url;
+  // A frequent mistake is pointing at the webapp root rather than the REST root.
+  if (!/\/engine-rest\/?$/.test(baseUrl) && !options.noSuffix) {
+    baseUrl = baseUrl.replace(/\/+$/, '') + '/engine-rest';
+    out.note(`Using ${baseUrl} (pass --no-suffix to use the URL exactly as given).`);
+  }
+
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const username = options.username || (await rl.question('Username: '));
+    rl.close();
+    const password = options.password || (await askHidden('Password: '));
+
+    const client = new Client({ baseUrl, username, password });
+    // /engine answers without auth on some setups, so prove the credential on an
+    // endpoint that actually requires it.
+    const [engines, count] = await Promise.all([client.engines(), client.processDefinitionCount()]);
+
+    saveConfig({ baseUrl, username, password, engineName: engines[0]?.name ?? 'default' });
+    out.line(`Logged in to ${baseUrl} as ${username}.`);
+    out.note(`Engine "${engines[0]?.name ?? 'default'}", ${count.count} process definitions deployed.`);
+  } catch (err) {
+    rl.close();
+    if (err.status === 401) {
+      throw new Error(`Login failed: the engine rejected these credentials (HTTP 401).`);
+    }
+    throw new Error(`Login failed: ${err.message}`);
+  }
+}
+
+export function logoutCommand() {
+  clearConfig();
+  out.note('Local session cleared.');
+}
+
+export async function whoamiCommand() {
+  const config = requireConfig();
+  const client = new Client(config);
+  const [engines, defs, insts, incidents] = await Promise.all([
+    client.engines(),
+    client.processDefinitionCount(),
+    client.get('/process-instance/count'),
+    client.get('/incident/count'),
+  ]);
+
+  if (out.isJsonMode()) {
+    return out.json({
+      baseUrl: config.baseUrl,
+      username: config.username,
+      engines: engines.map((e) => e.name),
+      processDefinitions: defs.count,
+      runningInstances: insts.count,
+      openIncidents: incidents.count,
+    });
+  }
+
+  out.kv(
+    [
+      ['user', config.username],
+      ['engine', `${config.baseUrl} (${engines.map((e) => e.name).join(', ')})`],
+      ['definitions', defs.count],
+      ['running', insts.count],
+      ['incidents', incidents.count > 0 ? `${incidents.count} open` : '0'],
+    ],
+    ''
+  );
+}

package/src/commands/tasks.js

@@ -0,0 +1,129 @@
+import { Client, parseVariableFlags } from '../client.js';
+import { requireConfig } from '../config.js';
+import { readProcess } from '../bpmn.js';
+import { unwrapError, explain } from '../errors.js';
+import * as out from '../output.js';
+
+export async function tasksCommand(options) {
+  const client = new Client(requireConfig());
+  const query = { maxResults: options.limit ?? 50 };
+  if (options.assignee) query.assignee = options.assignee;
+  if (options.instance) query.processInstanceId = options.instance;
+  if (options.key) query.processDefinitionKey = options.key;
+  if (options.tenant) query.tenantIdIn = options.tenant;
+  if (options.unassigned) query.unassigned = true;
+
+  const tasks = await client.tasks(query);
+  if (out.isJsonMode()) return out.json(tasks);
+  if (tasks.length === 0) return out.note('No open tasks match.');
+
+  out.table(
+    ['ID', 'NAME', 'ASSIGNEE', 'CREATED', 'INSTANCE'],
+    tasks.map((t) => [t.id, out.truncate(t.name, 34), t.assignee ?? 'unassigned', out.formatDateTime(t.created), t.processInstanceId])
+  );
+  out.note(`\n${tasks.length} open task(s)`);
+}
+
+// Shows what completing this task actually requires. The form fields come from the
+// deployed model, because AlurKerja keeps its form definition in an extension attribute
+// that the engine's own form endpoints do not read.
+export async function taskCommand(id) {
+  const client = new Client(requireConfig());
+  const task = await client.task(id);
+
+  const [variables, definition] = await Promise.all([
+    client.taskVariables(id).catch(() => ({})),
+    client.processDefinitionXml(task.processDefinitionId).catch(() => null),
+  ]);
+
+  let fields = [];
+  if (definition) {
+    try {
+      const model = readProcess(definition.bpmn20Xml);
+      fields = model.nodes.find((n) => n.id === task.taskDefinitionKey)?.formFields ?? [];
+    } catch {
+      /* an unparsable model should not stop the task from being shown */
+    }
+  }
+
+  if (out.isJsonMode()) return out.json({ task, variables, formFields: fields });
+
+  out.heading(`Task ${task.id}: ${task.name}`);
+  out.kv([
+    ['element', task.taskDefinitionKey],
+    ['assignee', task.assignee ?? 'unassigned'],
+    ['instance', task.processInstanceId],
+    ['definition', task.processDefinitionId],
+    ['created', out.formatDateTime(task.created)],
+    ['due', out.formatDateTime(task.due)],
+    ['tenant', task.tenantId ?? '-'],
+  ]);
+
+  if (fields.length > 0) {
+    out.line('\nForm fields');
+    out.table(
+      ['NAME', 'TYPE', 'REQUIRED', 'LABEL'],
+      fields.map((f) => [f.name, f.type, f.required ? 'yes' : '', f.disabled ? `${f.label} (read-only)` : f.label])
+    );
+    const writable = fields.filter((f) => !f.disabled);
+    if (writable.length > 0) {
+      out.note(`\ncamunda complete ${id} ${writable.map((f) => `--var ${f.name}=<value>`).join(' ')}`);
+    }
+  } else {
+    out.note('\nNo form fields declared on this element.');
+  }
+
+  const names = Object.keys(variables);
+  if (names.length > 0) {
+    out.line('\nVisible variables');
+    out.table(null, names.map((n) => [`  ${n}`, variables[n].type, out.truncate(JSON.stringify(variables[n].value), 60)]));
+  }
+}
+
+export async function completeCommand(id, options) {
+  const client = new Client(requireConfig());
+  const variables = parseVariableFlags(options.var);
+
+  try {
+    await client.completeTask(id, variables);
+  } catch (err) {
+    // Anything the task triggers synchronously fails here rather than becoming an
+    // incident, so this response is the only place the cause is ever recorded.
+    const unwrapped = unwrapError(err.body?.message || err.message);
+    out.problem(`Could not complete task ${id}.`);
+    out.line(`\n${unwrapped.message}`);
+    for (const layer of unwrapped.layers) {
+      const text = typeof layer.value === 'string' ? layer.value : JSON.stringify(layer.value, null, 2);
+      out.note(`\n${layer.label}:`);
+      for (const l of text.split('\n')) out.note(`  ${l}`);
+    }
+    const hint = explain(err.body?.message || err.message);
+    if (hint) {
+      out.line('');
+      for (const l of out.wrap(hint, 92)) out.line(l);
+    }
+    out.note('\nThe task is untouched; the whole completion rolled back.');
+    process.exitCode = 1;
+    return;
+  }
+
+  out.line(`Task ${id} completed.`);
+
+  if (!options.noWait) {
+    await new Promise((r) => setTimeout(r, options.wait ?? 1000));
+    const task = await client.task(id).catch(() => null);
+    void task;
+  }
+}
+
+export async function claimCommand(id, options) {
+  const client = new Client(requireConfig());
+  if (options.unclaim) {
+    await client.unclaimTask(id);
+    return out.line(`Task ${id} unassigned.`);
+  }
+  const config = requireConfig();
+  const user = options.user || config.username;
+  await client.setTaskAssignee(id, user);
+  out.line(`Task ${id} assigned to ${user}.`);
+}

package/src/config.js

@@ -0,0 +1,33 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CONFIG_DIR = join(homedir(), '.config', 'camunda-cli');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+export function loadConfig() {
+  if (!existsSync(CONFIG_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function saveConfig(config) {
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+export function clearConfig() {
+  if (existsSync(CONFIG_FILE)) writeFileSync(CONFIG_FILE, '{}');
+}
+
+export function requireConfig() {
+  const config = loadConfig();
+  if (!config || !config.baseUrl || !config.username) {
+    console.error('Not logged in. Run: camunda login <engine-rest-url>');
+    process.exit(1);
+  }
+  return config;
+}

package/src/errors.js

@@ -0,0 +1,138 @@
+// Camunda surfaces failures as one long string with the real cause buried several
+// layers deep. Observed against a live AlurKerja deployment, an addon script failure
+// arrives as: a REST message, containing a Java exception, containing `body: {json}`,
+// whose `output` field is itself a JSON *string* holding the message that actually
+// tells you what went wrong. This module peels that apart and, where the error is a
+// well-known Camunda one, says what usually causes it.
+
+const NESTED_BODY = /body:\s*(\{[\s\S]*)$/;
+
+// Pulls out every layer we can parse. Returns { raw, layers[], message } where
+// `message` is the deepest human-readable sentence found.
+export function unwrapError(raw) {
+  const text = typeof raw === 'string' ? raw : raw?.message || String(raw);
+  const layers = [];
+  let deepest = text;
+
+  const bodyMatch = text.match(NESTED_BODY);
+  if (bodyMatch) {
+    const parsed = tryParse(bodyMatch[1]);
+    if (parsed) {
+      layers.push({ label: 'integration response', value: parsed });
+      if (typeof parsed.output === 'string') {
+        const inner = tryParse(parsed.output);
+        if (inner) {
+          layers.push({ label: 'script output', value: inner });
+          if (inner.message) deepest = inner.message;
+        } else if (parsed.output.trim()) {
+          layers.push({ label: 'script output', value: parsed.output.trim() });
+          deepest = parsed.output.trim();
+        }
+      } else if (parsed.message) {
+        deepest = parsed.message;
+      } else if (parsed.error) {
+        deepest = parsed.error;
+      }
+    }
+  }
+
+  return { raw: text, layers, message: deepest };
+}
+
+function tryParse(s) {
+  try {
+    const v = JSON.parse(s);
+    return v && typeof v === 'object' ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// Known Camunda failure signatures, each with the cause we actually observed in
+// practice rather than a restatement of the message.
+const HINTS = [
+  {
+    match: /Cannot resolve identifier 'initiator'/,
+    hint: () =>
+      `The variable "initiator" is injected by AlurKerja when a process is started through its own API. ` +
+      `Starting the same process straight through the Camunda REST API skips that, so any element using ` +
+      `\${initiator} (usually a task assignee) fails as soon as it is reached. Start it with ` +
+      `--var initiator=<userId> to stand in for the real caller.`,
+  },
+  {
+    match: /Unknown property used in expression: \$\{([^}]*)\}.*Cannot resolve identifier '([^']+)'/,
+    hint: (m) =>
+      `Nothing has ever set the variable "${m[2]}" on this instance, and the expression reads it directly, ` +
+      `so the engine throws instead of treating it as null. Either set it before this point, or rewrite the ` +
+      `expression as \${execution.getVariable('${m[2]}')} which yields null instead of throwing. ` +
+      `Check for a name mismatch first: a form field named slightly differently is the usual cause.`,
+  },
+  {
+    match: /ENGINE-02004 No outgoing sequence flow for the element with id '([^']+)'/,
+    hint: (m) =>
+      `Gateway "${m[1]}" evaluated every outgoing flow condition to false and has no default flow, ` +
+      `so the token has nowhere to go. Either make the conditions exhaustive (a > and a < leave the ` +
+      `equal case uncovered) or mark one flow as the gateway's default.`,
+  },
+  {
+    match: /ENGINE-02001 .*more than one outgoing sequence flow/,
+    hint: () =>
+      `Several conditions on an exclusive gateway were true at once. Exclusive gateways take exactly one ` +
+      `path, so tighten the conditions until they are mutually exclusive.`,
+  },
+  {
+    match: /Alurkerja Integration failed/,
+    hint: () =>
+      `The addon behind this service task returned an error. The script's own message is shown above under ` +
+      `"script output"; the service task itself is fine, the failure is inside the addon action.`,
+  },
+  {
+    match: /ENGINE-13030|correlat\w+ .*ambiguous|more than one .*subscription/i,
+    hint: () =>
+      `A message matched more than one waiting subscription. This is usually several versions of the ` +
+      `receiving process still deployed and active at once, not a modelling mistake in the sender.`,
+  },
+  {
+    match: /OptimisticLockingException/,
+    hint: () =>
+      `Two transactions touched the same row at once. Camunda normally retries this by itself; if it keeps ` +
+      `surfacing, something outside the engine is writing to the same instance concurrently.`,
+  },
+  {
+    match: /no processes deployed with key '([^']+)'|No matching process definition with key: ([^\s]+) and no tenant-id/,
+    hint: (m) =>
+      `The key exists under a tenant, not at the root. Pass --tenant <tenantId>; "camunda definitions -k ${m[1] || m[2]}" ` +
+      `lists which tenant holds it.`,
+  },
+];
+
+export function explain(message) {
+  for (const { match, hint } of HINTS) {
+    const m = String(message || '').match(match);
+    if (m) return hint(m);
+  }
+  return null;
+}
+
+// Camunda stacktraces are ~90 lines of engine internals. The frames worth reading are
+// the exception header and anything that is not org.camunda.bpm.engine.impl.*.
+export function condenseStacktrace(trace, { keep = 12 } = {}) {
+  const lines = String(trace || '').split('\n');
+  const header = [];
+  const interesting = [];
+  for (const l of lines) {
+    const t = l.trim();
+    if (!t) continue;
+    if (!t.startsWith('at ')) {
+      header.push(t);
+      continue;
+    }
+    if (/^at (org\.camunda\.bpm\.engine\.impl|java\.|jakarta\.|javax\.|sun\.|jdk\.)/.test(t)) continue;
+    interesting.push(t);
+  }
+  return {
+    header,
+    frames: interesting.slice(0, keep),
+    omitted: lines.filter((l) => l.trim().startsWith('at ')).length - Math.min(interesting.length, keep),
+  };
+}

package/src/lint.js

@@ -0,0 +1,244 @@
+// Static checks over a deployed BPMN model.
+//
+// Every rule here exists because the failure it describes was reproduced against a real
+// engine first, not because it seemed plausible. The messages name the specific element
+// and say what to change, since the output is mostly read by tooling that will act on it.
+
+import { collectExpressions, readVariables, collectWrittenVariables } from './bpmn.js';
+
+const GATEWAYS = new Set(['exclusiveGateway', 'inclusiveGateway', 'complexGateway']);
+const START_TYPES = new Set(['startEvent']);
+const END_TYPES = new Set(['endEvent']);
+
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (Math.abs(m - n) > 4) return 99;
+  const d = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
+  for (let j = 0; j <= n; j++) d[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+  }
+  return d[m][n];
+}
+
+function similarNames(target, candidates) {
+  const prefix = target.includes('_') ? target.slice(0, target.indexOf('_') + 1) : null;
+  return candidates.filter((c) => {
+    if (c === target) return false;
+    if (prefix && c.startsWith(prefix)) return true;
+    return levenshtein(c.toLowerCase(), target.toLowerCase()) <= 3;
+  });
+}
+
+// Reads `${x > 300}` style comparisons so a gateway's branches can be checked for gaps.
+function parseComparison(expression) {
+  const m = String(expression || '').match(
+    /\$\{\s*([A-Za-z_$][\w$]*)\s*(==|!=|>=|<=|>|<)\s*(-?\d+(?:\.\d+)?)\s*\}/
+  );
+  if (!m) return null;
+  return { variable: m[1], op: m[2], value: Number(m[3]) };
+}
+
+export function lintProcess(model, { engineVariables = [] } = {}) {
+  const findings = [];
+  const add = (severity, rule, element, message) => findings.push({ severity, rule, element, message });
+
+  const byId = new Map(model.nodes.map((n) => [n.id, n]));
+  const outgoing = new Map();
+  const incoming = new Map();
+  for (const f of model.flows) {
+    if (!outgoing.has(f.source)) outgoing.set(f.source, []);
+    if (!incoming.has(f.target)) incoming.set(f.target, []);
+    outgoing.get(f.source).push(f);
+    incoming.get(f.target).push(f);
+  }
+
+  // --- dangling references -------------------------------------------------
+  for (const f of model.flows) {
+    if (!byId.has(f.source)) add('error', 'dangling-flow', f.id, `Sequence flow starts at "${f.source}", which is not an element in this process.`);
+    if (!byId.has(f.target)) add('error', 'dangling-flow', f.id, `Sequence flow ends at "${f.target}", which is not an element in this process.`);
+  }
+  for (const n of model.nodes) {
+    if (n.attachedTo && !byId.has(n.attachedTo)) {
+      add('error', 'dangling-boundary', n.id, `Boundary event is attached to "${n.attachedTo}", which does not exist.`);
+    }
+  }
+
+  // --- reachability --------------------------------------------------------
+  const starts = model.nodes.filter((n) => START_TYPES.has(n.type) && !n.scope);
+  if (starts.length === 0) add('error', 'no-start-event', model.id, 'The process has no start event, so nothing can ever begin it.');
+
+  const reachable = new Set();
+  const queue = starts.map((s) => s.id);
+  while (queue.length) {
+    const id = queue.shift();
+    if (reachable.has(id)) continue;
+    reachable.add(id);
+    for (const f of outgoing.get(id) || []) queue.push(f.target);
+  }
+  for (const n of model.nodes) {
+    if (n.scope || n.attachedTo || START_TYPES.has(n.type)) continue;
+    if (!reachable.has(n.id)) {
+      add('warning', 'unreachable', n.id, `"${n.name || n.id}" cannot be reached from any start event.`);
+    }
+  }
+  for (const n of model.nodes) {
+    if (n.scope || n.attachedTo) continue;
+    if (!END_TYPES.has(n.type) && (outgoing.get(n.id) || []).length === 0) {
+      add('warning', 'dead-end', n.id, `"${n.name || n.id}" has no outgoing sequence flow, so the token stops there without reaching an end event.`);
+    }
+  }
+
+  // --- gateway branching ---------------------------------------------------
+  for (const n of model.nodes) {
+    if (!GATEWAYS.has(n.type)) continue;
+    const outs = outgoing.get(n.id) || [];
+    if (outs.length < 2) continue;
+
+    const conditional = outs.filter((f) => f.condition);
+    const unconditional = outs.filter((f) => !f.condition && f.id !== n.defaultFlow);
+
+    if (conditional.length === outs.length && !n.defaultFlow) {
+      add(
+        'error',
+        'no-default-flow',
+        n.id,
+        `Every outgoing flow of "${n.name || n.id}" has a condition and there is no default flow. ` +
+          `If they all evaluate false at runtime the engine raises ENGINE-02004 and the instance stops. ` +
+          `Mark one flow as the default.`
+      );
+
+      // Numeric gap: a > N and a < N leave a == N with nowhere to go.
+      const comparisons = conditional.map((f) => ({ flow: f, cmp: parseComparison(f.condition) })).filter((c) => c.cmp);
+      const byVar = new Map();
+      for (const c of comparisons) {
+        if (!byVar.has(c.cmp.variable)) byVar.set(c.cmp.variable, []);
+        byVar.get(c.cmp.variable).push(c.cmp);
+      }
+      for (const [variable, cmps] of byVar) {
+        if (cmps.length !== conditional.length) continue;
+        const gt = cmps.find((c) => c.op === '>');
+        const lt = cmps.find((c) => c.op === '<');
+        if (gt && lt && gt.value === lt.value && !cmps.some((c) => ['==', '>=', '<='].includes(c.op))) {
+          add(
+            'error',
+            'uncovered-value',
+            n.id,
+            `"${n.name || n.id}" branches on ${variable} > ${gt.value} and ${variable} < ${lt.value}, ` +
+              `so ${variable} == ${gt.value} matches neither branch and the instance will fail there.`
+          );
+        }
+      }
+    }
+
+    if (n.type === 'exclusiveGateway' && unconditional.length > 1) {
+      add(
+        'warning',
+        'ambiguous-branch',
+        n.id,
+        `"${n.name || n.id}" has ${unconditional.length} outgoing flows with no condition. An exclusive gateway ` +
+          `takes the first one it finds, which makes the path taken depend on document order rather than intent.`
+      );
+    }
+  }
+
+  // --- variables read but never written ------------------------------------
+  const written = collectWrittenVariables(model);
+  const knownNames = new Set([...written.keys(), ...engineVariables]);
+  const formFieldNames = [...written.keys()];
+
+  for (const { where, expression, kind } of collectExpressions(model)) {
+    const { direct } = readVariables(expression);
+    for (const v of direct) {
+      if (knownNames.has(v)) continue;
+
+      if (v === 'initiator') {
+        add(
+          'warning',
+          'initiator-expression',
+          where,
+          `Reads \${initiator}. AlurKerja sets that variable when a process is started through its own API, ` +
+            `but starting the same process straight through the Camunda REST API does not, and the step fails ` +
+            `asynchronously with "Cannot resolve identifier 'initiator'". Pass --var initiator=<user> when starting from the CLI.`
+        );
+        continue;
+      }
+
+      const near = similarNames(v, formFieldNames);
+      if (near.length > 0) {
+        add(
+          'error',
+          'variable-name-mismatch',
+          where,
+          `Reads "${v}", which nothing in this process writes, while a form here writes ${near.map((s) => `"${s}"`).join(', ')}. ` +
+            `These names look related, so this is most likely a typo: the expression throws ` +
+            `"Cannot resolve identifier '${v}'" the moment it is evaluated.`
+        );
+      } else {
+        add(
+          'warning',
+          'unwritten-variable',
+          where,
+          `Reads "${v}" directly and nothing in this process writes it. If it is not supplied at start time the ` +
+            `expression throws rather than treating it as null. Use \${execution.getVariable('${v}')} if absent is a valid state.`
+        );
+      }
+    }
+  }
+
+  // --- integration wiring --------------------------------------------------
+  for (const n of model.nodes) {
+    const addonListeners = n.listeners.filter((l) => l.addon);
+    for (const l of addonListeners) {
+      if (!l.addon.config) {
+        add(
+          'warning',
+          'addon-without-config',
+          n.id,
+          `Calls addon "${l.addon.addon}" action "${l.addon.action}" without a config id, so the addon runs with no ` +
+            `Integration Config bound. That is only correct if the addon holds its settings internally.`
+        );
+      }
+    }
+    if (n.type === 'serviceTask' && addonListeners.length > 0 && !n.async) {
+      add(
+        'info',
+        'sync-integration',
+        n.id,
+        `Calls addon "${addonListeners[0].addon.addon}" with no async marker, so the call runs inside the caller's ` +
+          `transaction. A failure here rolls back and surfaces in the HTTP response only: no incident and no job ` +
+          `record is left behind, so "camunda incidents" will show nothing afterwards.`
+      );
+    }
+    if (n.type === 'serviceTask' && addonListeners.length === 0 && !n.class && !n.topic) {
+      const expr = (n.expression || '').trim();
+      if (!expr || expr === '${true}' || expr === 'true') {
+        add(
+          'warning',
+          'no-op-service-task',
+          n.id,
+          `"${n.name || n.id}" is a service task with no implementation behind it (expression ${expr || 'empty'} and no ` +
+            `listener), so it does nothing at runtime beyond passing the token along.`
+        );
+      }
+    }
+  }
+
+  // --- user tasks ----------------------------------------------------------
+  for (const n of model.nodes) {
+    if (n.type !== 'userTask') continue;
+    if (!n.assignee && !n.candidateGroups) {
+      add('info', 'unassigned-user-task', n.id, `"${n.name || n.id}" has neither an assignee nor candidate groups, so it lands in nobody's list until it is claimed.`);
+    }
+    if (n.formFields.length === 0) {
+      add('info', 'no-form', n.id, `"${n.name || n.id}" has no form fields, so completing it submits nothing.`);
+    }
+  }
+
+  const order = { error: 0, warning: 1, info: 2 };
+  findings.sort((a, b) => order[a.severity] - order[b.severity]);
+  return findings;
+}