camunda-cli 0.2.0

package/src/client.js

@@ -0,0 +1,400 @@
+// Camunda 7 Engine REST API client.
+//
+// Auth is plain HTTP Basic on every request; the engine REST API has no session or token
+// exchange to reuse. Verified against a live 7.24 multi-tenant deployment.
+//
+// Two behaviours here are not obvious from the API docs and were added after watching a
+// real deployment misbehave:
+//   * Transient 401/403 responses. A load-balanced engine will intermittently reject a
+//     perfectly good credential while a replica is unhealthy; observed five consecutive
+//     401s followed by five 200s, same credential, half a second apart. Without a retry a
+//     caller concludes "the password is wrong" and goes looking in the wrong place.
+//   * Accept headers. Most endpoints speak JSON, but /job/{id}/stacktrace returns
+//     text/plain and answers 406 to an Accept: application/json request.
+
+const RETRYABLE = new Set([401, 403, 500, 502, 503, 504]);
+
+function normalizeBaseUrl(url) {
+  return String(url).replace(/\/+$/, '');
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export class Client {
+  constructor({ baseUrl, username, password, retries = 3, timeout = 60000 }) {
+    this.baseUrl = normalizeBaseUrl(baseUrl);
+    this.authHeader =
+      username || password ? 'Basic ' + Buffer.from(`${username ?? ''}:${password ?? ''}`).toString('base64') : null;
+    this.retries = retries;
+    this.timeout = timeout;
+    this.lastRetried = 0;
+  }
+
+  buildUrl(path, query) {
+    let url = this.baseUrl + path;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (v === undefined || v === null || v === '') continue;
+        params.set(k, String(v));
+      }
+      const qs = params.toString();
+      if (qs) url += '?' + qs;
+    }
+    return url;
+  }
+
+  async request(method, path, { query, body, accept = 'application/json' } = {}) {
+    const url = this.buildUrl(path, query);
+    const headers = { Accept: accept };
+    if (this.authHeader) headers.Authorization = this.authHeader;
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+
+    let lastError;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      let res;
+      try {
+        res = await fetch(url, {
+          method,
+          headers,
+          body: body !== undefined ? JSON.stringify(body) : undefined,
+          signal: AbortSignal.timeout(this.timeout),
+        });
+      } catch (err) {
+        lastError = new Error(`${method} ${path} -> ${err.message}`);
+        if (attempt === this.retries) throw lastError;
+        await sleep(300 * (attempt + 1));
+        continue;
+      }
+
+      if (res.ok) {
+        if (attempt > 0) this.lastRetried = attempt;
+        if (res.status === 204) return null;
+        const text = await res.text();
+        if (accept !== 'application/json') return text;
+        return text ? JSON.parse(text) : null;
+      }
+
+      // A 4xx that carries a Camunda error body is a real answer, not a flaky replica:
+      // retrying it just delays the report. Bodyless 401/403 from a proxy is retryable.
+      const raw = await res.text();
+      let parsed = null;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        /* html or empty */
+      }
+      const isDefinitive = parsed && (parsed.message || parsed.type);
+      const err = new Error(`${method} ${path} -> ${parsed?.message || `HTTP ${res.status}`}`);
+      err.status = res.status;
+      err.body = parsed ?? raw;
+
+      if (isDefinitive || !RETRYABLE.has(res.status) || attempt === this.retries) throw err;
+      lastError = err;
+      await sleep(300 * (attempt + 1));
+    }
+    throw lastError;
+  }
+
+  get(path, query, opts) {
+    return this.request('GET', path, { query, ...opts });
+  }
+
+  // --- engine ---------------------------------------------------------------
+  engines() {
+    return this.get('/engine');
+  }
+  version() {
+    return this.get('/version');
+  }
+
+  // --- process definitions --------------------------------------------------
+  processDefinitions(query) {
+    return this.get('/process-definition', query);
+  }
+  processDefinitionCount(query) {
+    return this.get('/process-definition/count', query);
+  }
+  processDefinition(id) {
+    return this.get(`/process-definition/${encodeURIComponent(id)}`);
+  }
+  processDefinitionXml(id) {
+    return this.get(`/process-definition/${encodeURIComponent(id)}/xml`);
+  }
+  // Instance and incident counts per activity: the data behind Cockpit's diagram badges,
+  // and the quickest answer to "where is everything piling up".
+  processDefinitionStatistics(id, query) {
+    return this.get(`/process-definition/${encodeURIComponent(id)}/statistics`, {
+      incidents: true,
+      failedJobs: true,
+      ...query,
+    });
+  }
+  calledProcessDefinitions(id) {
+    return this.get(`/process-definition/${encodeURIComponent(id)}/static-called-process-definitions`);
+  }
+  startByDefinitionId(id, body) {
+    return this.request('POST', `/process-definition/${encodeURIComponent(id)}/start`, { body });
+  }
+  suspendDefinition(id, suspended) {
+    return this.request('PUT', `/process-definition/${encodeURIComponent(id)}/suspended`, {
+      body: { suspended, includeProcessInstances: false },
+    });
+  }
+
+  // --- process instances ----------------------------------------------------
+  processInstances(query) {
+    return this.get('/process-instance', query);
+  }
+  processInstance(id) {
+    return this.get(`/process-instance/${id}`);
+  }
+  processInstanceVariables(id) {
+    return this.get(`/process-instance/${id}/variables`);
+  }
+  setProcessInstanceVariable(id, name, value) {
+    return this.request('PUT', `/process-instance/${id}/variables/${encodeURIComponent(name)}`, { body: value });
+  }
+  // Where the tokens are *right now*, as a tree. History tells you where they have been.
+  activityInstanceTree(id) {
+    return this.get(`/process-instance/${id}/activity-instances`);
+  }
+  deleteProcessInstance(id, { reason, skipCustomListeners = true, skipIoMappings = true } = {}) {
+    return this.request('DELETE', `/process-instance/${id}`, {
+      query: { skipCustomListeners, skipIoMappings, deleteReason: reason },
+    });
+  }
+  suspendProcessInstance(id, suspended) {
+    return this.request('PUT', `/process-instance/${id}/suspended`, { body: { suspended } });
+  }
+
+  // --- history --------------------------------------------------------------
+  historyProcessInstances(query) {
+    return this.get('/history/process-instance', query);
+  }
+  historyProcessInstance(id) {
+    return this.get(`/history/process-instance/${id}`);
+  }
+  historyActivityInstances(query) {
+    return this.get('/history/activity-instance', query);
+  }
+  historyVariableInstances(query) {
+    return this.get('/history/variable-instance', query);
+  }
+  // Each individual write to a variable, with revision and timestamp. Requires the engine
+  // history level to be FULL; returns an empty list on lower levels rather than failing.
+  historyDetails(query) {
+    return this.get('/history/detail', query);
+  }
+  historyTasks(query) {
+    return this.get('/history/task', query);
+  }
+  // Survives the job itself. A failed job that was later deleted or retried away still has
+  // its exception recorded here, which /job alone cannot tell you.
+  historyJobLog(query) {
+    return this.get('/history/job-log', query);
+  }
+  historyJobLogStacktrace(id) {
+    return this.get(`/history/job-log/${id}/stacktrace`, undefined, { accept: 'text/plain' });
+  }
+  // Includes resolved incidents; /incident only lists open ones.
+  historyIncidents(query) {
+    return this.get('/history/incident', query);
+  }
+  historyUserOperations(query) {
+    return this.get('/history/user-operation', query);
+  }
+  historyExternalTaskLog(query) {
+    return this.get('/history/external-task-log', query);
+  }
+
+  // --- incidents and jobs ---------------------------------------------------
+  incidents(query) {
+    return this.get('/incident', query);
+  }
+  jobs(query) {
+    return this.get('/job', query);
+  }
+  job(id) {
+    return this.get(`/job/${id}`);
+  }
+  jobStacktrace(id) {
+    return this.get(`/job/${id}/stacktrace`, undefined, { accept: 'text/plain' });
+  }
+  setJobRetries(id, retries) {
+    return this.request('PUT', `/job/${id}/retries`, { body: { retries } });
+  }
+  executeJob(id) {
+    return this.request('POST', `/job/${id}/execute`);
+  }
+  jobDefinitions(query) {
+    return this.get('/job-definition', query);
+  }
+  externalTasks(query) {
+    return this.get('/external-task', query);
+  }
+
+  // --- deployments ----------------------------------------------------------
+  deployments(query) {
+    return this.get('/deployment', query);
+  }
+  deploymentResources(id) {
+    return this.get(`/deployment/${id}/resources`);
+  }
+  deleteDeployment(id, { cascade = false } = {}) {
+    return this.request('DELETE', `/deployment/${id}`, { query: { cascade } });
+  }
+  async deploy(name, files, { tenantId } = {}) {
+    const form = new FormData();
+    form.set('deployment-name', name);
+    form.set('deploy-changed-only', 'true');
+    if (tenantId) form.set('tenant-id', tenantId);
+    for (const { filename, buffer } of files) {
+      form.set(filename, new Blob([buffer]), filename);
+    }
+    const headers = { Accept: 'application/json' };
+    if (this.authHeader) headers.Authorization = this.authHeader;
+    const res = await fetch(`${this.baseUrl}/deployment/create`, { method: 'POST', headers, body: form });
+    if (!res.ok) {
+      const raw = await res.text();
+      let parsed = null;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        /* ignore */
+      }
+      const err = new Error(`POST /deployment/create -> ${parsed?.message || `HTTP ${res.status}`}`);
+      err.status = res.status;
+      err.body = parsed ?? raw;
+      throw err;
+    }
+    return res.json();
+  }
+
+  // --- tasks ----------------------------------------------------------------
+  tasks(query) {
+    return this.get('/task', query);
+  }
+  task(id) {
+    return this.get(`/task/${id}`);
+  }
+  taskVariables(id) {
+    return this.get(`/task/${id}/variables`);
+  }
+  taskIdentityLinks(id) {
+    return this.get(`/task/${id}/identity-links`);
+  }
+  completeTask(id, variables) {
+    return this.request('POST', `/task/${id}/complete`, { body: { variables } });
+  }
+  claimTask(id, userId) {
+    return this.request('POST', `/task/${id}/claim`, { body: { userId } });
+  }
+  unclaimTask(id) {
+    return this.request('POST', `/task/${id}/unclaim`);
+  }
+  setTaskAssignee(id, userId) {
+    return this.request('POST', `/task/${id}/assignee`, { body: { userId } });
+  }
+
+  // --- messages and signals -------------------------------------------------
+  correlateMessage(body) {
+    return this.request('POST', '/message', { body });
+  }
+  throwSignal(body) {
+    return this.request('POST', '/signal', { body });
+  }
+  eventSubscriptions(query) {
+    return this.get('/event-subscription', query);
+  }
+
+  // --- identity -------------------------------------------------------------
+  users(query) {
+    return this.get('/user', query);
+  }
+  groups(query) {
+    return this.get('/group', query);
+  }
+  tenants(query) {
+    return this.get('/tenant', query);
+  }
+}
+
+const VARIABLE_TYPES = ['String', 'Integer', 'Long', 'Short', 'Double', 'Boolean', 'Date', 'Json', 'Null'];
+
+// Accepts name=value, name=value:Type, or name:=<json>. Type defaults to String, which is
+// what Camunda assumes too, but an explicit type matters for gateway conditions that
+// compare numerically: "300" > 200 is false as a string comparison.
+export function parseVariableFlags(varArgs = []) {
+  const variables = {};
+  for (const raw of varArgs) {
+    const jsonEq = raw.indexOf(':=');
+    if (jsonEq > 0) {
+      const name = raw.slice(0, jsonEq);
+      variables[name] = { value: JSON.parse(raw.slice(jsonEq + 2)), type: 'Json' };
+      continue;
+    }
+
+    const eq = raw.indexOf('=');
+    if (eq === -1) throw new Error(`Invalid --var "${raw}". Use name=value, name=value:Type, or name:=<json>.`);
+    const name = raw.slice(0, eq);
+    let rest = raw.slice(eq + 1);
+    let type = 'String';
+
+    const colon = rest.lastIndexOf(':');
+    if (colon !== -1) {
+      const candidate = rest.slice(colon + 1);
+      const match = VARIABLE_TYPES.find((t) => t.toLowerCase() === candidate.toLowerCase());
+      if (match) {
+        type = match;
+        rest = rest.slice(0, colon);
+      }
+    }
+
+    let value = rest;
+    if (type === 'Integer' || type === 'Long' || type === 'Short') {
+      value = parseInt(rest, 10);
+      if (Number.isNaN(value)) throw new Error(`--var ${name}: "${rest}" is not a whole number.`);
+    } else if (type === 'Double') {
+      value = parseFloat(rest);
+      if (Number.isNaN(value)) throw new Error(`--var ${name}: "${rest}" is not a number.`);
+    } else if (type === 'Boolean') {
+      if (rest !== 'true' && rest !== 'false') throw new Error(`--var ${name}: expected true or false, got "${rest}".`);
+      value = rest === 'true';
+    } else if (type === 'Null') {
+      value = null;
+    }
+    variables[name] = { value, type };
+  }
+  return variables;
+}
+
+// Resolves a bare process definition key to a single definition, taking tenancy into
+// account. A key repeated across tenants is the normal case in AlurKerja, and the engine's
+// own key-based endpoints answer "no matching process definition ... and no tenant-id"
+// in that situation, which reads like the process is missing when it is not.
+export async function resolveDefinition(client, keyOrId, { tenant, version } = {}) {
+  if (keyOrId.includes(':')) return client.processDefinition(keyOrId);
+
+  const query = { key: keyOrId };
+  if (tenant) query.tenantIdIn = tenant;
+  if (version) query.version = version;
+  else query.latestVersion = true;
+
+  const matches = await client.processDefinitions(query);
+  if (matches.length === 0) {
+    const anywhere = await client.processDefinitions({ key: keyOrId, latestVersion: true });
+    if (anywhere.length > 0) {
+      const tenants = anywhere.map((d) => d.tenantId ?? '(no tenant)').join(', ');
+      throw new Error(`No definition "${keyOrId}" for tenant ${tenant}. It exists under: ${tenants}.`);
+    }
+    throw new Error(`No process definition with key "${keyOrId}".`);
+  }
+  if (matches.length > 1) {
+    const list = matches.map((d) => `  ${d.id}  tenant=${d.tenantId ?? '-'}  version=${d.version}`).join('\n');
+    throw new Error(
+      `"${keyOrId}" exists in ${matches.length} tenants. Narrow it with --tenant <id>, or pass the full definition id:\n${list}`
+    );
+  }
+  return matches[0];
+}

package/src/commands/definitions.js

@@ -0,0 +1,194 @@
+import { writeFileSync } 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';
+
+export async function definitionsCommand(options) {
+  const client = new Client(requireConfig());
+  const query = { maxResults: options.limit ?? 50, sortBy: 'key', sortOrder: 'asc' };
+  if (options.key) query.keyLike = `%${options.key}%`;
+  if (options.name) query.nameLike = `%${options.name}%`;
+  if (options.tenant) query.tenantIdIn = options.tenant;
+  if (options.latest) query.latestVersion = true;
+
+  const defs = await client.processDefinitions(query);
+  if (out.isJsonMode()) return out.json(defs);
+  if (defs.length === 0) return out.note('No process definitions match.');
+
+  out.table(
+    ['KEY', 'NAME', 'VER', 'TENANT', 'ID'],
+    defs.map((d) => [d.key, out.truncate(d.name ?? '', 34), String(d.version), d.tenantId ?? '-', d.id])
+  );
+  out.note(`\n${defs.length} definition(s)${options.latest ? ', latest version only' : ''}`);
+}
+
+// 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);
+
+  let stats = [];
+  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 });
+  }
+
+  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'],
+  ]);
+
+  if (model.lanes.length > 0) {
+    out.line('\nLanes');
+    out.table(null, model.lanes.map((l) => [l.name || l.id, `${l.nodeRefs.length} element(s)`]));
+  }
+
+  out.line('\nFlow nodes');
+  const rows = model.nodes.map((n) => {
+    const live = liveByActivity.get(n.id);
+    const marks = [];
+    if (n.async) marks.push(`async:${n.async}`);
+    if (n.multiInstance) marks.push(`multi:${n.multiInstance}`);
+    if (n.event?.type) marks.push(n.event.timer ? `${n.event.type}:${n.event.timer.value}` : n.event.type);
+    if (n.assignee) marks.push(`assignee=${n.assignee}`);
+    if (n.calledElement) marks.push(`calls=${n.calledElement}`);
+    const addon = n.listeners.find((l) => l.addon)?.addon;
+    if (addon) marks.push(`addon=${addon.addon}/${addon.action}${addon.config ? `#${addon.config}` : ''}`);
+    if (n.formFields.length) marks.push(`${n.formFields.length} field(s)`);
+    return [n.type, n.id, out.truncate(n.name, 30), live?.instances ? `[${live.instances} here]` : '', marks.join(' ')];
+  });
+  out.table(['TYPE', 'ID', 'NAME', 'LIVE', 'DETAIL'], rows);
+
+  out.line('\nSequence flows');
+  out.table(
+    ['FROM', 'TO', 'LABEL', 'CONDITION'],
+    model.flows.map((f) => [f.source, f.target, out.truncate(f.name, 14), f.condition ?? ''])
+  );
+
+  const withForms = model.nodes.filter((n) => n.formFields.length > 0);
+  if (withForms.length > 0) {
+    out.line('\nForm fields');
+    for (const n of withForms) {
+      out.line(`  ${n.id} (${n.name || n.type})`);
+      out.table(
+        null,
+        n.formFields.map((f) => [`    ${f.name}`, f.type, f.required ? 'required' : '', f.disabled ? 'read-only' : '']),
+        { indent: '' }
+      );
+    }
+  }
+
+  const addons = model.nodes.flatMap((n) => n.listeners.filter((l) => l.addon).map((l) => ({ node: n, l })));
+  if (addons.length > 0) {
+    out.line('\nIntegrations');
+    out.table(
+      ['ELEMENT', 'EVENT', 'ADDON', 'ACTION', 'CONFIG'],
+      addons.map(({ node, l }) => [node.id, `${l.kind}[${l.event}]`, l.addon.addon ?? '-', l.addon.action ?? '-', l.addon.config ?? '-'])
+    );
+  }
+
+  if (!options.noLint) {
+    const findings = lintProcess(model);
+    const errors = findings.filter((f) => f.severity === 'error').length;
+    const warnings = findings.filter((f) => f.severity === 'warning').length;
+    if (findings.length > 0) {
+      out.note(`\n${errors} error(s), ${warnings} warning(s) from static checks. Run "camunda lint ${keyOrId}" for detail.`);
+    }
+  }
+}
+
+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 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 (wanted.length === 0) {
+    out.line(`${def.key} v${def.version}: nothing to report.`);
+    return;
+  }
+
+  out.heading(`${def.key} v${def.version}`);
+  for (const f of wanted) {
+    const tag = f.severity === 'error' ? 'ERROR  ' : f.severity === 'warning' ? 'WARNING' : 'INFO   ';
+    out.line(`\n${tag} ${f.rule}  ${f.element}`);
+    for (const l of out.wrap(f.message, 88)) out.line(`        ${l}`);
+  }
+
+  const errors = wanted.filter((f) => f.severity === 'error').length;
+  out.note(`\n${wanted.length} finding(s)${options.all ? '' : ', info suppressed (use --all)'}`);
+  if (errors > 0) process.exitCode = 1;
+}
+
+export async function xmlCommand(keyOrId, options) {
+  const client = new Client(requireConfig());
+  const def = await resolveDefinition(client, keyOrId, options);
+  const { bpmn20Xml } = await client.processDefinitionXml(def.id);
+
+  if (options.output) {
+    writeFileSync(options.output, bpmn20Xml);
+    out.note(`Saved ${def.id} to ${options.output} (${bpmn20Xml.length} bytes).`);
+  } else {
+    console.log(bpmn20Xml);
+  }
+}
+
+// Answers "where are all the instances of this process sitting, and what is broken",
+// which is the diagram-badge view in Cockpit expressed as a table.
+export async function statsCommand(keyOrId, options) {
+  const client = new Client(requireConfig());
+  const def = await resolveDefinition(client, keyOrId, options);
+  const [stats, xmlRes] = await Promise.all([
+    client.processDefinitionStatistics(def.id),
+    client.processDefinitionXml(def.id),
+  ]);
+  const model = readProcess(xmlRes.bpmn20Xml);
+  const names = new Map(model.nodes.map((n) => [n.id, n.name || n.id]));
+
+  if (out.isJsonMode()) return out.json(stats);
+  if (stats.length === 0) {
+    out.note(`No running instances of ${def.key} v${def.version}.`);
+    return;
+  }
+
+  out.heading(`${def.key} v${def.version}`);
+  out.table(
+    ['ACTIVITY', 'NAME', 'INSTANCES', 'FAILED JOBS', 'INCIDENTS'],
+    stats.map((s) => [
+      s.id,
+      out.truncate(names.get(s.id) ?? '', 30),
+      String(s.instances),
+      String(s.failedJobs ?? 0),
+      String((s.incidents ?? []).reduce((a, i) => a + i.incidentCount, 0)),
+    ])
+  );
+  const total = stats.reduce((a, s) => a + s.instances, 0);
+  out.note(`\n${total} instance(s) across ${stats.length} activity/activities`);
+}
+
+function stripRaw(model) {
+  return { ...model, nodes: model.nodes.map(({ raw, ...rest }) => rest) };
+}

package/src/commands/deploy.js

@@ -0,0 +1,82 @@
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { Client } from '../client.js';
+import { requireConfig } from '../config.js';
+import { readProcess } from '../bpmn.js';
+import { lintProcess } from '../lint.js';
+import * as out from '../output.js';
+
+export async function deploymentsCommand(options) {
+  const client = new Client(requireConfig());
+  const query = { maxResults: options.limit ?? 20, sortBy: 'deploymentTime', sortOrder: 'desc' };
+  if (options.tenant) query.tenantIdIn = options.tenant;
+  if (options.name) query.nameLike = `%${options.name}%`;
+
+  const deployments = await client.deployments(query);
+  if (out.isJsonMode()) return out.json(deployments);
+  if (deployments.length === 0) return out.note('No deployments found.');
+
+  out.table(
+    ['ID', 'NAME', 'DEPLOYED', 'TENANT'],
+    deployments.map((d) => [d.id, out.truncate(d.name ?? '-', 34), out.formatDateTime(d.deploymentTime), d.tenantId ?? '-'])
+  );
+}
+
+// Lints before deploying by default. Pushing a model whose gateway conditions cannot all
+// be satisfied only moves the failure to the first instance that runs it, and by then the
+// stack trace is much further from the cause.
+export async function deployCommand(files, options) {
+  const client = new Client(requireConfig());
+
+  const payload = files.map((file) => ({ filename: basename(file), buffer: readFileSync(file), path: file }));
+
+  if (!options.skipLint) {
+    let blocking = 0;
+    for (const f of payload) {
+      if (!/\.bpmn$/i.test(f.filename)) continue;
+      let findings;
+      try {
+        findings = lintProcess(readProcess(f.buffer.toString('utf8')));
+      } catch (err) {
+        out.warn(`${f.filename}: could not be parsed for checks (${err.message})`);
+        continue;
+      }
+      const errors = findings.filter((x) => x.severity === 'error');
+      if (errors.length === 0) continue;
+      blocking += errors.length;
+      out.problem(`${f.filename}`);
+      for (const e of errors) {
+        out.line(`  ${e.rule}  ${e.element}`);
+        for (const l of out.wrap(e.message, 90)) out.note(`    ${l}`);
+      }
+    }
+    if (blocking > 0) {
+      out.line('');
+      out.problem(`${blocking} blocking issue(s). Deploy anyway with --skip-lint.`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const name = options.name || payload.map((p) => p.filename).join(', ');
+  const result = await client.deploy(name, payload, { tenantId: options.tenant });
+
+  if (out.isJsonMode()) return out.json(result);
+
+  out.line(`Deployed "${name}" as deployment ${result.id}`);
+  const defs = Object.values(result.deployedProcessDefinitions ?? {});
+  if (defs.length === 0) {
+    out.note('No new process definition version was created: the content is identical to what is already deployed.');
+    return;
+  }
+  out.table(
+    ['KEY', 'VERSION', 'ID'],
+    defs.map((d) => [d.key, String(d.version), d.id])
+  );
+}
+
+export async function undeployCommand(id, options) {
+  const client = new Client(requireConfig());
+  await client.deleteDeployment(id, { cascade: options.cascade });
+  out.line(`Deployment ${id} deleted${options.cascade ? ' along with its instances and history' : ''}.`);
+}