@uipath/maestro-builder-sdk 5.2.0

package/dist/bpmn/check-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { type CliExitCode } from '../cli-run.js';
+export declare function run(argv: string[]): Promise<CliExitCode>;

package/dist/bpmn/check-cli.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * check-cli — fast static validation of a <Name>.bpmn.ts (no output file).
+ *
+ * Usage:
+ *   node --experimental-strip-types check-cli.js <bpmn.ts | BaseName>
+ *
+ * Exit 0 = clean; exit 1 = at least one error. Warnings print but do not fail.
+ */
+import { resolveBpmnFile, loadBuiltBpmn } from './load.js';
+import { check } from './check.js';
+import { runWhenInvokedDirectly } from '../cli-run.js';
+import { ensureTypeScriptRuntime } from '../node-runtime.js';
+export async function run(argv) {
+    if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+        console.error('usage: check <bpmn.ts | BaseName>');
+        return 2;
+    }
+    ensureTypeScriptRuntime();
+    const built = await loadBuiltBpmn(resolveBpmnFile(argv[0]));
+    const diags = check(built);
+    for (const d of diags)
+        console.error(`  ${d.level === 'error' ? '✗' : '⚠'} [${d.code}] ${d.message}`);
+    const errors = diags.filter((d) => d.level === 'error').length;
+    if (errors) {
+        console.error(`check: ${errors} error(s).`);
+        return 1;
+    }
+    console.error(`check: ok${diags.length ? ` (${diags.length} warning(s))` : ''}.`);
+    return 0;
+}
+runWhenInvokedDirectly(import.meta.url, 'check', run);

package/dist/bpmn/check.d.ts

@@ -0,0 +1,25 @@
+/**
+ * bpmn/check — fast static validation of a BuiltBpmn before serialization.
+ *
+ * Surfaces the common Maestro canvas-rule failures early (dangling flow refs,
+ * duplicate ids, a gateway branch with no condition, a superfluous gateway, an
+ * implicit join, a missing start event, a boundary event attached to nothing, an
+ * empty timer) so authoring gets instant feedback. The authoritative gate is
+ * still `uip maestro bpmn validate` (`validateBpmnCanvas`) on the emitted
+ * `.bpmn`.
+ *
+ * **An `error` here must mirror a real platform rule.** Being stricter than
+ * `validate` is worse than being looser: it refuses processes that deploy and run
+ * correctly, and the author has no way to appeal. Where this file is deliberately
+ * stricter than the platform — an unconditioned inclusive-gateway branch, an
+ * implicit join — the diagnostic is a `warning`, and its comment says which
+ * platform rule it corresponds to and how the two differ.
+ */
+import type { BuiltBpmn } from './bpmn-sdk.js';
+export interface Diagnostic {
+    level: 'error' | 'warning';
+    code: string;
+    message: string;
+    where?: string;
+}
+export declare function check(built: BuiltBpmn): Diagnostic[];

package/dist/bpmn/check.js

@@ -0,0 +1,430 @@
+import { processId } from './serialize.js';
+import { bindingRequiredFields, missingRequiredContext, missingRequiredInputs, registryType, REGISTRY_GAPS, unsatisfiableRequiredInputs, } from './typed-node.js';
+const GATEWAY_KINDS = new Set(['exclusiveGateway', 'parallelGateway', 'inclusiveGateway', 'eventBasedGateway']);
+/**
+ * What a boundary event may attach to. `connector` belongs here: it serializes to
+ * a `bpmn:sendTask`, which is an activity like any other, and catching a
+ * connector's failure is the commonest error-handling shape there is.
+ */
+const ACTIVITY_KINDS = new Set(['task', 'scriptTask', 'subProcess', 'connector', 'typed', 'connectorEvent', 'externalTask']);
+export function check(built) {
+    const diags = [];
+    if (!built.id)
+        diags.push({ level: 'error', code: 'NO_ID', message: 'bpmn() requires an id.' });
+    const seenIds = new Set();
+    checkScope(built.nodes, built.flows, 'process', diags, seenIds, true);
+    checkScopedVars(built, diags);
+    checkDocumentIds(built, diags);
+    return diags;
+}
+/**
+ * Every `id` in the document must be unique — including across KINDS.
+ *
+ * Not a style rule. `bpmn-moddle` keeps one document-global id registry, so a
+ * second use of an id makes its whole element **unparsable**, and it drops it:
+ *
+ *     unparsable content <bpmn:task> detected … nested error: duplicate ID <after>
+ *
+ * `.var('after', …)` next to `.task('after', …)` therefore emits a `.bpmn` whose
+ * task simply is not there. Both validators still pass it — the canvas one
+ * downgrades the now-dangling flows to warnings and `uip maestro bpmn validate`
+ * reports `Valid` — and the runtime then dies with `Unknown element 'after'`, or
+ * worse, silently does no work if nothing else routes through the hole. So this
+ * is the only gate that can catch it, and it has to be an error.
+ *
+ * The ids in play are every element and flow, every variable and binding, the
+ * synthesized `Message_n`/`Error_n` declarations, and the process itself.
+ */
+function checkDocumentIds(built, diags) {
+    const owners = new Map();
+    const claim = (id, kind) => {
+        const existing = owners.get(id);
+        if (existing === undefined) {
+            owners.set(id, kind);
+            return;
+        }
+        diags.push({
+            level: 'error',
+            code: 'DUPLICATE_DOCUMENT_ID',
+            message: `id "${id}" is used by both ${existing} and ${kind}. Every id in a .bpmn must be unique — ` +
+                `the XML parser drops the second element that reuses one, so it disappears from the process.`,
+            where: id,
+        });
+    };
+    claim(built.id, 'the process');
+    const walk = (nodes, flows) => {
+        for (const n of nodes) {
+            claim(n.id, `element "${n.id}"`);
+            if (n.kind === 'subProcess') {
+                for (const v of n.variables)
+                    claim(v.id, `variable "${v.id}"`);
+                walk(n.nodes, n.flows);
+            }
+        }
+        for (const f of flows)
+            claim(f.id, `flow "${f.id}"`);
+    };
+    walk(built.nodes, built.flows);
+    for (const v of built.variables)
+        claim(v.id, `variable "${v.id}"`);
+    for (const b of built.bindings)
+        claim(b.id, `binding "${b.id}"`);
+    for (const mm of built.messages)
+        claim(mm.id, `message "${mm.name}"`);
+    for (const e of built.errors)
+        claim(e.id, `error "${e.name}"`);
+}
+/**
+ * A variable scoped with `elementId` must name an element that exists.
+ *
+ * The runtime resolves the scope by id and has nothing to fall back on, so a typo
+ * makes the variable unreachable — silently, with no diagnostic anywhere else.
+ */
+function checkScopedVars(built, diags) {
+    const ids = new Set();
+    const walk = (nodes) => {
+        for (const n of nodes) {
+            ids.add(n.id);
+            if (n.kind === 'subProcess')
+                walk(n.nodes);
+        }
+    };
+    walk(built.nodes);
+    // The PROCESS is a legal scope for a variable, and its id is not a flow element,
+    // so it has to be added by hand. Real exports scope variables to it — the ones
+    // an author declares on the canvas rather than on a node — and every one of them
+    // was reported as scoped to an element that does not exist.
+    ids.add(processId(built.id));
+    const allVars = [...built.variables];
+    const collect = (nodes) => {
+        for (const n of nodes) {
+            if (n.kind !== 'subProcess')
+                continue;
+            allVars.push(...n.variables);
+            collect(n.nodes);
+        }
+    };
+    collect(built.nodes);
+    for (const v of allVars) {
+        if (v.elementId !== undefined && !ids.has(v.elementId))
+            diags.push({
+                level: 'error',
+                code: 'SCOPED_VAR_UNKNOWN_ELEMENT',
+                message: `Variable "${v.id}" is scoped to element "${v.elementId}", which does not exist.`,
+                where: v.id,
+            });
+    }
+}
+/**
+ * A duration the RUNTIME can parse — days/hours/minutes/seconds only.
+ *
+ * Deliberately narrower than ISO-8601: the runtime's duration parser accepts
+ * `P[nD][T[nH][nM][nS]]` and nothing else, so a spec-legal `P1W` or `P1Y` is
+ * accepted by `validate` and then fails at run time. Same reason the canvas has
+ * its own `TIMER_DURATION_WEEK_UNSUPPORTED` rule.
+ */
+const RUNTIME_DURATION = /^P(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?)?$/i;
+function isRuntimeDuration(v) {
+    // A bare `P`/`PT` matches the shape but carries no components — the same
+    // "validates, then no runtime can parse it" trap the timer eval card exists for.
+    return RUNTIME_DURATION.test(v) && /\d/.test(v);
+}
+/** Retry and loop options, checked per activity. */
+function checkActivityFields(n, diags) {
+    // A script task whose body is missing or blank. The wire form of a script task IS its
+    // `<bpmn:script>` body, so without one the emitter writes an activity that parses,
+    // validates and runs — and does nothing. Every gate stays green: `check` passed, the
+    // compile succeeded, `uip maestro bpmn validate` returned Success, and the emitted file
+    // contained zero `<bpmn:script>` elements. The failure only shows up as a variable that
+    // never changed, which is the hardest kind of wrong to attribute.
+    //
+    // Reachable from ordinary authoring: `script` is a required field, but passing the body
+    // under any other key (a plausible `body:`) satisfies the runtime object while leaving
+    // `script` undefined, and TypeScript only catches that when the author is compiling
+    // types rather than running the file.
+    if (n.kind === 'scriptTask' && (n.script === undefined || n.script.trim() === ''))
+        diags.push({
+            level: 'error',
+            code: 'SCRIPT_TASK_NO_BODY',
+            message: `Script task "${n.id}" has no script body, so it would emit an activity that runs and does nothing. ` +
+                `Pass the Jint JavaScript as \`script\` (\`.scriptTask('${n.id}', { script: 'return { … };' })\`).`,
+            where: n.id,
+        });
+    if (!('retry' in n) && !('loop' in n))
+        return;
+    const retry = 'retry' in n ? n.retry : undefined;
+    if (retry) {
+        if (!Number.isInteger(retry.maxRetries) || retry.maxRetries < 1)
+            diags.push({
+                level: 'error',
+                code: 'RETRY_INVALID_COUNT',
+                message: `Retry on "${n.id}" needs maxRetries to be a positive integer (got ${retry.maxRetries}); the runtime ignores a policy with fewer.`,
+                where: n.id,
+            });
+        for (const [field, value] of [
+            ['backoff', retry.backoff],
+            ['maxDuration', retry.maxDuration],
+        ]) {
+            if (value !== undefined && !isRuntimeDuration(value))
+                diags.push({
+                    level: 'error',
+                    code: 'RETRY_INVALID_DURATION',
+                    message: `Retry ${field} on "${n.id}" is "${value}"; the runtime parses days/hours/minutes/seconds only, e.g. "PT30S" or "P1DT12H".`,
+                    where: n.id,
+                });
+        }
+        if (retry.exponentialBase !== undefined && retry.backoffType !== 'exponential')
+            diags.push({
+                level: 'warning',
+                code: 'RETRY_BASE_WITHOUT_EXPONENTIAL',
+                message: `Retry on "${n.id}" sets exponentialBase but backoffType is not 'exponential', so it has no effect.`,
+                where: n.id,
+            });
+    }
+    const loop = 'loop' in n ? n.loop : undefined;
+    if (loop) {
+        if (!loop.collection)
+            diags.push({ level: 'error', code: 'LOOP_NO_COLLECTION', message: `Loop on "${n.id}" needs a collection expression.`, where: n.id });
+        if (!loop.itemVar)
+            diags.push({ level: 'error', code: 'LOOP_NO_ITEM_VAR', message: `Loop on "${n.id}" needs an itemVar to bind each item to.`, where: n.id });
+        // The local engine now HONOURS a completion condition, but only on a sequential
+        // loop. A parallel loop has dispatched every iteration before the first could
+        // report, so there is nothing left to stop — BPMN's answer is to cancel the
+        // remaining instances, which the engine does not implement. So the warning
+        // narrowed from "never evaluated" to exactly the case that is still not.
+        if (loop.completion !== undefined && loop.sequential !== true)
+            diags.push({
+                level: 'warning',
+                code: 'LOOP_COMPLETION_NOT_LOCAL',
+                message: `Loop completion on "${n.id}" is emitted for the platform but NOT evaluated by the local engine on a ` +
+                    `PARALLEL loop, so a local run iterates the whole collection. Set \`sequential: true\` to have it honoured locally.`,
+                where: n.id,
+            });
+    }
+}
+function checkScope(nodes, flows, where, diags, seenIds, isTop, 
+/**
+ * Whether the CONTAINER of these nodes is an event sub-process. The process root
+ * never is, so it defaults false — see ERROR_START_OUTSIDE_EVENT_SUBPROCESS below.
+ */
+inEventSubProcess = false) {
+    const nodeIds = new Set();
+    for (const n of nodes)
+        nodeIds.add(n.id);
+    // Duplicate ids (globally across the document).
+    for (const n of nodes)
+        dupId(n.id, seenIds, diags, where);
+    for (const f of flows)
+        dupId(f.id, seenIds, diags, where);
+    // At least one start event per scope that has any nodes.
+    //
+    // "Start event" is the ELEMENT, not the builder kind. A registry-backed node can
+    // be one too — `Intsvc.TimerTrigger` and `Intsvc.EventTrigger` both serialize to
+    // `bpmn:StartEvent` — and keying off `kind === 'startEvent'` alone reported
+    // NO_START on a process that has one, refusing an artifact the platform accepts.
+    if (nodes.length && !nodes.some(isStartElement))
+        diags.push({ level: isTop ? 'error' : 'warning', code: 'NO_START', message: `${where} has no start event.`, where });
+    // Flow endpoints must resolve within this scope.
+    for (const f of flows) {
+        if (!nodeIds.has(f.source))
+            diags.push({ level: 'error', code: 'DANGLING_FLOW', message: `Flow "${f.id}" source "${f.source}" is not an element in ${where}.`, where: f.id });
+        if (!nodeIds.has(f.target))
+            diags.push({ level: 'error', code: 'DANGLING_FLOW', message: `Flow "${f.id}" target "${f.target}" is not an element in ${where}.`, where: f.id });
+    }
+    const outgoing = new Map();
+    const incomingCount = new Map();
+    for (const f of flows) {
+        const outs = outgoing.get(f.source) ?? [];
+        outs.push(f);
+        outgoing.set(f.source, outs);
+        incomingCount.set(f.target, (incomingCount.get(f.target) ?? 0) + 1);
+    }
+    for (const n of nodes) {
+        const outs = outgoing.get(n.id) ?? [];
+        const ins = incomingCount.get(n.id) ?? 0;
+        // Exclusive/inclusive gateways: every non-default outgoing needs a condition —
+        // but only where the platform requires it. Its rule
+        // (ConditionalFlowRule/validateConditionalSequenceFlow) fires for a
+        // `bpmn:ExclusiveGateway` with MORE THAN ONE outgoing flow. A gateway with one
+        // outgoing flow is a JOIN, and its single flow is unconditional by definition;
+        // demanding a condition there refused a shape the platform validates and the
+        // runtime executes, leaving `default` as a misleading workaround. Inclusive
+        // gateways are outside the platform's rule, so an unconditioned branch there is
+        // a warning — suspicious, not invalid.
+        if (n.kind === 'exclusiveGateway' || n.kind === 'inclusiveGateway') {
+            if (n.default !== undefined && !outs.some((o) => o.id === n.default))
+                diags.push({ level: 'error', code: 'BAD_DEFAULT', message: `Gateway "${n.id}" default "${n.default}" is not one of its outgoing flows.`, where: n.id });
+            if (outs.length > 1) {
+                const level = n.kind === 'exclusiveGateway' ? 'error' : 'warning';
+                for (const o of outs)
+                    if (o.id !== n.default && o.condition === undefined)
+                        diags.push({ level, code: 'MISSING_CONDITION_EXPRESSION', message: `Outgoing flow "${o.id}" of gateway "${n.id}" has no condition.`, where: o.id });
+            }
+        }
+        // A gateway with exactly one in and one out is superfluous.
+        if (GATEWAY_KINDS.has(n.kind) && ins === 1 && outs.length === 1)
+            diags.push({ level: 'warning', code: 'SUPERFLUOUS_GATEWAY', message: `Gateway "${n.id}" has one incoming and one outgoing flow; remove it.`, where: n.id });
+        // An activity or event with >1 incoming flow is an implicit join. A WARNING,
+        // not an error: the platform's FAKE_JOIN rule only matches the abstract types
+        // `bpmn:Activity`/`bpmn:Event`, which never appear on real exported BPMN, so
+        // the rule is dormant there and an implicit merge validates and runs. Joining
+        // through a gateway is still the clearer shape, hence the nudge.
+        if (!GATEWAY_KINDS.has(n.kind) && n.kind !== 'boundaryEvent' && ins > 1)
+            diags.push({
+                level: 'warning',
+                code: 'FAKE_JOIN',
+                message: `"${n.id}" has ${ins} incoming flows; the platform accepts this, but joining with a gateway is clearer.`,
+                where: n.id,
+            });
+        // Boundary events must attach to an activity in the same scope.
+        if (n.kind === 'boundaryEvent') {
+            const target = nodes.find((x) => x.id === n.attachedTo);
+            if (!target)
+                diags.push({ level: 'error', code: 'BOUNDARY_UNATTACHED', message: `Boundary event "${n.id}" attaches to unknown element "${n.attachedTo}".`, where: n.id });
+            else if (!ACTIVITY_KINDS.has(target.kind))
+                diags.push({ level: 'error', code: 'BOUNDARY_NOT_ACTIVITY', message: `Boundary event "${n.id}" must attach to an activity, not "${target.kind}".`, where: n.id });
+        }
+        // A timer event definition needs one of duration/date/cycle.
+        // An error START event only means something inside an event sub-process: that is
+        // BPMN's construct for catching an error thrown elsewhere in the same container.
+        // At the process root nothing can throw into it, so the whole handler branch is
+        // unreachable — and `uip maestro bpmn validate` accepts it silently, so without
+        // this the author's first clue is a handler that never runs on a real failure.
+        if (n.kind === 'startEvent' && n.event?.type === 'error' && !inEventSubProcess) {
+            diags.push({
+                level: 'error',
+                code: 'ERROR_START_OUTSIDE_EVENT_SUBPROCESS',
+                message: `Error start event "${n.id}" is not inside an event sub-process, so nothing can throw into it. ` +
+                    'Put it in `.subProcess(id, fn, { triggeredByEvent: true })` as that scope\'s single start event.',
+                where: n.id,
+            });
+        }
+        if (n.kind !== 'subProcess' && 'event' in n && n.event?.type === 'timer') {
+            const t = n.event.timer;
+            if (t.duration === undefined && t.date === undefined && t.cycle === undefined)
+                diags.push({ level: 'error', code: 'TIMER_MISSING_FIELD', message: `Timer on "${n.id}" needs a duration, date, or cycle.`, where: n.id });
+        }
+        // Retry / loop options on any activity.
+        checkActivityFields(n, diags);
+        // A registry-backed node's required context fields. This is what
+        // `uip maestro bpmn validate` reports as EMPTY_REQUIRED_FIELD; hearing it from
+        // the SDK is faster, and the registry snapshot already knows the answer.
+        if (n.kind === 'typed') {
+            // Fields the platform insists be `=bindings.<id>` references rather than
+            // literals. The typed builder methods bind these automatically, so this
+            // fires on a hand-built node or a family whose wrapper forgot — which is
+            // exactly when the CLI would otherwise be the one to say so
+            // (`context input "name" must reference project bindings`).
+            // Context reaches a node two ways — see the note on `contextNames` below; a
+            // binding declared in a verbatim row is still a binding.
+            const contextView = { ...n.context };
+            for (const row of n.contextRows ?? [])
+                contextView[row.name] = row.value ?? row.body ?? '';
+            for (const field of bindingRequiredFields(n.type)) {
+                const value = contextView[field.name];
+                if (typeof value === 'string' && value.startsWith('=bindings.'))
+                    continue;
+                diags.push({
+                    level: 'error',
+                    code: 'BINDING_REQUIRED',
+                    message: `"${n.id}" (${n.type}) field "${field.name}" must reference a binding ` +
+                        `(=bindings.<id>) targeting resource "${field.bindingInfo?.resource}" / ` +
+                        `"${field.bindingInfo?.propertyAttribute}", not a literal.`,
+                    where: n.id,
+                });
+            }
+            // Context reaches a node two ways — the `context` record, or the verbatim
+            // `contextRows` an importer uses when a row carries detail the record cannot
+            // hold (its own type, a `target`, or the absence of a value). Both are context,
+            // so both satisfy a required field.
+            //
+            // Reading only the record meant an imported node whose rows happened to need
+            // spelling out reported EVERY required field missing — on an artifact that
+            // carries all of them. `contextRowsNeedSpellingOut` decides which form decompile
+            // emits, so whether this fired depended on a detail of the source document that
+            // has nothing to do with whether the field is set.
+            const contextNames = contextView;
+            for (const field of missingRequiredContext(n.type, contextNames)) {
+                diags.push({
+                    level: 'error',
+                    code: 'EMPTY_REQUIRED_FIELD',
+                    message: `"${n.id}" (${n.type}) is missing required field "${field}".`,
+                    where: n.id,
+                });
+            }
+            // The same rule over the PAYLOAD fields — the platform's RequiredFieldsRule
+            // draws on both, so an unset required input is the same EMPTY_REQUIRED_FIELD.
+            for (const field of missingRequiredInputs(n.type, n.inputs, contextNames)) {
+                diags.push({
+                    level: 'error',
+                    code: 'EMPTY_REQUIRED_FIELD',
+                    message: `"${n.id}" (${n.type}) is missing required input "${field}".`,
+                    where: n.id,
+                });
+            }
+            // A type that permits only the output row its spec declares. Reachable via
+            // the generic `.activity()`; the typed wrapper does not offer the option.
+            if (REGISTRY_GAPS[n.type]?.outputRowsFixed && Object.keys(n.outputs ?? {}).length) {
+                diags.push({
+                    level: 'error',
+                    code: 'OUTPUT_ROWS_FIXED',
+                    message: `"${n.id}" (${n.type}) permits only its declared output row, so the extra row(s) ` +
+                        `${Object.keys(n.outputs ?? {}).map((k) => `"${k}"`).join(', ')} will be refused ` +
+                        `("output name must be \\"${registryType(n.type).output?.name}\\""). Use outputVar and read the ` +
+                        `typed row instead.`,
+                    where: n.id,
+                });
+            }
+            // A type whose required payload fields cannot be expressed at all. Warning,
+            // not error: the node is as correct as the registry allows, so refusing it
+            // would block work the platform, not the author, has to fix. Saying nothing
+            // is worse — the artifact validates here and is rejected by the CLI.
+            const unsatisfiable = unsatisfiableRequiredInputs(n.type);
+            if (unsatisfiable.length) {
+                diags.push({
+                    level: 'warning',
+                    code: 'REQUIRED_INPUT_UNSATISFIABLE',
+                    message: `"${n.id}" (${n.type}) declares required input(s) ${unsatisfiable.map((f) => `"${f}"`).join(', ')}, ` +
+                        `but its "${registryType(n.type).inputPattern}" pattern merges every input into one row, so the ` +
+                        `platform's required-field rule cannot see them. \`uip maestro bpmn validate\` will report ` +
+                        `EMPTY_REQUIRED_FIELD whatever this node carries — a platform defect, not an authoring error. ` +
+                        `See docs/BPMN_COVERAGE_DESIGN.md D13.`,
+                    where: n.id,
+                });
+            }
+        }
+        // Recurse into sub-process bodies.
+        if (n.kind === 'subProcess')
+            checkScope(n.nodes, n.flows, `subProcess "${n.id}"`, diags, seenIds, false, n.triggeredByEvent === true);
+    }
+}
+/**
+ * Whether this node serializes to a `bpmn:StartEvent`.
+ *
+ * Two ways to be one: the builder's own `startEvent` kind, or a registry-backed
+ * node whose spec places it on that element. An unknown extension type answers
+ * `false` rather than throwing — a bad type has its own diagnostic, and NO_START is
+ * the wrong place to report it.
+ */
+function isStartElement(n) {
+    if (n.kind === 'startEvent')
+        return true;
+    // A connector EVENT TRIGGER is a start event too — `Intsvc.EventTrigger`
+    // serializes to `bpmn:StartEvent`. Its mid-flow sibling (`subscribe: 'event'`,
+    // a receive task) is not.
+    if (n.kind === 'connectorEvent')
+        return n.subscribe === 'trigger';
+    if (n.kind !== 'typed')
+        return false;
+    try {
+        return registryType(n.type).element === 'bpmn:StartEvent';
+    }
+    catch {
+        return false;
+    }
+}
+function dupId(id, seen, diags, where) {
+    if (seen.has(id))
+        diags.push({ level: 'error', code: 'DUP_ID', message: `Duplicate element id "${id}" in ${where}.`, where: id });
+    seen.add(id);
+}

package/dist/bpmn/compile-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { type CliExitCode } from '../cli-run.js';
+export declare function run(argv: string[]): Promise<CliExitCode>;

package/dist/bpmn/compile-cli.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * compile-cli — <Name>.bpmn.ts → <Name>.bpmn
+ *
+ * Usage:
+ *   node --experimental-strip-types compile-cli.js <bpmn.ts | BaseName> [-o out.bpmn]
+ *
+ * Runs the fast static check first; if it passes, serializes to Maestro `.bpmn`
+ * XML (semantic-only — no diagram). The authoritative deploy gate is
+ * `uip maestro bpmn validate`; a separate "tidy" step lays the diagram out.
+ */
+import { writeFileSync, existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { resolveBpmnFile, loadBuiltBpmn } from './load.js';
+import { serialize } from './serialize.js';
+import { check } from './check.js';
+import { Library } from '../core/library.js';
+import { Bindings } from '../core/bindings.js';
+import { runWhenInvokedDirectly } from '../cli-run.js';
+import { ensureTypeScriptRuntime } from '../node-runtime.js';
+import { resolveLibraryDir } from '../registry/cache.js';
+function opt(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+export async function run(argv) {
+    if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+        console.error('usage: compile <bpmn.ts | BaseName> [-o out.bpmn]');
+        return 2;
+    }
+    const flags = new Set(['-o', '--library', '--bindings']);
+    const pos = argv.find((a, i) => !flags.has(a) && !flags.has(argv[i - 1]));
+    if (!pos) {
+        console.error('compile: missing <bpmn.ts | BaseName>');
+        return 2;
+    }
+    const file = resolveBpmnFile(pos);
+    ensureTypeScriptRuntime();
+    const built = await loadBuiltBpmn(file);
+    const diags = check(built);
+    for (const d of diags)
+        console.error(`  ${d.level === 'error' ? '✗' : '⚠'} [${d.code}] ${d.message}`);
+    if (diags.some((d) => d.level === 'error')) {
+        console.error(`compile: ${diags.filter((d) => d.level === 'error').length} error(s); not emitting.`);
+        return 1;
+    }
+    // Connector service tasks resolve against the library (like Flow's/Case's
+    // compile-cli); load it only when present, and bindings.json alongside the .ts.
+    const libDir = resolveLibraryDir(opt(argv, '--library'));
+    const library = libDir && existsSync(join(libDir, 'index.json')) ? new Library(libDir) : undefined;
+    const bindFile = opt(argv, '--bindings') ?? (existsSync('bindings.json') ? 'bindings.json' : undefined);
+    const bindings = new Bindings(bindFile);
+    const xml = await serialize(built, { library, bindings });
+    const base = basename(file).replace(/\.bpmn\.ts$|\.ts$/, '');
+    const out = opt(argv, '-o') ?? `${base}.bpmn`;
+    writeFileSync(out, xml);
+    console.log(`compile: wrote ${out} (${built.nodes.length} element(s))`);
+    return 0;
+}
+runWhenInvokedDirectly(import.meta.url, 'compile', run);

package/dist/bpmn/connector.d.ts

@@ -0,0 +1,56 @@
+/**
+ * bpmn/connector — emit an Integration Service connector service task as a
+ * `bpmn:sendTask` carrying a `uipath:activity` (`Intsvc.ActivityExecution`).
+ *
+ * The connector DATA (wiring context, path/query/body input split, output schema,
+ * metadata blob, connection/folder bindings) is exactly what the Flow node and the
+ * Case task carry — all derived from the same `ResolvedConnector` (`Library.resolve`)
+ * — only the ENVELOPE differs: moddle `uipath:*` elements here vs. caseplan JSON in
+ * `case/serialize.ts`. The shape was verified against real Studio Web `.bpmn`
+ * exports (`Intsvc.ActivityExecution` on a `bpmn:sendTask`; see CONNECTORS_DESIGN.md
+ * §D) and passes `uip maestro bpmn validate`.
+ *
+ * NOTE: the DATA computation mirrors `case/serialize.ts` (`connectorTaskData`/
+ * `connectorMetadata`/`connectorOutputs`); the two could be unified into a shared
+ * `core/` helper in a later cleanup — kept separate here to keep this change
+ * BPMN-only.
+ *
+ * All values are embedded via `bpmn-moddle` (`m.create`), which escapes attributes,
+ * text, and CDATA — never string-concatenated into XML.
+ */
+import type BpmnModdle from 'bpmn-moddle';
+import type { ModdleElement } from 'bpmn-moddle';
+import { type BpmnNode } from './bpmn-sdk.js';
+import type { Library } from '../core/library.js';
+import type { Bindings } from '../core/bindings.js';
+type El = ModdleElement;
+type ConnectorNode = Extract<BpmnNode, {
+    kind: 'connector';
+}>;
+/** The subset of the serializer context this emitter needs. */
+export interface ConnectorCtx {
+    m: BpmnModdle;
+    library?: Library;
+    bindings?: Bindings;
+    bindingSink: Map<string, Record<string, unknown>>;
+    /**
+     * Declared Maestro `type` for a variable id, for typing an author-mapped output
+     * row. Optional so the connector emitter (which writes its own rows) is
+     * unaffected; the Phase 3d families pass it through to `createTypedNode`.
+     */
+    varTypeOf?: (varId: string) => string | undefined;
+}
+export declare function createConnectorTask(ctx: ConnectorCtx, n: ConnectorNode): El;
+/**
+ * Resolve a symbolic connection/folder to a process-level binding.
+ *
+ * Exported for the Phase 3d nodes, which need the identical closure: a connector
+ * event and an external agent/workflow each reference a connection and a folder
+ * the same way a connector activity does, and duplicating this was how the two
+ * families drifted apart in `case/serialize.ts`.
+ */
+export declare function connectorBindingRef(ctx: ConnectorCtx, name: string | undefined, resource: string, propertyAttribute: string, displayName: string): {
+    id: string;
+    resourceKey: string;
+} | undefined;
+export {};