@camunda8/cli 2.8.0-alpha.9 → 3.0.0

package/dist/default-plugins/element-template/vendor-src/bundle-entry.js

@@ -0,0 +1,44 @@
+/**
+ * Vendor bundle entry point for the element-template plugin.
+ *
+ * bpmn-js and bpmn-js-element-templates use extensionless ESM imports
+ * internally, which Node.js cannot resolve without a bundler. This file
+ * is bundled with esbuild into a single self-contained CJS module that
+ * is loaded at runtime by the plugin via require().
+ *
+ * Build: npm run build:vendor
+ */
+
+import Modeler from 'bpmn-js-headless/lib/Modeler';
+import { CloudElementTemplatesCoreModule } from 'bpmn-js-element-templates/core';
+import ZeebeModdleExtension from 'zeebe-bpmn-moddle/resources/zeebe.json';
+
+/**
+ * No-op TextRenderer module.
+ *
+ * bpmn-js's BpmnImporter.addLabel calls textRenderer.getExternalLabelBounds
+ * to fit external labels (event/gateway names). The default implementation
+ * creates an SVG <text> via document.createElementNS to measure dimensions
+ * — which throws in Node.js where `document` doesn't exist. The errors are
+ * non-fatal (the importer catches them) but produce noisy stack traces.
+ *
+ * For template application we don't need accurate label measurements:
+ * the input file's existing BPMNLabel bounds are preserved on saveXML.
+ * Returning the input bounds unchanged keeps the importer happy without
+ * touching the DOM.
+ */
+const HeadlessTextRendererModule = {
+  textRenderer: ['type', function HeadlessTextRenderer() {
+    this.getExternalLabelBounds = function(bounds) { return bounds; };
+    this.getTextAnnotationBounds = function(bounds) { return bounds; };
+    this.getDimensions = function() { return { width: 0, height: 0 }; };
+    this.createText = function() { return null; };
+  }],
+};
+
+export {
+  Modeler,
+  CloudElementTemplatesCoreModule,
+  ZeebeModdleExtension,
+  HeadlessTextRendererModule,
+};

package/dist/default-plugins/feel/README.md

@@ -0,0 +1,163 @@
+# c8ctl-plugin-feel
+
+A default [c8ctl](https://github.com/camunda/c8ctl) plugin for
+evaluating [FEEL](https://docs.camunda.io/docs/components/modeler/feel/what-is-feel/)
+expressions. By default uses the connected Camunda cluster's engine
+via the 8.9+ REST API. Use `--engine local` to evaluate in-process
+via [feelin](https://github.com/nikku/feelin) without a cluster connection.
+
+## Usage
+
+```bash
+# Evaluate a simple expression on the cluster (default)
+c8ctl feel evaluate '1 + 2'
+# → 3
+
+# Leading '=' is optional — both forms work
+c8ctl feel evaluate '=1 + 2'
+
+# Pass variables individually
+c8ctl feel evaluate 'a + b' --var a=1 --var b=2
+# → 3
+
+# Tenant-scoped cluster variables
+c8ctl feel evaluate 'camunda.vars.env.API_BASE' --tenant my-tenant
+
+# Compose with other tools — bulk JSON via stdin/file
+c8ctl feel evaluate 'sum(items)' --vars "$(jq -c '{items: .data}' input.json)"
+
+# Evaluate offline via feelin (no cluster needed)
+c8ctl feel evaluate '1 + 2' --engine local
+```
+
+## Warnings
+
+Runtime issues (unknown variables, type mismatches) come back as
+warnings, not errors — `result` falls to `null` and the expression
+still exits 0.
+
+```text
+$ c8ctl feel evaluate 'unknownVar' --engine local
+null
+
+⚠ 1 warning:
+  Variable 'unknownVar' not found (NO_VARIABLE_FOUND)
+```
+
+The trailing `(NO_VARIABLE_FOUND)` is the engine's diagnostic type —
+emitted when available (local engine) and omitted when not (cluster).
+
+In JSON mode warnings expand to the engine's diagnostic shape:
+
+```bash
+c8ctl output json
+c8ctl feel evaluate 'unknownVar' --engine local
+# → {"expression":"unknownVar","result":null,"warnings":[
+#      { "message": "Variable 'unknownVar' not found",
+#        "type": "NO_VARIABLE_FOUND",
+#        "position": { "from": 0, "to": 10 } }
+#    ]}
+```
+
+The envelope `{ expression, result, warnings }` is identical across
+engines. The per-warning fields differ:
+
+| Field | `cluster` | `local` |
+|---|---|---|
+| `message` | always | always |
+| `type` | — | feelin's `WarningType` (`NO_VARIABLE_FOUND`, `INVALID_TYPE`, …) |
+| `position` | — | `{ from, to }` byte offsets in the expression |
+
+JSON consumers should treat `type` and `position` as engine-conditional.
+
+## Engines
+
+| Engine | When | Notes |
+|---|---|---|
+| `cluster` (default) | Connected to a Camunda 8.9+ cluster | Uses `POST /v2/expression/evaluation`. Real Zeebe FEEL semantics, full Camunda extensions, supports tenant-scoped cluster variables. |
+| `local` | Offline or no cluster configured | Uses [feelin](https://github.com/nikku/feelin) in-process. Fast, but **does not support all Camunda FEEL extensions** — result may differ from the cluster engine. |
+
+`feel evaluate` exits non-zero for CLI/input validation errors (missing
+expression, unknown flag, invalid `--engine`, malformed `--var`, invalid
+`--vars` JSON) and for FEEL parse failures. Runtime evaluation issues
+(e.g. unresolved variables) are warnings in the output, not failures,
+because they're the engine's diagnostic output rather than a CLI error.
+
+## Error behaviour
+
+The cluster engine never silently falls back to `--engine local` —
+hidden behaviour is bad, and feelin's missing Camunda extensions
+could give a different answer. When the cluster is unavailable, you
+get an explicit error with a hint:
+
+| Failure | Detection | Behaviour |
+|---|---|---|
+| No cluster configured | client construction fails | error + hint to use `--engine local` |
+| Parse error | 400 | error with cleaned-up FEEL parser message (no hint — fix the expression) |
+| Auth failure | 401 / 403 | error + hint |
+| Cluster pre-8.9 | 404 on `/v2/expression/evaluation` | error noting 8.9 requirement + hint |
+| Anything else (network failure, 5xx, …) | non-400/401/403/404 | generic "cannot connect" error + hint |
+
+The hint always reminds you that feelin behaviour may differ from
+the cluster engine.
+
+## Setting variables
+
+Two flags, mix and match:
+
+- **`--var key=value`** (repeatable) — set a single variable. Path
+  segments separated by `.` nest. The value is parsed as JSON
+  (`42`, `true`, `null`, `[1,2,3]`, `{"a":1}`); if JSON parsing
+  fails the value is taken as a string literal.
+- **`--vars '{...}'`** — bulk-load variables from a JSON object.
+
+When both are given, `--vars` is the base and each `--var` applies
+on top. Within `--var`, last write wins.
+
+```bash
+# Simple values
+c8ctl feel evaluate 'a + b' --var a=10 --var b=5
+# → 15
+
+# Strings (no JSON quoting needed)
+c8ctl feel evaluate 'name' --var name=Alice
+# → Alice
+
+# Booleans, null, numbers — parsed as JSON
+c8ctl feel evaluate 'if active then "yes" else "no"' --var active=true
+# → yes
+
+# Arrays — quote for the shell so '[' isn't globbed
+c8ctl feel evaluate 'sum(items)' --var 'items=[1,2,3,4]'
+# → 10
+
+# Nested via dot path
+c8ctl feel evaluate 'person.name' --var person.name=Alice --var person.age=30
+# → Alice
+
+# Mix --vars (bulk) with --var (override)
+c8ctl feel evaluate 'a + b' --vars '{"a": 1, "b": 2}' --var b=99
+# → 100
+
+# Or load --vars from a file
+c8ctl feel evaluate 'sum(items)' --vars "$(cat payload.json)"
+```
+
+### Conflict detection
+
+You can't nest a property under a value that's already a
+non-object — the CLI fails with the offending path:
+
+```
+$ c8ctl feel evaluate 'foo.bar' --var foo=hello --var foo.bar=nested
+✗ Failed to feel evaluate: Cannot set --var foo.bar: 'foo' is of type string; cannot nest a property under it.
+```
+
+The reverse direction (a `--var` overwriting an existing object
+with a scalar) is allowed — last write wins.
+
+## See also
+
+- [Camunda FEEL docs](https://docs.camunda.io/docs/components/modeler/feel/what-is-feel/)
+- [Built-in FEEL functions](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-introduction/)
+- [Evaluate Expression API reference](https://docs.camunda.io/docs/apis-tools/orchestration-cluster-api-rest/specifications/evaluate-expression/)