@uipath/maestro-builder-sdk 6.20.0 → 6.20.2

package/dist/api-index.md

@@ -219,8 +219,8 @@ could hand you spans for a version you do not have.
 | `SchedulePreset` | type | `dist/flow-sdk.d.ts:131` | Supporting types |  |
 | `script` | function | `dist/nodes/script/flow/factories.d.ts:7-14` | Actions | Declare an inline script action. |
 | `ScriptInputs` | interface | `dist/nodes/script/flow/spec.d.ts:7-44` | Option shapes | 2 field(s) |
-| `ScriptReturns` | type | `dist/core/script-return.d.ts:33-38` | Supporting types | What an author may write for `script({ returns })`: the type outright, or — for an object return — the FIELDS, which is… |
-| `ScriptReturnType` | type | `dist/core/script-return.d.ts:31-32` | Supporting types | The vocabulary a script's output can be declared as. |
+| `ScriptReturns` | type | `dist/core/script-return.d.ts:42-48` | Supporting types | What an author may write for `script({ returns })`: the type outright, or — for an object return — the FIELDS, which is… |
+| `ScriptReturnType` | type | `dist/core/script-return.d.ts:31-41` | Supporting types | The vocabulary a script's output can be declared as. |
 | `sendMessage` | function | `dist/core/actions.d.ts:2438-2456` | Actions | Post an assistant message into a live conversation (`uipath.conversational.send-message`). |
 | `SendMessageInputs` | interface | `dist/core/actions.d.ts:492-511` | Option shapes | 4 field(s) |
 | `ShownField` | interface | `dist/core/actions.d.ts:198-213` | Supporting types | A value the reviewer READS: shown on the form, filled in from the flow. |

package/dist/check.js

@@ -4814,6 +4814,7 @@ function checkRegisteredStep(entry, s, exprs, errorSource, opts, diags, typeOf,
         const ctx = {
             step: s.name,
             version: impl.version,
+            definition: () => bundledDefinition(impl.typeName, impl.version),
             report: (code, message, suggestion) => diags.push(catalogued(entry, s.name, code, message, suggestion)),
             declaredRef: (js) => {
                 const name = declaredRefName(js, triggerId);

package/dist/core/script-return.d.ts

@@ -28,14 +28,24 @@
  * into a designer error — the exact defect this file exists to remove, pointed
  * the other way.
  */
-/** The vocabulary a script's output can be declared as. */
-export type ScriptReturnType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+/**
+ * The vocabulary a script's output can be declared as.
+ *
+ * `'any'` is the platform's own declaration on `core.action.script@1.1` (the
+ * 1.0.0 definition says `'object'`), so it is valid only as the top-level
+ * `returns` of a 1.1 step; `check` refuses it on 1.0.0 and as a field type.
+ * Declaring it keeps the output open even when the body plainly returns one
+ * type; it is also how decompile writes back a 1.1 node whose output a designer
+ * left at that default.
+ */
+export type ScriptReturnType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'any';
 /**
  * What an author may write for `script({ returns })`: the type outright, or —
  * for an object return — the FIELDS, which is the spelling every other action's
- * `returns` uses (`http`, `rpaWorkflow`, `agent`).
+ * `returns` uses (`http`, `rpaWorkflow`, `agent`). A field's type is never
+ * `'any'`.
  */
-export type ScriptReturns = ScriptReturnType | Record<string, ScriptReturnType>;
+export type ScriptReturns = ScriptReturnType | Record<string, Exclude<ScriptReturnType, 'any'>>;
 /** A resolved output declaration: a type, and for objects the fields we know. */
 export interface ScriptOutputShape {
     type: ScriptReturnType;

package/dist/decompile.js

@@ -563,7 +563,9 @@ function emitRegisteredSpec(node, imp, inputNames) {
         sourceText: unwrapSource,
         plainValue: unwrapPlain,
         stepName: (nodeId) => nodeId,
-        definition: () => runDefs.get(`${node.type}@${version}`) ?? runDefs.get(node.type),
+        // The file's carried definition first; the bundled one at the node's version
+        // when the file carries none (a hand-trimmed or SDK-written file).
+        definition: () => runDefs.get(`${node.type}@${version}`) ?? BUNDLED_DEFINITIONS[`${node.type}@${version}`] ?? runDefs.get(node.type),
         warn: warnOnce,
     };
     const spec = impl.deserialize(node, ctx);
@@ -2227,6 +2229,83 @@ function sweepDroppedEdges(graph, skip) {
     }
     return lines;
 }
+/** Every out-edge of `id` on port `port`, in edge order. */
+function portEdges(graph, id, port) {
+    return graph.outEdges(id).filter((e) => e.sourcePort === port);
+}
+/** `id`'s successor edges whose target is inside `scope` (the edges `scopeSucc` follows). */
+function scopeSuccEdges(graph, id, scope) {
+    return graph.successorEdges(id).filter((e) => e.targetPort !== 'loopBack' && scope.has(e.targetNodeId));
+}
+/**
+ * The nearest node that post-dominates EVERY one of `targets` — where the paths
+ * that start at them all meet again — or `undefined` when they only meet at the
+ * scope exit. Walks each target's `ipdom` chain (the target itself first).
+ */
+function commonPostDominator(targets, ipdom) {
+    const chain = (t) => {
+        const out = [];
+        for (let n = t; n !== undefined && n !== EXIT && !out.includes(n); n = ipdom.get(n))
+            out.push(n);
+        return out;
+    };
+    const [head, ...rest] = targets.map(chain);
+    const others = rest.map((c) => new Set(c));
+    return head?.find((n) => others.every((c) => c.has(n)));
+}
+/**
+ * The region that starts with `edges`, the edges ONE source port (or a
+ * trigger) has.
+ *
+ * One edge is an ordinary region (`edgeRegion`). Two or more are a fork, which
+ * is what serialize emits for a `.parallel(...)` that is the first thing in a
+ * flow, a subflow, an entry point's prefix or a branch / switch arm: the trigger
+ * (or the arm's port) gets one edge per parallel arm, and the arms meet at the
+ * parallel's merge node. When the targets meet at a merge node the fork
+ * decompiles to that `.parallel(...)`, then the region continues from the
+ * merge's output (flow-builder-sdk#1155).
+ *
+ * Every edge in `edges` is accounted (edge accounting, #1125): the fold
+ * recreates each one. A fork whose arms never meet at a merge node has no
+ * builder spelling. Like the same shape mid-flow (`region`), it throws under
+ * `bestEffort: false`, and otherwise keeps the first arm behind a
+ * `TODO: unstructured fan-out` marker, which is what reports the other edges.
+ */
+function forkRegion(edges, stop, scope, ipdom, ctx, refInto) {
+    if (edges.length <= 1)
+        return edgeRegion(edges[0], stop, scope, ipdom, ctx, refInto);
+    const targets = edges.map((e) => e.targetNodeId);
+    const join = commonPostDominator(targets, ipdom);
+    const joinNode = join !== undefined ? ctx.graph.byId.get(join) : undefined;
+    if (join === undefined || join === stop || joinNode?.type !== T.merge) {
+        if (ctx.o.bestEffort === false)
+            throw new Error(`decompile: unstructured fan-out (${edges.length} edges).`);
+        for (const e of edges)
+            ctx.graph.accounted.add(e);
+        return [
+            `/* TODO: unstructured fan-out (${commentText(edges.length)} edges) */`,
+            ...region(targets[0], stop, scope, ipdom, ctx, refInto),
+        ];
+    }
+    for (const e of edges)
+        ctx.graph.accounted.add(e);
+    const fork = parallelSeg(join, joinNode, targets, scope, ipdom, ctx, refInto);
+    if (fork.next.brk || fork.next.cont)
+        return [fork.seg, fork.next.brk ? '.break()' : '.continue()'];
+    return [fork.seg, ...region(fork.next.cursor, stop, scope, ipdom, ctx, refInto)];
+}
+/**
+ * The `.parallel(join, [arms])` segment for a fork whose `targets` (one per
+ * edge; the caller accounts those edges) meet at the merge node `join`. Each
+ * arm is the region up to `join`. `next` is where the walk goes after the
+ * merge: its `output` edge, accounted by `continueOn` (`brk` / `cont` when
+ * that edge leaves through the enclosing loop's `break` / spelled `continue`).
+ */
+function parallelSeg(join, joinNode, targets, scope, ipdom, ctx, refInto) {
+    const arms = targets.map((t, i) => armCb(`a${i}`, region(t, join, scope, ipdom, ctx, refInto)));
+    const seg = `.parallel(${tsLiteral(join)}, [\n${arms.map((a) => reindent(a, '  ')).join(',\n')},\n]${verArg(joinNode)})`;
+    return { seg, next: continueOn(joinNode, 'output', ctx, refInto) };
+}
 /** Re-indent every non-empty line of a (possibly multi-line) segment by `pad`. */
 function reindent(seg, pad) {
     return seg.split('\n').map((l) => (l === '' ? l : pad + l)).join('\n');
@@ -2385,8 +2464,8 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
         if (node.type === T.decision) {
             const r = ipdom.get(node.id) ?? stop;
             const cond = emitBareExpr(String((node.inputs ?? {}).expression ?? ''), ctx.imp, ctx.inputNames);
-            const thenSegs = edgeRegion(portEdge(ctx.graph, node.id, 'true'), r, scope, ipdom, ctx, refInto);
-            const elseSegs = edgeRegion(portEdge(ctx.graph, node.id, 'false'), r, scope, ipdom, ctx, refInto);
+            const thenSegs = forkRegion(portEdges(ctx.graph, node.id, 'true'), r, scope, ipdom, ctx, refInto);
+            const elseSegs = forkRegion(portEdges(ctx.graph, node.id, 'false'), r, scope, ipdom, ctx, refInto);
             const labels = armLabels(node);
             if (labels.trueLabel)
                 thenSegs.unshift(`.label(${tsLiteral(labels.trueLabel)})`);
@@ -2574,16 +2653,16 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
         }
         // Parallel: the fork's ipdom is the merge join; each successor is one arm.
         const join = ipdom.get(node.id);
-        if (join && join !== EXIT && ctx.graph.byId.get(join)?.type === T.merge) {
-            const arms = succ.map((t, i) => armCb(`a${i}`, region(follow(ctx.graph, node.id, t), join, scope, ipdom, ctx, refInto)));
-            segs.push(`.parallel(${tsLiteral(join)}, [\n${arms.map((a) => reindent(a, '  ')).join(',\n')},\n]${verArg(ctx.graph.byId.get(join))})`);
+        const joinNode = join !== undefined ? ctx.graph.byId.get(join) : undefined;
+        if (join && join !== EXIT && joinNode?.type === T.merge) {
+            const fork = parallelSeg(join, joinNode, succ.map((t) => follow(ctx.graph, node.id, t)), scope, ipdom, ctx, refInto);
+            segs.push(fork.seg);
             flagDropped(node, ctx, segs);
-            const next = continueOn(ctx.graph.byId.get(join), 'output', ctx, refInto);
-            if (next.brk || next.cont) {
-                segs.push(next.brk ? '.break()' : '.continue()');
+            if (fork.next.brk || fork.next.cont) {
+                segs.push(fork.next.brk ? '.break()' : '.continue()');
                 return segs;
             }
-            cursor = next.cursor;
+            cursor = fork.next.cursor;
             continue;
         }
         // Unstructured fan-out we can't fold — best-effort marker. Its successor
@@ -2803,7 +2882,7 @@ function emitSwitch(node, ipdom, scope, ctx, stop, refInto) {
                 }
             }
         }
-        const armSegs = edgeRegion(portEdge(ctx.graph, node.id, `case-${c.id}`), r, scope, ipdom, ctx, refInto);
+        const armSegs = forkRegion(portEdges(ctx.graph, node.id, `case-${c.id}`), r, scope, ipdom, ctx, refInto);
         const defaultLabel = `Case ${valueLiteral}`;
         const labelPart = c.label && c.label !== defaultLabel ? `, label: ${tsLiteral(c.label)}` : '';
         // The file's case id comes back when it is not the positional one serialize
@@ -2816,7 +2895,7 @@ function emitSwitch(node, ipdom, scope, ctx, stop, refInto) {
     const on = emitBareExpr(disc ?? '', ctx.imp, ctx.inputNames);
     const hasDefault = (node.inputs ?? {}).hasDefault === true || portEdge(ctx.graph, node.id, 'default') !== undefined;
     const defArm = hasDefault
-        ? `, ${armCb('d', edgeRegion(portEdge(ctx.graph, node.id, 'default'), r, scope, ipdom, ctx, refInto))}`
+        ? `, ${armCb('d', forkRegion(portEdges(ctx.graph, node.id, 'default'), r, scope, ipdom, ctx, refInto))}`
         : '';
     const caseList = `[\n${caseSrcs.map((c) => reindent(c, '  ')).join(',\n')},\n]`;
     // The builder's `.switch(on, [{value}])` models `on === value` only. A flow whose
@@ -3020,9 +3099,11 @@ function emitChildFlow(name, child, ctx) {
     // Body: the child's trigger is its own manual Start; walk from its successor.
     const trigger = (child.nodes ?? []).find((n) => isTrigger(n.type) && !(child.edges ?? []).some((e) => e.targetNodeId === n.id));
     const scope = scopeIds(child.nodes ?? [], undefined);
-    const entry = trigger ? follow(childCtx.graph, trigger.id, scopeSucc(childCtx.graph, trigger.id, scope)[0]) : undefined;
-    const ipdom = entry ? postDominators(entry, scope, childCtx.graph) : new Map();
-    const bodySegs = entry ? region(entry, EXIT, scope, ipdom, childCtx) : [];
+    const entries = trigger ? scopeSuccEdges(childCtx.graph, trigger.id, scope) : [];
+    const ipdom = entries.length
+        ? postDominators(entries.length > 1 ? trigger.id : entries[0].targetNodeId, scope, childCtx.graph)
+        : new Map();
+    const bodySegs = entries.length ? forkRegion(entries, EXIT, scope, ipdom, childCtx) : [];
     parts.push(...bodySegs);
     parts.push(...sweepDroppedEdges(childCtx.graph, new Set()));
     // A subflow carries its own scoped layout, resolved against its own node ids.
@@ -3144,9 +3225,13 @@ export function decompile(flow, options = {}) {
     const ctx = { graph, flow, imp, inputNames, o: options, emitted: new Set(), shared };
     const scope = scopeIds(flow.nodes ?? [], undefined);
     const startId = trigger?.id ?? 'start';
-    const first = follow(graph, startId, scopeSucc(graph, startId, scope)[0]);
-    const ipdom = first !== undefined ? postDominators(first, scope, graph) : new Map();
-    const bodySegs = first !== undefined ? region(first, EXIT, scope, ipdom, ctx) : [];
+    // Walked from the trigger's successors together: a `.parallel` placed first
+    // gives the trigger one edge per arm (#1155).
+    const firsts = scopeSuccEdges(graph, startId, scope);
+    const ipdom = firsts.length
+        ? postDominators(firsts.length > 1 ? startId : firsts[0].targetNodeId, scope, graph)
+        : new Map();
+    const bodySegs = firsts.length ? forkRegion(firsts, EXIT, scope, ipdom, ctx) : [];
     // Additional roots decompile to .entryPoint(...): scoped inputs from the
     // globals bound to them, and a prefix region that hands off into the shared
     // body — the shared nodes are in ctx.emitted by now, so the walk naturally
@@ -3236,8 +3321,11 @@ function entryPointSeg(t, scope, ipdom, ctx) {
         optParts.push(`inputs: { ${scoped.map((g) => `${key(g.name ?? g.id)}: ${declExpr(g, true, ctx.imp, sharedOf(g))}`).join(', ')} }`);
     }
     optParts.push(...triggerOptParts(t));
-    const first = follow(ctx.graph, t.id, scopeSucc(ctx.graph, t.id, scope)[0]);
-    const prefixSegs = first !== undefined ? region(first, EXIT, scope, ipdom, ctx) : [];
+    const firsts = scopeSuccEdges(ctx.graph, t.id, scope);
+    // A prefix that forks needs post-dominators over ITS nodes, which the root's
+    // map (computed from the default trigger) does not cover.
+    const epIpdom = firsts.length > 1 ? postDominators(t.id, scope, ctx.graph) : ipdom;
+    const prefixSegs = firsts.length ? forkRegion(firsts, EXIT, scope, epIpdom, ctx) : [];
     const optArgText = optParts.length ? `, { ${optParts.join(', ')} }` : (prefixSegs.length ? ', undefined' : '');
     const prefix = prefixSegs.length ? `, ${armCb('b', prefixSegs)}` : '';
     return `.entryPoint(${tsLiteral(t.id)}, ${factory}${optArgText}${prefix})`;

package/dist/flow-node-type.d.ts

@@ -92,7 +92,10 @@ export interface FlowDeserializeContext {
     plainValue(raw: unknown): unknown;
     /** The step name a node id was emitted for. */
     stepName(nodeId: string): string;
-    /** The file's own `definitions[]` entry for this node, if it carries one. */
+    /**
+     * The node's definition: the file's own `definitions[]` entry for it, else the
+     * SDK's bundled definition at the node's version; undefined when neither exists.
+     */
     definition(): unknown;
     /** Report something the lift could not keep. Decompile prints it once. */
     warn(message: string): void;
@@ -119,6 +122,11 @@ export interface FlowCheckContext {
     readonly step: string;
     /** The version the node will be emitted at. */
     readonly version: string;
+    /**
+     * The SDK's bundled definition of this step's node type at `version` (the one
+     * serialize emits from), or undefined when the SDK does not ship it.
+     */
+    definition(): unknown;
     /** Report a diagnostic on this step. Its severity is the family catalog's for `code`. */
     report(code: string, message: string, suggestion?: string): void;
     /**

package/dist/nodes/script/flow/check.js

@@ -2,8 +2,22 @@ export const SCRIPT_DIAGNOSTICS = {
     SCRIPT_RETURNS_UNKNOWN_TYPE: { severity: 'error', summary: '`returns` names a type the wire format does not know' },
     SCRIPT_EMPTY_RETURNS: { severity: 'warning', summary: '`returns: {}` names no fields' },
 };
-/** The type vocabulary a script's `returns` may name — what the wire format accepts. */
-const SCRIPT_RETURN_TYPES = new Set(['string', 'number', 'boolean', 'object', 'array']);
+/**
+ * The types a script's `returns` may name for a FIELD, and at the top level on
+ * every version. `any` is not one: no definition declares a field as `any`.
+ */
+const SCRIPT_FIELD_TYPES = new Set(['string', 'number', 'boolean', 'object', 'array']);
+/**
+ * The types a top-level `returns` may name at this step's version: the field
+ * types, plus the output type the node's own definition declares at that version
+ * (`any` on `core.action.script@1.1`, `object` on 1.0.0).
+ */
+function topLevelTypes(ctx) {
+    const declared = ctx.definition()
+        ?.outputDefinition?.output?.type;
+    return typeof declared === 'string' ? new Set([...SCRIPT_FIELD_TYPES, declared]) : SCRIPT_FIELD_TYPES;
+}
+const quoted = (types) => [...types].map((t) => `"${t}"`).join(', ');
 /**
  * A script step's `returns` — the author overriding what the body looks like.
  *
@@ -19,9 +33,10 @@ export function checkScript(inputs, ctx) {
     if (returns === undefined)
         return;
     if (typeof returns === 'string') {
-        if (!SCRIPT_RETURN_TYPES.has(returns)) {
+        const allowed = topLevelTypes(ctx);
+        if (!allowed.has(returns)) {
             ctx.report('SCRIPT_RETURNS_UNKNOWN_TYPE', `Script step "${step}" declares \`returns: ${JSON.stringify(returns)}\`, which is not a type the `
-                + `wire format knows. Use one of ${[...SCRIPT_RETURN_TYPES].map((t) => `"${t}"`).join(', ')}, or a `
+                + `wire format knows at ${ctx.version}. Use one of ${quoted(allowed)}, or a `
                 + `field map like \`{ total: "number" }\` to name an object's fields.`);
         }
         return;
@@ -41,9 +56,9 @@ export function checkScript(inputs, ctx) {
         return;
     }
     for (const [name, type] of Object.entries(fields)) {
-        if (typeof type !== 'string' || !SCRIPT_RETURN_TYPES.has(type)) {
+        if (typeof type !== 'string' || !SCRIPT_FIELD_TYPES.has(type)) {
             ctx.report('SCRIPT_RETURNS_UNKNOWN_TYPE', `Script step "${step}" declares field "${name}" as ${JSON.stringify(type)}, which is not a type the `
-                + `wire format knows. Use one of ${[...SCRIPT_RETURN_TYPES].map((t) => `"${t}"`).join(', ')}.`);
+                + `wire format knows for a field. Use one of ${quoted(SCRIPT_FIELD_TYPES)}.`);
         }
     }
 }

package/dist/nodes/script/flow/node-type.js

@@ -23,9 +23,13 @@ import { checkScript } from './check.js';
  */
 function scriptOutputs(base, returns, code) {
     const shape = returns !== undefined ? declaredScriptShape(returns) : inferScriptShape(code);
-    // Nothing knowable, or knowably the open object the definition already
-    // declares — leave the node exactly as it was.
-    if (!shape || (shape.type === 'object' && !shape.properties))
+    // Nothing knowable — leave the node exactly as it was. An INFERRED bare object
+    // is nothing knowable either: the inference never enumerates fields, so it
+    // only says "some object", and the definition's own declaration stands. A
+    // DECLARED type always lands, even `object`: the definition's default is
+    // version-dependent (`object` on script 1.0.0, `any` on 1.1), so "the same as
+    // the default" is not a property of the word `object`.
+    if (!shape || (returns === undefined && shape.type === 'object' && !shape.properties))
         return base;
     if (!base || typeof base !== 'object')
         return base;
@@ -46,7 +50,7 @@ function scriptOutputs(base, returns, code) {
  * the same way — a property map the body does not produce is one the author gave
  * as `returns: {…}`.
  */
-function liftReturns(node, code) {
+function liftReturns(node, code, definitionType) {
     const out = node.outputs?.output;
     const declared = typeof out?.type === 'string' ? out.type : undefined;
     if (!declared)
@@ -54,11 +58,14 @@ function liftReturns(node, code) {
     const props = out?.properties;
     // What re-compiling this body with NO `returns` would declare. Mirror
     // `scriptOutputs` exactly: an inference of a bare `object` (or none at all)
-    // leaves the definition's own `{type:'object'}` standing, untouched.
+    // leaves the definition's own output type standing, untouched. That type is
+    // the node's definition AT ITS VERSION (`definitionType`): `object` on script
+    // 1.0.0 but `any` on 1.1, so a 1.1 node's untouched `any` is the default, not
+    // an author override.
     const inferred = inferScriptShape(code);
     const effective = inferred && !(inferred.type === 'object' && !inferred.properties)
         ? inferred
-        : { type: 'object', properties: undefined };
+        : { type: definitionType, properties: undefined };
     const same = effective.type === declared
         && JSON.stringify(sortKeys(effective.properties ?? {})) === JSON.stringify(sortKeys(props ?? {}));
     if (same)
@@ -95,14 +102,16 @@ function scriptAt(version) {
                 ...(typed !== base ? { outputs: typed } : {}),
             };
         },
-        deserialize: (node) => {
+        deserialize: (node, ctx) => {
             const raw = node.inputs?.script;
             const code = typeof raw === 'string' ? raw : '';
             // `returns` is recovered only when the node's declared output is something
             // re-compiling the body would NOT produce on its own: serialize infers from
             // the body first, so a script whose type is already plain in its code
             // round-trips without it.
-            const returns = liftReturns(node, code);
+            const defType = ctx.definition()
+                ?.outputDefinition?.output?.type;
+            const returns = liftReturns(node, code, typeof defType === 'string' ? defType : 'object');
             return { kind: 'script', inputs: { code, ...(returns !== undefined ? { returns } : {}) } };
         },
         print: ({ inputs }, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.20.0",
+  "version": "6.20.2",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "30b9615751de65281973caeec9d688ad105fc925"
+  "gitref": "b82dedf06e578750e6cb85ed825d25cec1745b09"
 }