@camunda8/cli 2.8.0-alpha.9 → 3.0.0

package/dist/default-plugins/element-template/commands/apply.js

@@ -0,0 +1,298 @@
+/**
+ * `c8ctl element-template apply` — apply an element template to a BPMN
+ * element via the prebuilt bpmn-js + bpmn-js-element-templates vendor bundle.
+ */
+import { existsSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { applySetOverrides, findPropertiesByBindingName, parseArgs, parseSetArg, warnUnmetConditions, } from "../helpers.js";
+import { elementExistsInBpmn, getExecutionPlatformVersion, parseTemplateRef, readBpmnInput, readTemplateFromPathOrUrl, resolveOotbTemplate, } from "../template-ref.js";
+if (!globalThis.c8ctl)
+    throw new Error("c8ctl runtime not initialised");
+const c8ctl = globalThis.c8ctl;
+const require = createRequire(import.meta.url);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Locate the prebuilt vendor bundle. Plugins live in two places:
+ *   - dev:        default-plugins/element-template/commands/apply.ts
+ *                 vendor: ../../../dist/vendor/bpmn-element-templates.cjs
+ *   - production: dist/default-plugins/element-template/commands/apply.js
+ *                 vendor: ../../../vendor/bpmn-element-templates.cjs
+ */
+function resolveVendorBundle() {
+    const candidates = [
+        resolvePath(__dirname, "..", "..", "..", "dist", "vendor", "bpmn-element-templates.cjs"),
+        resolvePath(__dirname, "..", "..", "..", "vendor", "bpmn-element-templates.cjs"),
+    ];
+    for (const path of candidates) {
+        if (existsSync(path)) {
+            return path;
+        }
+    }
+    throw new Error("Vendor bundle not found. Run `npm run build:vendor` to build it.\n" +
+        `Searched: ${candidates.join(", ")}`);
+}
+/**
+ * Find the first child of `extensionElements` whose moddle `$type` matches.
+ * Avoids importing bpmn-js's `is()` helper just for one shape check.
+ */
+function findExtensionByType(extensionElements, type) {
+    if (!extensionElements) {
+        return undefined;
+    }
+    // biome-ignore lint/plugin: moddle API contract boundary — get() returns untyped collections
+    const values = extensionElements.get("values");
+    return values?.find((v) => v.$type === type);
+}
+/**
+ * Force the source/value of each `--set` into the corresponding moddle child.
+ *
+ * bpmn-js-element-templates' applyTemplate preserves existing input/output/
+ * header/property values on a re-apply (and unconditionally on Dropdown
+ * properties — see ChangeElementTemplateHandler#shouldKeepValue, ref
+ * bpmn-io/bpmn-js-properties-panel#767). For a CLI the user expectation is
+ * "--set wins". After the first applyTemplate we walk the --set args, locate
+ * the moddle entry that backs each binding, and update its value via
+ * `modeling.updateModdleProperties` so the change goes through the same
+ * command stack the library uses internally.
+ *
+ * Bindings whose moddle entry doesn't exist yet (because their condition was
+ * not met against the pre-apply element state) are skipped here and picked
+ * up by the second applyTemplate, which re-evaluates conditions against the
+ * now-updated element and creates the missing entries using our mutated
+ * `prop.value` as the default.
+ */
+function forceSetValues(modeler, element, template, setArgs) {
+    const modeling = modeler.get("modeling");
+    // biome-ignore lint/plugin: moddle API contract boundary — get() returns untyped ModdleElement
+    const extensionElements = element.businessObject.get("extensionElements");
+    if (!extensionElements) {
+        return;
+    }
+    const ioMapping = findExtensionByType(extensionElements, "zeebe:IoMapping");
+    const taskHeaders = findExtensionByType(extensionElements, "zeebe:TaskHeaders");
+    const taskDefinition = findExtensionByType(extensionElements, "zeebe:TaskDefinition");
+    const zeebeProperties = findExtensionByType(extensionElements, "zeebe:Properties");
+    for (const arg of setArgs) {
+        const { bindingTypeFilter, name, value } = parseSetArg(arg);
+        const matches = findPropertiesByBindingName(template.properties, name, bindingTypeFilter);
+        for (const prop of matches) {
+            updateModdleForProperty(modeling, element, prop, value, {
+                ioMapping,
+                taskHeaders,
+                taskDefinition,
+                zeebeProperties,
+            });
+        }
+    }
+}
+function updateModdleForProperty(modeling, element, prop, value, containers) {
+    const binding = prop.binding;
+    if (!binding) {
+        return;
+    }
+    switch (binding.type) {
+        case "zeebe:input": {
+            // biome-ignore lint/plugin: moddle API contract boundary — get() returns untyped collections
+            const inputs = (containers.ioMapping?.get("inputParameters") ??
+                []);
+            const child = inputs.find((p) => p.target === binding.name);
+            if (child) {
+                modeling.updateModdleProperties(element, child, { source: value });
+            }
+            return;
+        }
+        case "zeebe:output": {
+            // biome-ignore lint/plugin: moddle API contract boundary — get() returns untyped collections
+            const outputs = (containers.ioMapping?.get("outputParameters") ??
+                []);
+            const child = outputs.find((p) => p.source === binding.source);
+            if (child) {
+                modeling.updateModdleProperties(element, child, { target: value });
+            }
+            return;
+        }
+        case "zeebe:taskHeader": {
+            // biome-ignore lint/plugin: moddle API contract boundary — get() returns untyped collections
+            const headers = (containers.taskHeaders?.get("values") ??
+                []);
+            const child = headers.find((h) => h.key === binding.key);
+            if (child) {
+                modeling.updateModdleProperties(element, child, { value });
+            }
+            return;
+        }
+        case "zeebe:property": {
+            // biome-ignore lint/plugin: moddle API contract boundary — get() returns untyped collections
+            const props = (containers.zeebeProperties?.get("properties") ??
+                []);
+            const child = props.find((p) => p.name === binding.name);
+            if (child) {
+                modeling.updateModdleProperties(element, child, { value });
+            }
+            return;
+        }
+        case "zeebe:taskDefinition": {
+            if (containers.taskDefinition && binding.property) {
+                modeling.updateModdleProperties(element, containers.taskDefinition, {
+                    [binding.property]: value,
+                });
+            }
+            return;
+        }
+    }
+}
+/**
+ * Apply an element template to a BPMN element using bpmn-js-headless and
+ * bpmn-js-element-templates (same libraries as Web/Desktop Modeler).
+ *
+ * Loaded from a prebuilt CJS vendor bundle since the upstream libraries
+ * use extensionless ESM imports that Node.js can't resolve without a bundler.
+ *
+ * Pass `setArgs` to honor `--set` overrides on re-apply. The first
+ * applyTemplate uses the (already-mutated) template defaults for fresh
+ * properties; `forceSetValues` then overrides preserved values; a second
+ * applyTemplate picks up dependents whose conditions just became met.
+ */
+async function applyElementTemplate(xml, template, elementId, setArgs) {
+    const vendorPath = resolveVendorBundle();
+    const vendor = require(vendorPath);
+    const { Modeler, CloudElementTemplatesCoreModule, ZeebeModdleExtension, HeadlessTextRendererModule, } = vendor;
+    // HeadlessTextRendererModule overrides bpmn-js's default textRenderer,
+    // which would otherwise call document.createElementNS during importXML
+    // (to measure external label bounds) and throw "document is not defined"
+    // in Node. The errors are non-fatal but produce noisy stack traces.
+    const modeler = new Modeler({
+        additionalModules: [
+            HeadlessTextRendererModule,
+            CloudElementTemplatesCoreModule,
+        ],
+        moddleExtensions: { zeebe: ZeebeModdleExtension },
+    });
+    await modeler.importXML(xml);
+    const elementRegistry = modeler.get("elementRegistry");
+    const element = elementRegistry.get(elementId);
+    if (!element) {
+        throw new Error(`Element "${elementId}" not found in the BPMN diagram`);
+    }
+    const elementTemplates = modeler.get("elementTemplates");
+    elementTemplates.set([template]);
+    elementTemplates.applyTemplate(element, template);
+    if (setArgs.length > 0) {
+        forceSetValues(modeler, element, template, setArgs);
+        // Second pass so dependents whose conditions are newly met get
+        // created with our mutated defaults.
+        elementTemplates.applyTemplate(element, template);
+    }
+    const result = await modeler.saveXML({ format: true });
+    return result.xml;
+}
+export async function applySubcommand(args) {
+    const logger = c8ctl.getLogger();
+    const parsed = parseArgs(args);
+    if (parsed.error) {
+        throw new Error(parsed.error);
+    }
+    const [templateArg, elementId, bpmnFilePath] = parsed.positionals;
+    if (parsed.positionals.length > 3) {
+        throw new Error(`Unexpected argument: ${parsed.positionals[3]}. Usage: c8ctl element-template apply <template> <element-id> [<file.bpmn>]`);
+    }
+    if (!templateArg) {
+        throw new Error("Missing template argument. Usage: c8ctl element-template apply <template> <element-id> [<file.bpmn>]");
+    }
+    if (!elementId) {
+        throw new Error("Missing element-id argument. Usage: c8ctl element-template apply <template> <element-id> [<file.bpmn>]");
+    }
+    // Reject incompatible flag combinations before reading stdin —
+    // otherwise a piped BPMN stream is consumed (and a long-running
+    // producer can hang) just to surface a usage error.
+    if (parsed.inPlace && !bpmnFilePath) {
+        throw new Error("--in-place cannot be used with stdin input");
+    }
+    const input = await readBpmnInput(bpmnFilePath);
+    if (!input) {
+        throw new Error("No BPMN input provided. Pass a file path or pipe BPMN XML via stdin.");
+    }
+    const ref = parseTemplateRef(templateArg);
+    if (!ref) {
+        throw new Error("Missing template argument.");
+    }
+    let template;
+    if (ref.kind === "id") {
+        const executionPlatformVersion = await getExecutionPlatformVersion(input.xml);
+        template = await resolveOotbTemplate(ref, { executionPlatformVersion });
+        if (ref.version === undefined && !executionPlatformVersion) {
+            logger.warn("BPMN has no modeler:executionPlatformVersion — applying latest version " +
+                `(${template.version}) of ${ref.id}.`);
+        }
+    }
+    else {
+        template = await readTemplateFromPathOrUrl(ref.value);
+    }
+    // Validate --set overrides against the template before dry-run or real apply,
+    // so `--dry-run --set notAProperty=x` fails just as the real apply would.
+    let setProperties = [];
+    if (parsed.setArgs.length > 0) {
+        setProperties = applySetOverrides(template.properties, parsed.setArgs);
+    }
+    // Dry-run: describe what would happen without mutating anything
+    if (c8ctl.dryRun) {
+        // Validate the target element exists so dry-run only reports a successful
+        // plan when the real apply would also succeed.
+        if (!(await elementExistsInBpmn(input.xml, elementId))) {
+            throw new Error(`Element "${elementId}" not found in the BPMN diagram`);
+        }
+        const fallbackId = ref.kind === "id" ? ref.id : ref.value;
+        const info = {
+            dryRun: true,
+            command: "element-template apply",
+            template: {
+                id: template.id ?? fallbackId,
+                name: template.name,
+                version: template.version,
+            },
+            elementId,
+            source: input.source,
+            inPlace: parsed.inPlace && !!bpmnFilePath,
+            setOverrides: parsed.setArgs,
+        };
+        if (c8ctl.outputMode === "json") {
+            logger.json(info);
+        }
+        else {
+            logger.output("Dry run — no changes applied.");
+            logger.output(`  Template: ${info.template.name ?? info.template.id}${info.template.version != null ? ` v${info.template.version}` : ""}`);
+            logger.output(`  Element:  ${elementId}`);
+            logger.output(`  Source:   ${input.source}`);
+            if (info.inPlace) {
+                logger.output(`  Mode:     in-place (would overwrite ${bpmnFilePath})`);
+            }
+            else {
+                logger.output("  Mode:     stdout (would print transformed XML)");
+            }
+            if (parsed.setArgs.length > 0) {
+                logger.output(`  --set:    ${parsed.setArgs.join(", ")}`);
+            }
+        }
+        return;
+    }
+    let resultXml;
+    try {
+        resultXml = await applyElementTemplate(input.xml, template, elementId, parsed.setArgs);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Error applying template: ${message}`);
+    }
+    if (setProperties.length > 0) {
+        warnUnmetConditions(logger, resultXml, setProperties);
+    }
+    if (parsed.inPlace && bpmnFilePath) {
+        writeFileSync(resolvePath(bpmnFilePath), resultXml, "utf-8");
+        logger.info(`Updated ${bpmnFilePath}`);
+        return;
+    }
+    process.stdout.write(resultXml);
+}
+//# sourceMappingURL=apply.js.map

package/dist/default-plugins/element-template/commands/apply.js.map

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

package/dist/default-plugins/element-template/commands/get-properties.js

@@ -0,0 +1,344 @@
+/**
+ * `c8ctl element-template get-properties` — list settable properties of a
+ * template. Default render is a condensed table of name + description
+ * rows grouped by section. `--detailed` swaps in per-property detail cards.
+ */
+import { styleText } from "node:util";
+import { BINDING_TYPE_SHORTHANDS, globToRegex, } from "../helpers.js";
+import { loadTemplate } from "../template-ref.js";
+import { formatKeyedCard, parseInspectArgs } from "./info.js";
+if (!globalThis.c8ctl)
+    throw new Error("c8ctl runtime not initialised");
+const c8ctl = globalThis.c8ctl;
+export async function getPropertiesSubcommand(args) {
+    const logger = c8ctl.getLogger();
+    const usage = "Usage: c8ctl element-template get-properties <template> [<name>...] [--group <id>...] [--detailed | -d]\n" +
+        "  Default: condensed list (name + description). --detailed shows full cards.\n" +
+        "  Names may include shell-style globs — quote to avoid shell expansion: 'auth*'";
+    const parsed = parseInspectArgs(args, usage, {
+        allowPropertyNames: true,
+        allowFilters: true,
+    });
+    const { template, allDetails, groupLabelMap, sourceByDetail, autoResolvedVersion, } = await loadTemplate(parsed.templateArg);
+    if (autoResolvedVersion) {
+        logger.warn(`Resolved latest version (${template.version}) of ${template.id}. ` +
+            `Use '${template.id}@${template.version}' to pin.`);
+    }
+    // Resolve positional names if any (literals or globs). Each arg must
+    // match at least one property — typos shouldn't silently produce no
+    // output. With no positionals, default to all properties.
+    let details = parsed.propertyArgs.length > 0
+        ? parsed.propertyArgs.flatMap((arg) => filterByPropertyArg(allDetails, arg, parsed.templateArg))
+        : allDetails;
+    // --group intersects with positional matches. Validation of the
+    // requested group ids uses the full template (allDetails) so a
+    // valid group id on a property the name filter excluded still
+    // counts as known — the user should see "no match" for the
+    // combination, not "unknown group id".
+    details = applyGroupFilter(details, allDetails, parsed.groups, groupLabelMap);
+    // Dedupe by object reference — the same property detail object is
+    // returned when it matches multiple positionals (e.g. `url` and
+    // `u*` together). NOT by binding name+type: distinct properties
+    // sometimes share those (operation-conditional duplicates that
+    // bind to the same field with different `condition` clauses).
+    const seen = new Set();
+    details = details.filter((d) => {
+        if (seen.has(d)) {
+            return false;
+        }
+        seen.add(d);
+        return true;
+    });
+    // Each filter is individually validated (positional names via
+    // filterByPropertyArg, group ids via applyGroupFilter), but their
+    // intersection can still be empty when a property exists somewhere
+    // and a group exists, just not together. Surface that as an error
+    // to match the README contract that filters error on no-match.
+    if (details.length === 0 &&
+        (parsed.propertyArgs.length > 0 || parsed.groups.length > 0)) {
+        const nameClause = parsed.propertyArgs.length > 0
+            ? `name${parsed.propertyArgs.length > 1 ? "s" : ""} ${parsed.propertyArgs.map((a) => `"${a}"`).join(", ")}`
+            : "";
+        const groupClause = parsed.groups.length > 0
+            ? `group${parsed.groups.length > 1 ? "s" : ""} ${parsed.groups.map((g) => `"${g}"`).join(", ")}`
+            : "";
+        const what = [nameClause, groupClause].filter(Boolean).join(" and ");
+        throw new Error(`No properties match ${what}.`);
+    }
+    const total = allDetails.length;
+    if (c8ctl.outputMode === "json") {
+        const projector = parsed.detailed
+            ? buildShowProperty
+            : buildCondensedProperty;
+        logger.json(buildJsonPayload(template, details, projector, total, sourceByDetail));
+        return;
+    }
+    // Summary line at the top — gives an at-a-glance answer to "how
+    // many am I seeing, out of how many available". Especially useful
+    // after a filter to confirm scope.
+    logger.output(styleText("dim", `Showing ${details.length} of ${total} properties.`));
+    logger.output("");
+    if (parsed.detailed) {
+        // Detail-card view — full per-property fields.
+        for (let i = 0; i < details.length; i++) {
+            for (const line of formatPropertyCard(details[i])) {
+                logger.output(line);
+            }
+            if (i < details.length - 1) {
+                logger.output("");
+            }
+        }
+        return;
+    }
+    // Default: condensed list — group heading + name + description.
+    renderCondensedTable(details, groupLabelMap, logger);
+    // Trailing hint — point users at name filtering and --detailed.
+    logger.output("");
+    logger.output(styleText("dim", "Filter by name (supports globs):\n" +
+        `  c8ctl element-template get-properties ${parsed.templateArg} 'auth*' url\n` +
+        "For full details on each property:\n" +
+        `  c8ctl element-template get-properties ${parsed.templateArg} --detailed`));
+}
+/**
+ * Project a property into the JSON shape that mirrors the **condensed
+ * get-properties text output** — just identification (binding) and the
+ * descriptive text the row surfaces. Group is included so consumers
+ * can resolve the section heading via the top-level `groups` table.
+ */
+function buildCondensedProperty(prop) {
+    return {
+        id: prop.id,
+        binding: prop.binding,
+        label: prop.label,
+        description: prop.description,
+        group: prop.group,
+        choices: prop.choices,
+    };
+}
+/**
+ * Project a property into the JSON shape that mirrors the
+ * **--detailed get-properties card** — every field the card surfaces.
+ * Schema field names verbatim.
+ */
+function buildShowProperty(prop) {
+    return {
+        id: prop.id,
+        binding: prop.binding,
+        type: prop.type,
+        optional: prop.optional,
+        value: prop.value,
+        feel: prop.feel,
+        group: prop.group,
+        condition: prop.condition,
+        label: prop.label,
+        description: prop.description,
+        constraints: prop.constraints,
+        choices: prop.choices,
+    };
+}
+/**
+ * JSON payload for `get-properties`. `projectProp` decides which
+ * per-property shape to use (condensed vs detailed) so JSON mirrors
+ * text density per mode.
+ */
+function buildJsonPayload(template, details, projectProp, totalCount, sourceByDetail) {
+    const properties = details
+        .map((d) => sourceByDetail.get(d))
+        .filter((p) => Boolean(p))
+        .map(projectProp);
+    return {
+        count: properties.length,
+        total: totalCount,
+        groups: template.groups ?? [],
+        properties,
+    };
+}
+/**
+ * Filter `details` to those whose `groupId` is in the requested list.
+ * Empty list means no filter. Unknown group ids throw with the list of
+ * valid ids — group ids are short and bounded so we always show them.
+ *
+ * `allDetails` is the unfiltered property set from the template; we
+ * use it to compute the valid-group set so that a group id which only
+ * appears on a property excluded by an earlier name filter still counts
+ * as known. Without this, combining a valid name filter and a valid
+ * group id from a template with no `groups` table would surface
+ * "Unknown group id" rather than the intended empty-intersection error.
+ */
+function applyGroupFilter(details, allDetails, groups, groupLabelMap) {
+    if (groups.length === 0) {
+        return details;
+    }
+    // Valid group IDs: the template's declared groups table PLUS any group id
+    // referenced directly on any property in the template (templates that use
+    // property.group without a matching groups entry still render a heading —
+    // so the filter must accept those ids too).
+    const validFromTemplate = new Set(groupLabelMap.keys());
+    const validFromDetails = new Set(allDetails
+        .map((d) => d.groupId)
+        .filter((id) => id !== undefined));
+    const valid = new Set([...validFromTemplate, ...validFromDetails]);
+    for (const g of groups) {
+        if (!valid.has(g)) {
+            const known = [...valid].join(", ") || "(none defined on this template)";
+            throw new Error(`Unknown group id "${g}". Use the template's group id (not its label).\n` +
+                `Available group ids: ${known}`);
+        }
+    }
+    const set = new Set(groups);
+    return details.filter((d) => d.groupId !== undefined && set.has(d.groupId));
+}
+/**
+ * Render the condensed one-line-per-property listing grouped by
+ * section.
+ */
+function renderCondensedTable(details, groupLabelMap, logger) {
+    const grouped = new Map();
+    const ungrouped = [];
+    for (const detail of details) {
+        if (detail.groupId) {
+            const list = grouped.get(detail.groupId) ?? [];
+            list.push(detail);
+            grouped.set(detail.groupId, list);
+        }
+        else {
+            ungrouped.push(detail);
+        }
+    }
+    // Global name-column width so the description column anchors at the
+    // same x-position across all groups.
+    const nameWidth = Math.max(0, ...details.map((d) => (d.name ?? "?").length));
+    const groupEntries = [...grouped.entries()].map(([groupId, group]) => ({ groupId, group }));
+    if (ungrouped.length > 0) {
+        groupEntries.push({ groupId: null, group: ungrouped });
+    }
+    for (let i = 0; i < groupEntries.length; i++) {
+        const { groupId, group } = groupEntries[i];
+        const label = groupId ? (groupLabelMap.get(groupId) ?? groupId) : "Other";
+        // Show "Label (id)" so the --group filter token is self-documenting.
+        // Skip the parenthetical when label and id are identical.
+        const heading = groupId && label !== groupId
+            ? `${styleText("bold", label)} ${styleText("dim", `(${groupId})`)}`
+            : styleText("bold", label);
+        logger.output(heading);
+        for (const detail of group) {
+            logger.output(formatCondensedRow(detail, { nameWidth }));
+        }
+        if (i < groupEntries.length - 1) {
+            logger.output("");
+        }
+    }
+}
+/**
+ * Build one condensed row: indent · padded name · description-or-label.
+ */
+function formatCondensedRow(detail, { nameWidth }) {
+    const NAME_INDENT = "  ";
+    const COLUMN_GAP = "  ";
+    const CONT_INDENT = " ".repeat(NAME_INDENT.length + 4);
+    const name = (detail.name ?? "?").padEnd(nameWidth);
+    const text = detail.description ?? detail.label ?? "";
+    const trailing = text ? `${COLUMN_GAP}${styleText("dim", text)}` : "";
+    const lines = [`${NAME_INDENT}${styleText("bold", name)}${trailing}`];
+    // Surface `id` only when it adds information — i.e. it exists and
+    // differs from the binding name. For most properties (id == name or
+    // id missing) this stays a single-line row.
+    if (detail.id && detail.id !== detail.name) {
+        lines.push(styleText("dim", `${CONT_INDENT}[id: ${detail.id}]`));
+    }
+    if (detail.choices?.length) {
+        const values = detail.choices.map((c) => c.value).join(", ");
+        lines.push(styleText("dim", `${CONT_INDENT}[choices: ${values}]`));
+    }
+    return lines.join("\n");
+}
+/**
+ * Detail card for a single property — keyed two-column layout.
+ */
+function formatPropertyCard(detail) {
+    const fields = [];
+    if (detail.id) {
+        fields.push(["Id", detail.id]);
+    }
+    fields.push(["Type", detail.type ?? "String"]);
+    fields.push(["Required", detail.required ? "yes" : "no"]);
+    if (detail.feel) {
+        fields.push(["FEEL", detail.feel]);
+    }
+    if (detail.default !== undefined && detail.default !== "") {
+        fields.push(["Default", formatBadgeValue(detail.default)]);
+    }
+    if (detail.bindingType) {
+        fields.push(["Binding", detail.bindingType]);
+    }
+    if (detail.label || detail.description) {
+        const text = [detail.label, detail.description].filter(Boolean).join(" — ");
+        fields.push(["Description", text]);
+    }
+    if (detail.conditionText) {
+        fields.push(["Active when", detail.conditionText]);
+    }
+    else if (detail.condition) {
+        fields.push(["Conditional", "(see template definition)"]);
+    }
+    if (detail.pattern) {
+        fields.push(["Pattern", detail.pattern.value]);
+        if (detail.pattern.message) {
+            fields.push(["", detail.pattern.message]);
+        }
+    }
+    if (detail.choices?.length) {
+        fields.push(["Choices", detail.choices.map((c) => c.value).join(", ")]);
+    }
+    return formatKeyedCard({
+        title: detail.name ?? "?",
+        subtitle: detail.group ? `(${detail.group})` : undefined,
+        fields,
+    });
+}
+/**
+ * Filter properties by a `<name>` or `<binding-type>:<name>` argument.
+ */
+function filterByPropertyArg(details, propertyArg, templateArg) {
+    const colon = propertyArg.indexOf(":");
+    let nameFilter = propertyArg;
+    let typeFilter;
+    if (colon !== -1) {
+        const prefix = propertyArg.slice(0, colon);
+        typeFilter = BINDING_TYPE_SHORTHANDS[prefix];
+        if (!typeFilter) {
+            const valid = Object.keys(BINDING_TYPE_SHORTHANDS).join(", ");
+            throw new Error(`Unknown binding type prefix "${prefix}". Valid prefixes: ${valid}`);
+        }
+        nameFilter = propertyArg.slice(colon + 1);
+    }
+    const isGlob = nameFilter.includes("*");
+    const matcher = isGlob ? globToRegex(nameFilter) : null;
+    const matches = details.filter((d) => {
+        if (typeFilter && d.bindingType !== typeFilter) {
+            return false;
+        }
+        if (!d.name) {
+            return false;
+        }
+        return matcher ? matcher.test(d.name) : d.name === nameFilter;
+    });
+    if (matches.length === 0) {
+        const hint = templateArg
+            ? `\nRun 'c8ctl element-template get-properties ${templateArg}' to list all available properties.`
+            : "";
+        throw new Error(`Property "${propertyArg}" not found.${hint}`);
+    }
+    return matches;
+}
+function formatBadgeValue(value) {
+    if (typeof value === "string") {
+        // Multi-line defaults (FEEL expression bodies, JSON snippets) would
+        // otherwise wrap and break the badge layout — collapse to a single
+        // line and truncate.
+        const oneLine = value.replace(/\s+/g, " ").trim();
+        return oneLine.length > 60 ? `${oneLine.slice(0, 57)}...` : oneLine;
+    }
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=get-properties.js.map