@uipath/maestro-builder-sdk 5.2.0

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

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

package/dist/bpmn/tidy-cli.js

@@ -0,0 +1,39 @@
+/**
+ * tidy-cli — lay out a semantic-only `.bpmn` (add the `bpmndi` diagram).
+ *
+ * Usage:
+ *   node --experimental-strip-types tidy-cli.js <file.bpmn> [-o out.bpmn]
+ *
+ * The SDK's serializer emits semantic-only BPMN (no diagram) because validation
+ * is layout-independent. This step runs `bpmn-auto-layout` to synthesize a full
+ * `bpmndi:BPMNDiagram` — a `BPMNShape` per node and a `BPMNEdge` per flow — so
+ * the file imports into a visual canvas. The `uipath:*` extension payloads are
+ * preserved. Overwrites the input unless `-o` is given.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { layoutProcess } from 'bpmn-auto-layout';
+import { finalizeBpmnXml } from './serialize.js';
+import { runWhenInvokedDirectly } from '../cli-run.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: tidy <file.bpmn> [-o out.bpmn]');
+        return 2;
+    }
+    const flags = new Set(['-o']);
+    const input = argv.find((a, i) => !flags.has(a) && !flags.has(argv[i - 1]));
+    if (!input) {
+        console.error('tidy: missing <file.bpmn>');
+        return 2;
+    }
+    const laidOut = finalizeBpmnXml(await layoutProcess(readFileSync(input, 'utf8')));
+    const out = opt(argv, '-o') ?? input;
+    writeFileSync(out, laidOut.endsWith('\n') ? laidOut : laidOut + '\n');
+    const shapes = (laidOut.match(/BPMNShape/g) ?? []).length;
+    console.log(`tidy: laid out ${out} (${shapes} shape(s))`);
+    return 0;
+}
+runWhenInvokedDirectly(import.meta.url, 'tidy', run);

package/dist/bpmn/typed-node.d.ts

@@ -0,0 +1,382 @@
+/**
+ * bpmn/typed-node — emit a REGISTRY-BACKED node from its spec.
+ *
+ * Phase 3 of `docs/BPMN_COVERAGE_DESIGN.md`. The registry already says, per
+ * extension type, everything the wire needs: which BPMN element carries it, which
+ * `uipath:*` tag, the context fields and which are required, how inputs are
+ * shaped, what the output row looks like, and whether the element needs an event
+ * definition. So there is ONE emitter driven by `registry-types.json`, not one
+ * per type — the alternative is 30 near-identical functions and a `switch` that
+ * grows with the platform.
+ *
+ * This is deliberately NOT a code generator. Generated emitters would need
+ * reviewing on every registry refresh; a spec table turns the same refresh into a
+ * data diff, and the emitter stays one readable function.
+ */
+import type BpmnModdle from 'bpmn-moddle';
+import type { ModdleElement } from 'bpmn-moddle';
+type El = ModdleElement;
+/** One context field of a typed node, as the registry describes it. */
+export interface RegistryContextField {
+    name: string;
+    /** The designer's label — what the product validator quotes in its diagnostics. */
+    displayName: string | null;
+    type: string;
+    required: boolean;
+    hidden: boolean;
+    binding: boolean;
+    default: string | null;
+    /**
+     * Which resource and property a binding for this field must target, when the
+     * platform requires one. `binding: true` alone does NOT mean "must be bound" —
+     * `Intsvc.UnifiedHttpRequest`'s `url` is `binding: true` and a literal validates
+     * fine. It is `bindingInfo` together with `required` that the platform enforces.
+     */
+    bindingInfo: {
+        resource: string | null;
+        propertyAttribute: string | null;
+    } | null;
+}
+/**
+ * One PAYLOAD field of a typed node — the registry's `InputFields`, as distinct
+ * from the `ContextFields` above.
+ *
+ * Absent from the snapshot until Phase 3a, on the reading that `inputPattern` plus
+ * the type-level `inputName`/`inputTarget` said everything emission needed. Two
+ * defects came out of that gap, both invisible to `uip maestro bpmn validate`:
+ * a `separateInputs` row was targeted at its own key rather than the field's
+ * declared `target`, and every payload row was typed `json`, so a field declared
+ * `string` arrived JSON-quoted.
+ *
+ * Not every type declares these. A connector's inputs are discovered from the
+ * connector library rather than the registry, so `Intsvc.ActivityExecution` has
+ * none and its rows keep deriving their target from the key — see `inputRows`.
+ */
+export interface RegistryInputField {
+    name: string;
+    displayName: string | null;
+    type: string;
+    required: boolean;
+    hidden: boolean;
+    /**
+     * Where the row points. `null` means the type's shared `inputTarget` applies,
+     * which is the case for every `mergedBody` type — its fields have no target of
+     * their own because they are merged into a single row.
+     */
+    target: string | null;
+    default: string | null;
+}
+/** The output row a typed node writes, or `null` when it has none. */
+export interface RegistryOutput {
+    name: string;
+    type: string;
+    /** `=response`-style source; `null` means the row carries no `source` attribute. */
+    source: string | null;
+    relative: boolean;
+}
+/** One extension type's emission spec. */
+export interface RegistryTypeSpec {
+    /** `bpmn:SendTask`, `bpmn:ServiceTask`, … */
+    element: string | null;
+    /** `uipath:activity` | `uipath:event` | `uipath:mapping`. */
+    tag: string | null;
+    inputPattern: 'none' | 'mergedBody' | 'separateInputs' | 'splitInputsItemData' | 'scriptArgs' | string;
+    inputName: string | null;
+    inputTarget: string | null;
+    context: RegistryContextField[];
+    /** The payload fields the registry declares; empty for types with dynamic inputs. */
+    inputs: RegistryInputField[];
+    output: RegistryOutput | null;
+    /** e.g. `bpmn:messageEventDefinition` — what makes a message event a message event. */
+    eventDefinition: string | null;
+    /** True when authoring needs a tenant read (a connection, a process, a queue). */
+    requiresDiscovery: boolean;
+    bindingPattern: string;
+}
+/** Every extension type in the snapshot, sorted. */
+export declare function registryTypeNames(): string[];
+/**
+ * The spec for one extension type.
+ *
+ * @param type - The extension type, e.g. `'Intsvc.UnifiedHttpRequest'`.
+ * @returns Its emission spec.
+ * @throws If the type is not in the committed snapshot — which means either a
+ * typo or a registry refresh the snapshot has not caught up with.
+ */
+export declare function registryType(type: string): RegistryTypeSpec;
+/**
+ * Facts the platform enforces but the registry does not state.
+ *
+ * Every entry here was found by probing `uip maestro bpmn validate`, not read out
+ * of a spec — so every entry is a liability: it can drift without the snapshot
+ * changing, and nothing upstream promises it. Keeping them in one visible table
+ * beats burying them in a builder method, and each is pinned by a test so a
+ * platform change fails loudly instead of silently emitting a rejected artifact.
+ *
+ * `resourceSubType` — `Orchestrator.StartAgentJob` requires its process bindings to
+ * carry `resourceSubType="Agent"` on top of the `resource`/`propertyAttribute` the
+ * registry does give:
+ *
+ *     [error] Orchestrator.StartAgentJob binding "x" must target Agent name.
+ *
+ * `resource="Agent"` and `resource="agent"` are both rejected; only
+ * `resource="process"` + `resourceSubType="Agent"` validates. The string matches the
+ * field's `DisplayName`, but nothing says that is the rule, so it is recorded as a
+ * constant for the one type known to need it rather than derived.
+ */
+export declare const REGISTRY_GAPS: Record<string, {
+    resourceSubType?: string;
+    extraContext?: string[];
+    outputRowsFixed?: boolean;
+    notEnforcedInputs?: string[];
+}>;
+/**
+ * One `uipath:output` row, spelled out.
+ *
+ * `schema` is the row's element BODY — a JSON Schema for a `jsonSchema` row. It is
+ * modelled as `unknown` rather than a schema type on purpose: the SDK carries it
+ * through without interpreting it, which is what makes an artifact from a platform
+ * version newer than this SDK still round-trip.
+ */
+/**
+ * One `uipath:context` input row, spelled out.
+ *
+ * The counterpart of {@link TypedOutputRow} on the input side, and for the same
+ * reason. `context` is a name→value record, so a row's declared TYPE has to be
+ * looked up in the registry — and a field the registry does not declare falls back
+ * to `string`. A real HITL node states `type="boolean"` on a field the snapshot has
+ * never heard of, so the round trip retyped it, which is the coercion hazard the
+ * runtime cares about: it switches on this `type`, and a boolean told to be a
+ * string arrives truthy whatever its value.
+ *
+ * A record also cannot say "no value attribute at all", which is different from
+ * `value=""` — 71 rows in one real file differ on exactly that.
+ */
+export interface TypedContextRow {
+    /** Field name. */
+    name: string;
+    /** The row's declared type. Defaults to `string`. */
+    type?: string;
+    /** The `value` attribute. Omitted entirely when absent — not written as `""`. */
+    value?: string;
+    /**
+     * The row's CDATA body, for a `json` field — the value itself, or a string when
+     * the exact bytes matter. See {@link BpmnBuilder.schema} for the same rule on a
+     * variable's schema.
+     */
+    body?: unknown;
+    /** The row's `target` attribute, when the artifact carries one. */
+    target?: string;
+    /** The row's `required` attribute — 11 context rows in the corpus carry one. */
+    required?: boolean;
+}
+export interface TypedOutputRow {
+    /** Row name, e.g. `response` or `Error`. */
+    name: string;
+    /** Row type, e.g. `jsonSchema`, `string`, or a registry type. Defaults to `string`. */
+    type?: string;
+    /** Variable the row writes. */
+    var?: string;
+    /** `=`-expression read against the node's result, e.g. `=response`. */
+    source?: string;
+    /** The row's body — a JSON Schema for a `jsonSchema` row. */
+    schema?: unknown;
+    /**
+     * Mark the row `custom="true"` — the product's flag for a row an author added
+     * rather than one the node's type declares.
+     */
+    custom?: boolean;
+    /** The row's `description` — designer help text the product carries on some rows. */
+    description?: string;
+    /**
+     * The row's `target`. Rare, and carried for fidelity: a real sub-process mapping
+     * writes `target=""`, which is neither absent nor meaningful, and dropping it
+     * changes the bytes.
+     */
+    target?: string;
+}
+/** What an author supplies for a typed node, on top of its id. */
+export interface TypedNodeInput {
+    /** Display name the designer shows. */
+    name?: string;
+    /** Context values, by field name — the registry decides which are required. */
+    context?: Record<string, unknown>;
+    /** Context rows spelled out, replacing `context` — see {@link TypedContextRow}. */
+    contextRows?: TypedContextRow[];
+    /** The payload, shaped per the type's `inputPattern`. */
+    inputs?: Record<string, unknown>;
+    /** The `uipath:type` `version` attribute — see `ActivityNodeOpts.typeVersion`. */
+    typeVersion?: string;
+    /** The `uipath:inputSchema` body inside `uipath:context` — see `ActivityNodeOpts.inputSchema`. */
+    inputSchema?: unknown;
+    /** Variable the output lands in. Defaults to `<id>_<outputName>`. */
+    outputVar?: string;
+    /**
+     * EXTRA output rows: variable id → `=`-expression read against the node's own
+     * result, e.g. `{ decision: '=Action' }`.
+     *
+     * Why this exists: several types declare a TYPED output — `Actions.HITL` writes
+     * `type="Actions.HITL"` with no `source` — which the designer resolves into
+     * sub-fields but the local engine cannot, so the variable stays `undefined` on a
+     * local run and nothing can branch on it. An explicit row alongside it maps one
+     * field the way every other output row works, which the runtime does resolve.
+     * The spec's own row is still emitted, so the artifact stays what the platform
+     * expects.
+     */
+    outputs?: Record<string, string>;
+    /**
+     * The output rows EXACTLY as they should be written, replacing both the spec's
+     * derived row and `outputs` above.
+     *
+     * The counterpart of `contextVerbatim` for outputs, and it exists for the same
+     * reason: an imported artifact's rows can carry detail the derived pair cannot
+     * express. A connector task (`Intsvc.ActivityExecution`) is the case that forced
+     * it — TWO rows, both `type="jsonSchema"`, each carrying a JSON schema in its
+     * element BODY (the operation's response shape, and the standard error shape).
+     * `outputs` is a variable→expression map with no room for a type or a body, so
+     * decompiling a connector through it silently dropped the response schema. That
+     * is why connectors were REFUSED by `bpmn-decompile` until this existed.
+     *
+     * An author writing `.activity()` by hand wants `outputVar`/`outputs`; this is
+     * for a caller that already knows the exact rows.
+     */
+    outputRows?: TypedOutputRow[];
+    /** `=`-expression that skips the node when truthy (activity/event tags only). */
+    skipCondition?: string;
+    /**
+     * Emit `context` EXACTLY as given — same fields, same order — injecting none of
+     * the registry's defaults.
+     *
+     * For importers, not authors. Default injection is an authoring convenience:
+     * `.http()` relies on it for `mode`, which is required, hidden, and so never
+     * passed by hand. An importer has the opposite need — the artifact already
+     * carries the fields it should, and adding a default it lacked, or reordering
+     * what it had, breaks a byte-exact round-trip. `bpmn-decompile` sets this.
+     */
+    contextVerbatim?: boolean;
+}
+/** The variable a typed node's output row writes, or `undefined` when it has none. */
+export declare function typedNodeOutputVar(id: string, type: string, outputVar?: string): string | undefined;
+/**
+ * Emit a registry-backed typed node.
+ *
+ * @param m - The moddle instance to create elements with.
+ * @param id - The BPMN element id.
+ * @param type - The extension type, e.g. `'Intsvc.UnifiedHttpRequest'`.
+ * @param input - Author-supplied name, context, payload, output variable and skip.
+ * @returns The moddle element, ready for the serializer to wire flows onto.
+ */
+export declare function createTypedNode(m: BpmnModdle, id: string, type: string, input: TypedNodeInput, 
+/**
+ * Declared Maestro `type` for a variable id, for typing the extra output rows below.
+ * Optional so a caller with no variable context still gets today's behaviour.
+ */
+varType?: (varId: string) => string | undefined): El;
+/** `uipath:Output` rows exactly as the caller spelled them, deriving nothing. */
+export declare function verbatimOutputRows(m: BpmnModdle, rows: TypedOutputRow[]): El[];
+/**
+ * The extension payload for a type and its output rows, with NO element around it.
+ *
+ * `createTypedNode` takes the element from the registry, which is right for an
+ * activity and wrong everywhere the product uses a payload as DECORATION: a
+ * `uipath:mapping` on a start event, an end event or a sub-process, a
+ * `uipath:activity` on an error boundary. Those arms of `createNode` build their
+ * own element and attach this to it, rather than letting `BPMN.Variables` turn a
+ * start event into a `bpmn:Task`.
+ *
+ * @param m - The moddle instance.
+ * @param type - The extension type, e.g. `BPMN.Variables` or `uipath:Activity`.
+ * @param rows - Output rows, emitted verbatim.
+ * @returns The payload element, ready to go inside a `bpmn:ExtensionElements`.
+ */
+export declare function createExtensionPayload(m: BpmnModdle, type: string, rows: TypedOutputRow[]): El;
+/**
+ * The context fields this type requires to be a `=bindings.<id>` reference rather
+ * than a literal.
+ *
+ * Narrower than it looks, and the narrowness is measured. `binding: true` marks a
+ * field the designer OFFERS a binding picker for — `Intsvc.UnifiedHttpRequest`'s
+ * `url` is one, and a literal URL validates fine. What the platform actually
+ * enforces is `bindingInfo` AND `required`, which today selects exactly
+ * `Orchestrator.StartAgentJob`'s `name` and `folderPath`:
+ *
+ *     [error] Orchestrator.StartAgentJob context input "name" must reference project bindings.
+ *     [error] Orchestrator.StartAgentJob binding "x" must target Agent name.
+ *
+ * Both halves are enforced — a literal is rejected, and so is a binding pointing
+ * at the wrong property.
+ *
+ * @param type - The extension type.
+ * @returns Its fields that must be bound, with the target each binding needs.
+ */
+export declare function bindingRequiredFields(type: string): RegistryContextField[];
+/**
+ * Required context fields the author left unset and the registry cannot default.
+ *
+ * Separate from emission so `check()` can report them at authoring time. Missing
+ * them is what `uip maestro bpmn validate` reports as `EMPTY_REQUIRED_FIELD`, and
+ * hearing it from the SDK is faster than hearing it from the CLI.
+ *
+ * @param type - The extension type.
+ * @param context - The context values the author supplied.
+ * @returns The names of required fields with no value and no default.
+ */
+export declare function missingRequiredContext(type: string, context?: Record<string, unknown>): string[];
+/**
+ * Required PAYLOAD fields the author left unset.
+ *
+ * The counterpart of {@link missingRequiredContext}, and reported the same way: the
+ * platform's `RequiredFieldsRule` draws on `InputFields` as well as `ContextFields`,
+ * so an unset required payload field is the same `EMPTY_REQUIRED_FIELD` the CLI
+ * would report a build later.
+ *
+ * @param type - The extension type.
+ * @param inputs - The payload the author supplied.
+ * @returns The names of required payload fields with no value and no default.
+ */
+export declare function missingRequiredInputs(type: string, inputs?: Record<string, unknown>, 
+/**
+ * The node's `uipath:context` values, which SATISFY a required payload field too.
+ *
+ * The platform's `RequiredFieldsRule` draws on both, and a trigger is where that
+ * shows: `Intsvc.EventTrigger` declares seven required inputs, and a real one
+ * carries every one of them as a `uipath:context` row rather than a
+ * `uipath:input`. Checking inputs alone reported all seven; `uip maestro bpmn
+ * validate` reports exactly one — `connectionId`, the only name the artifact
+ * genuinely does not spell (it writes `connection`). Reading both makes this
+ * agree with the CLI instead of guessing on either side of it.
+ */
+context?: Record<string, unknown>): string[];
+/**
+ * Whether this type's required payload fields are UNSATISFIABLE on the wire.
+ *
+ * A platform defect, recorded here because the SDK cannot emit its way around it.
+ * `RequiredFieldsRule` builds its required-name set from `InputFields` and then
+ * fires when a name is absent from the serialized rows **by name**. Under
+ * `mergedBody` and `splitInputsItemData` every payload field collapses into ONE row
+ * — named `body` or `ItemData` — so a required input field is never present by
+ * name and the rule fires however the node is filled in:
+ *
+ *     [error] [call] EMPTY_REQUIRED_FIELD: The field 'agentUrl' in node 'call' is
+ *                    required but has no value.
+ *
+ * Note the registry's own `XmlTemplate` for `A2A.AgentExecution` emits exactly the
+ * body-only shape that fails, which is the clearest statement that the two halves
+ * of the platform disagree rather than that the SDK is writing the wrong thing.
+ *
+ * Whether a workaround exists is per-type and not derivable from the spec, so it is
+ * not encoded here. Measured: `A2A.AgentExecution` accepts redundant sibling rows
+ * alongside the merged body (`Valid`); `Maestro.SendMessageEvent` refuses them
+ * outright — `does not support input payload "Reference"` as a row, `does not
+ * support context input "Reference"` in context, and `ItemData`'s `target="body"`
+ * is enforced — so for that type NO artifact satisfies both gates.
+ *
+ * Selects exactly `A2A.AgentExecution` and `Maestro.SendMessageEvent` today. The
+ * three other types with required payload fields are `separateInputs`, whose rows
+ * DO carry their own names, and are unaffected.
+ *
+ * @param type - The extension type.
+ * @returns The required payload field names that cannot be expressed, or `[]`.
+ */
+export declare function unsatisfiableRequiredInputs(type: string): string[];
+export {};