@camunda8/cli 2.8.0-alpha.8 → 3.0.0-alpha.1

package/dist/default-plugins/bpmn/c8ctl-plugin.js

@@ -0,0 +1,125 @@
+/**
+ * c8ctl-plugin-bpmn
+ *
+ * Lint BPMN diagrams against recommended and Camunda rules.
+ *
+ * Usage:
+ *   c8ctl bpmn lint <file.bpmn>
+ *   cat file.bpmn | c8ctl bpmn lint
+ */
+import { lintSubcommand } from "./lint.js";
+if (!globalThis.c8ctl)
+    throw new Error("c8ctl runtime not initialised");
+const c8ctl = globalThis.c8ctl;
+// Ambient module declarations for the untyped bpmn-io ecosystem live in
+// ./bpmn-io.d.ts (TS does not allow `declare module` inside module files
+// for modules that resolve to actual files).
+/**
+ * Reinject flags pre-parsed by the host (#366/#367) back into the args
+ * array as `--name value` / `--name` tokens, so the plugin's hand-rolled
+ * `parseArgs` still sees them.
+ */
+function injectFlagsIntoArgs(args, flags) {
+    const out = [...args];
+    if (!flags) {
+        return out;
+    }
+    for (const [name, value] of Object.entries(flags)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (typeof value === "boolean") {
+            if (value) {
+                out.push(`--${name}`);
+            }
+        }
+        else if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item !== undefined && item !== null) {
+                    out.push(`--${name}`, String(item));
+                }
+            }
+        }
+        else {
+            out.push(`--${name}`, String(value));
+        }
+    }
+    return out;
+}
+async function bpmnHandler(args, flags) {
+    const reinjected = injectFlagsIntoArgs(args ?? [], flags);
+    const subcommand = reinjected[0];
+    const subArgs = reinjected.slice(1);
+    const validSubcommands = metadata.commands.bpmn.subcommands.map((s) => s.name);
+    if (!subcommand || !validSubcommands.includes(subcommand)) {
+        const logger = c8ctl.getLogger();
+        const lead = subcommand
+            ? `Unknown subcommand '${subcommand}'.`
+            : "c8ctl bpmn requires a subcommand.";
+        logger.info(`${lead} Available: ${validSubcommands.join(", ")}`);
+        logger.info("Run 'c8ctl bpmn --help' for full usage.");
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        if (subcommand === "lint")
+            await lintSubcommand(subArgs);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const logger = c8ctl.getLogger();
+        logger.error(`Failed to bpmn ${subcommand}: ${message}`);
+        process.exitCode = 1;
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin API
+// ---------------------------------------------------------------------------
+export const metadata = {
+    name: "bpmn",
+    description: "Lint BPMN diagrams",
+    commands: {
+        bpmn: {
+            description: "BPMN tooling — lint diagrams (supports stdin piping)",
+            helpDescription: "Lint BPMN diagrams. Supports file paths and stdin piping.\n\n" +
+                "Rule configuration: a .bpmnlintrc in the working directory takes precedence. " +
+                "Otherwise the linter extends bpmnlint:recommended plus the matching " +
+                "camunda-compat/camunda-cloud-<version> ruleset, auto-detected from " +
+                'modeler:executionPlatform="Camunda Cloud" and ' +
+                "modeler:executionPlatformVersion in the BPMN file.",
+            subcommands: [
+                {
+                    name: "lint",
+                    description: "Lint a BPMN diagram against recommended and Camunda rules",
+                },
+            ],
+            examples: [
+                {
+                    command: "c8ctl bpmn lint process.bpmn",
+                    description: "Lint a BPMN file with Camunda rules",
+                },
+                {
+                    command: "cat process.bpmn | c8ctl bpmn lint",
+                    description: "Lint from stdin",
+                },
+                {
+                    command: "c8ctl bpmn lint --quiet process.bpmn",
+                    description: "Suppress the success line in scripts",
+                },
+            ],
+        },
+    },
+};
+export const commands = {
+    bpmn: {
+        flags: {
+            quiet: {
+                type: "boolean",
+                short: "q",
+                description: 'Suppress the "No issues found." line on a clean lint',
+            },
+        },
+        handler: bpmnHandler,
+    },
+};
+//# sourceMappingURL=c8ctl-plugin.js.map

package/dist/default-plugins/bpmn/c8ctl-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"c8ctl-plugin.js","sourceRoot":"","sources":["../../../default-plugins/bpmn/c8ctl-plugin.ts"],"names":[],"mappings":"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"}

package/dist/default-plugins/bpmn/lint.js

@@ -0,0 +1,259 @@
+/**
+ * BPMN lint internals — bpmnlint driver, config resolution, and the
+ * collect-then-render split that powers `c8ctl bpmn lint`. The plugin
+ * file (./c8ctl-plugin.ts) only handles host glue and CLI dispatch.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolve as resolvePath } from "node:path";
+import { styleText } from "node:util";
+if (!globalThis.c8ctl)
+    throw new Error("c8ctl runtime not initialised");
+const c8ctl = globalThis.c8ctl;
+const require = createRequire(import.meta.url);
+function isRecord(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Read BPMN XML from a file path or stdin. Returns null if no input is available.
+ *
+ * Stdin is consumed via async iteration so a slow upstream writer (e.g.
+ * `apply | lint` in a pipeline, or any producer that hasn't flushed yet)
+ * is awaited until 'end'. Do not use `readFileSync(0)` here — when stdin
+ * is a pipe with no buffered data yet, it throws EAGAIN, which gets
+ * swallowed and surfaces as "no input".
+ */
+async function readBpmnInput(filePath) {
+    if (filePath) {
+        const resolved = resolvePath(filePath);
+        if (!existsSync(resolved)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        return { xml: readFileSync(resolved, "utf-8"), source: resolved };
+    }
+    if (!process.stdin.isTTY) {
+        process.stdin.setEncoding("utf-8");
+        let xml = "";
+        for await (const chunk of process.stdin) {
+            xml += chunk;
+        }
+        if (!xml.trim())
+            return null;
+        return { xml, source: "stdin" };
+    }
+    return null;
+}
+function detectCamundaCloudVersion(rootElement) {
+    const attrs = rootElement.$attrs ?? {};
+    const platform = attrs["modeler:executionPlatform"];
+    const version = attrs["modeler:executionPlatformVersion"];
+    if (platform !== "Camunda Cloud" || !version) {
+        return null;
+    }
+    const match = version.match(/^(\d+\.\d+)/);
+    return match ? match[1] : null;
+}
+function resolveCamundaCompatConfig(version) {
+    const plugin = require("bpmnlint-plugin-camunda-compat");
+    const configs = plugin.configs;
+    const configName = `camunda-cloud-${version.replace(".", "-")}`;
+    if (configName in configs) {
+        return `plugin:camunda-compat/${configName}`;
+    }
+    const cloudConfigs = Object.keys(configs)
+        .filter((k) => k.startsWith("camunda-cloud-"))
+        .sort((a, b) => {
+        const parse = (s) => s.replace("camunda-cloud-", "").split("-").map(Number);
+        const va = parse(a);
+        const vb = parse(b);
+        for (let i = 0; i < Math.max(va.length, vb.length); i++) {
+            const diff = (va[i] || 0) - (vb[i] || 0);
+            if (diff !== 0) {
+                return diff;
+            }
+        }
+        return 0;
+    });
+    if (cloudConfigs.length > 0) {
+        return `plugin:camunda-compat/${cloudConfigs[cloudConfigs.length - 1]}`;
+    }
+    return null;
+}
+function buildLintConfig(rootElement) {
+    const rcPath = resolvePath(".bpmnlintrc");
+    if (existsSync(rcPath)) {
+        const parsed = JSON.parse(readFileSync(rcPath, "utf-8"));
+        if (!isRecord(parsed)) {
+            throw new Error(".bpmnlintrc must contain a JSON object");
+        }
+        return parsed;
+    }
+    const config = { extends: ["bpmnlint:recommended"] };
+    const version = detectCamundaCloudVersion(rootElement);
+    if (version) {
+        const compatConfig = resolveCamundaCompatConfig(version);
+        if (compatConfig)
+            config.extends.push(compatConfig);
+    }
+    return config;
+}
+function formatElementRef(report, pathStringify) {
+    const id = report.id ?? "";
+    if (report.path) {
+        return `${id}#${pathStringify(report.path)}`;
+    }
+    return id;
+}
+/**
+ * Flatten bpmnlint's `{ ruleName: [report, ...] }` shape into a typed
+ * issue list plus the parallel `rows` list that the text renderer
+ * formats into a column-aligned table.
+ */
+function collectLintResult(results) {
+    let errorCount = 0;
+    let warningCount = 0;
+    const issues = [];
+    const rows = [];
+    const { pathStringify } = require("@bpmn-io/moddle-utils");
+    for (const [ruleName, reports] of Object.entries(results)) {
+        for (const report of reports) {
+            const elementRef = formatElementRef(report, pathStringify);
+            const displayName = report.name ?? ruleName;
+            const severity = report.category === "error" ? "error" : "warning";
+            rows.push({
+                elementRef,
+                severity,
+                message: report.message,
+                displayName,
+                category: report.category,
+            });
+            const issue = {
+                rule: report.name ?? ruleName,
+                elementId: report.id || null,
+                message: report.message,
+                category: report.category === "warn" ? "warning" : report.category,
+            };
+            if (report.path) {
+                issue.path = report.path;
+            }
+            issues.push(issue);
+            if (report.category === "error")
+                errorCount++;
+            else
+                warningCount++;
+        }
+    }
+    return { rows, issues, errorCount, warningCount };
+}
+function renderLintJson(logger, file, result) {
+    logger.json({
+        file,
+        issues: result.issues,
+        errorCount: result.errorCount,
+        warningCount: result.warningCount,
+    });
+}
+function renderLintText(logger, source, result, options) {
+    const { rows, errorCount, warningCount } = result;
+    const problemCount = errorCount + warningCount;
+    if (problemCount === 0) {
+        if (!options.quiet) {
+            // Mirror the bold red ✖ summary used for problems with a bold green
+            // ✓ on success — gives the user an unambiguous "lint ran cleanly"
+            // signal instead of trailing silence.
+            logger.output(styleText(["bold", "green"], "✓ No issues found."));
+        }
+        return;
+    }
+    // Compute column widths from the uncolored values so padding lines up
+    // regardless of terminal color support.
+    const widths = rows.reduce((acc, r) => ({
+        elementRef: Math.max(acc.elementRef, r.elementRef.length),
+        severity: Math.max(acc.severity, r.severity.length),
+        message: Math.max(acc.message, r.message.length),
+    }), { elementRef: 0, severity: 0, message: 0 });
+    const padEnd = (s, n) => s + " ".repeat(Math.max(0, n - s.length));
+    const sourceLabel = source === "stdin" ? "stdin" : resolvePath(source);
+    logger.output("");
+    logger.output(styleText("underline", sourceLabel));
+    for (const r of rows) {
+        const severityColor = r.category === "error" ? "red" : "yellow";
+        const severityCell = styleText(severityColor, padEnd(r.severity, widths.severity));
+        logger.output([
+            " ",
+            padEnd(r.elementRef, widths.elementRef),
+            severityCell,
+            padEnd(r.message, widths.message),
+            r.displayName,
+        ].join("  "));
+    }
+    const pluralize = (word, count) => count === 1 ? word : `${word}s`;
+    const summary = `✖ ${problemCount} ${pluralize("problem", problemCount)} ` +
+        `(${errorCount} ${pluralize("error", errorCount)}, ` +
+        `${warningCount} ${pluralize("warning", warningCount)})`;
+    const summaryColor = errorCount > 0 ? ["bold", "red"] : ["bold", "yellow"];
+    logger.output("");
+    logger.output(styleText(summaryColor, summary));
+}
+export async function lintSubcommand(args) {
+    const logger = c8ctl.getLogger();
+    const usage = "Usage: c8ctl bpmn lint [<file.bpmn>] [--quiet | -q]";
+    const endOfOpts = args.indexOf("--");
+    const optionArgs = endOfOpts === -1 ? args : args.slice(0, endOfOpts);
+    const positionalArgs = endOfOpts === -1 ? [] : args.slice(endOfOpts + 1);
+    const quiet = optionArgs.includes("--quiet") || optionArgs.includes("-q");
+    const unknownFlag = optionArgs.find((a) => a.startsWith("-") && a !== "--quiet" && a !== "-q");
+    if (unknownFlag) {
+        throw new Error(`Unknown flag: ${unknownFlag}. ${usage}`);
+    }
+    const filePath = positionalArgs[0] ?? optionArgs.find((a) => !a.startsWith("-"));
+    // Reject extra positional args (only one BPMN file is accepted).
+    const allPositionals = [
+        ...positionalArgs,
+        ...optionArgs.filter((a) => !a.startsWith("-")),
+    ];
+    if (allPositionals.length > 1) {
+        throw new Error(`Unexpected argument: ${allPositionals[1]}. ${usage}`);
+    }
+    const input = await readBpmnInput(filePath);
+    if (!input) {
+        throw new Error("No BPMN input provided. Pass a file path or pipe BPMN XML via stdin.");
+    }
+    const BpmnModdle = (await import("bpmn-moddle")).default;
+    const zeebeSchema = (await import("zeebe-bpmn-moddle/resources/zeebe.json", {
+        with: { type: "json" },
+    })).default;
+    const moddle = new BpmnModdle({ zeebe: zeebeSchema });
+    let rootElement;
+    try {
+        const result = await moddle.fromXML(input.xml);
+        rootElement = result.rootElement;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse BPMN: ${message}`);
+    }
+    const config = buildLintConfig(rootElement);
+    const { Linter } = require("bpmnlint");
+    const NodeResolver = require("bpmnlint/lib/resolver/node-resolver");
+    // Pass our plugin-scoped `require` to NodeResolver so bpmnlint resolves
+    // `bpmnlint-plugin-camunda-compat` from c8ctl's installation, not the
+    // user's CWD. Without this, `bpmn lint` only works when run from a
+    // directory that happens to have the plugin in its node_modules.
+    const linter = new Linter({
+        config,
+        resolver: new NodeResolver({ require }),
+    });
+    const results = await linter.lint(rootElement);
+    const result = collectLintResult(results);
+    if (c8ctl.outputMode === "json") {
+        renderLintJson(logger, input.source, result);
+    }
+    else {
+        renderLintText(logger, input.source, result, { quiet });
+    }
+    if (result.errorCount > 0) {
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=lint.js.map

package/dist/default-plugins/bpmn/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../../default-plugins/bpmn/lint.ts"],"names":[],"mappings":"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"}

package/dist/default-plugins/bpmn/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "c8ctl-plugin-bpmn",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "c8ctl plugin to lint BPMN diagrams against recommended and Camunda rules",
+  "keywords": ["c8ctl", "c8ctl-plugin", "bpmn", "lint"],
+  "main": "c8ctl-plugin.ts"
+}

package/dist/default-plugins/cluster/package.json

@@ -8,7 +8,7 @@
   "c8ctl": {
     "versionAliases": {
       "stable": "8.9",
-      "alpha": "8.9"
+      "alpha": "8.10"
     }
   }
 }

package/dist/default-plugins/element-template/AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md — `element-template` plugin
+
+Read [docs/design.md](./docs/design.md) before changing this plugin. It
+covers the **why**: vendor bundle, marketplace endpoint choice, cache
+strategy (`upstreamRef`-keyed dedup), lazy bootstrap, and semver-based
+version resolution.
+
+## Where things live
+
+| File | Purpose |
+| --- | --- |
+| `c8ctl-plugin.ts` | Plugin API (metadata + commands export), subcommand dispatch table |
+| `commands/<name>.ts` | One file per subcommand: `apply`, `get`, `get-properties`, `info`, `search`, `sync` |
+| `template-ref.ts` | `parseTemplateRef`, `readBpmnInput`, `getExecutionPlatformVersion`, `resolveOotbTemplate`, `loadTemplate` |
+| `marketplace.ts` | Cache I/O, `/ootb-connectors` fetch, sync, search, version resolution |
+| `helpers.ts` | `--set` parsing, file/URL fetch, glob → regex, multi-binding lookup, condition warnings |
+| `vendor-src/bundle-entry.js` | esbuild entry — re-exports `Modeler`, `CloudElementTemplatesCoreModule`, `ZeebeModdleExtension` |
+
+## Things to know before editing
+
+- **Touching anything bpmn-js related requires `npm run build:vendor`.**
+  The plugin loads `dist/vendor/bpmn-element-templates.cjs`, not the
+  source. `vendor-src/bundle-entry.js` is the only entry point that
+  esbuild bundles.
+- **Cache file shape mirrors Desktop Modeler's
+  `.camunda-connector-templates.json`.** Don't change the format
+  without reason — `metadata.upstreamRef` is the dedup key for
+  incremental sync.
+- **`get` deliberately does NOT auto-bootstrap.** Bootstrap progress
+  goes through `logger.info`, which writes to stdout in text mode —
+  that would corrupt `get <id> > template.json` redirects. Cache miss
+  surfaces as an explicit error pointing at `sync`. Don't add a
+  bootstrap call to `getSubcommand` without changing the logger story
+  first.
+- **Path/URL apply paths must not trigger the index bootstrap.**
+  Detection happens in `parseTemplateRef()` in `template-ref.ts`
+  before any cache call.
+- **JSON output uses element-templates schema field names verbatim.**
+  No invented derivations — `binding`, `optional`, `value`, `condition`,
+  `group` (id), `elementType: { value }`, `engines: { camunda }`. The
+  only c8ctl-internal extension is `metadata.upstreamRef`, which `get`
+  strips before serializing.
+- **Property dedup is by object reference, not by `binding.name|type`.**
+  Template authors sometimes attach two properties with the same binding
+  name + type but different `condition` clauses (operation-conditional
+  duplicates); the engine drops inactive ones at apply time. The
+  WeakMap-based `sourceByDetail` side table in `loadTemplate` preserves
+  this identity so `get-properties` doesn't collapse them and `--set`
+  writes to all matching duplicates.
+- **Marketplace endpoint URL is overridable via
+  `C8CTL_OOTB_ELEMENT_TEMPLATES_URL`** — useful for tests against a
+  local fixture server.
+
+## Testing
+
+```bash
+npm run build:vendor && node --experimental-strip-types --test tests/unit/element-template.test.ts
+```
+
+Smoke-test against the live marketplace (writes to a throwaway dir):
+
+```bash
+C8CTL_DATA_DIR=/tmp/c8ctl-smoke node --experimental-strip-types src/index.ts \
+  element-template search "AWS S3"
+```