@uipath/maestro-builder-sdk 6.29.0 → 6.29.1

package/dist/core/definition-handles.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The source handles a node's definition declares, read against the node's own
+ * inputs — one reader for every layer that has to know which ports a node can
+ * leave on (`merge-roundtrip.ts`'s handle checks, `decompile`'s arm recovery for
+ * a node with no typed factory, and `.stepSwitch` over a `rawNode`).
+ *
+ * A definition lists its handles in `handleConfiguration[].handles[]`. A static
+ * handle is its `id`; a REPEATED one is a template expanded once per item of an
+ * input array:
+ *
+ * ```
+ * { id: 'case-{item.id}', type: 'source', repeat: 'inputs.criteria' }
+ * inputs.criteria = [{ id: 'returns' }, { id: 'billing' }]
+ * → case-returns, case-billing
+ * ```
+ *
+ * This is how `core.logic.agentic-switch` (one exit per choice, plus `default`)
+ * and `core.logic.switch` (one per case) declare their exits.
+ */
+type Def = {
+    readonly [k: string]: unknown;
+} | undefined;
+/**
+ * Every source handle `def` declares for a node with `inputs`, in declaration
+ * order, templates expanded. `undefined` when `def` has no
+ * `handleConfiguration`, or has a template this cannot expand (a `repeat` that
+ * is not an `inputs.` path), so a caller can tell "no handles" from "cannot
+ * know".
+ */
+export declare function expandSourceHandles(def: Def, inputs: unknown): string[] | undefined;
+/**
+ * The FORWARD exits a node's definition declares when it has more than one —
+ * every source handle except `error` and an agent's artifact handles, templates
+ * expanded. `undefined` for a definition with one forward exit or fewer, or one
+ * whose handles cannot be known: such a node has no fan-out to route.
+ */
+export declare function forwardFanOut(def: Def, inputs: unknown): string[] | undefined;
+export {};

package/dist/core/definition-handles.js

@@ -0,0 +1,74 @@
+/**
+ * The source handles a node's definition declares, read against the node's own
+ * inputs — one reader for every layer that has to know which ports a node can
+ * leave on (`merge-roundtrip.ts`'s handle checks, `decompile`'s arm recovery for
+ * a node with no typed factory, and `.stepSwitch` over a `rawNode`).
+ *
+ * A definition lists its handles in `handleConfiguration[].handles[]`. A static
+ * handle is its `id`; a REPEATED one is a template expanded once per item of an
+ * input array:
+ *
+ * ```
+ * { id: 'case-{item.id}', type: 'source', repeat: 'inputs.criteria' }
+ * inputs.criteria = [{ id: 'returns' }, { id: 'billing' }]
+ * → case-returns, case-billing
+ * ```
+ *
+ * This is how `core.logic.agentic-switch` (one exit per choice, plus `default`)
+ * and `core.logic.switch` (one per case) declare their exits.
+ */
+/**
+ * Every source handle `def` declares for a node with `inputs`, in declaration
+ * order, templates expanded. `undefined` when `def` has no
+ * `handleConfiguration`, or has a template this cannot expand (a `repeat` that
+ * is not an `inputs.` path), so a caller can tell "no handles" from "cannot
+ * know".
+ */
+export function expandSourceHandles(def, inputs) {
+    const groups = def?.handleConfiguration;
+    if (!Array.isArray(groups))
+        return undefined;
+    const out = [];
+    for (const g of groups) {
+        for (const h of (g?.handles ?? [])) {
+            if (h?.type !== 'source' || typeof h.id !== 'string')
+                continue;
+            const template = /\{item\.([A-Za-z0-9_]+)\}/.exec(h.id);
+            if (!template) {
+                if (!out.includes(h.id))
+                    out.push(h.id);
+                continue;
+            }
+            if (typeof h.repeat !== 'string' || !h.repeat.startsWith('inputs.'))
+                return undefined;
+            let items = inputs;
+            for (const seg of h.repeat.slice('inputs.'.length).split('.'))
+                items = items?.[seg];
+            for (const item of Array.isArray(items) ? items : []) {
+                const v = item?.[template[1]];
+                if (typeof v !== 'string' && typeof v !== 'number')
+                    continue;
+                const id = h.id.replace(template[0], String(v));
+                if (!out.includes(id))
+                    out.push(id);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Source handles that are not exits: `error` (routed by `.onError()`) and an
+ * agent's artifact handles, which attach its tools, context, escalations and
+ * memory rather than continue the flow.
+ */
+const NOT_FORWARD = new Set(['error', 'tool', 'context', 'escalation', 'memory']);
+/**
+ * The FORWARD exits a node's definition declares when it has more than one —
+ * every source handle except `error` and an agent's artifact handles, templates
+ * expanded. `undefined` for a definition with one forward exit or fewer, or one
+ * whose handles cannot be known: such a node has no fan-out to route.
+ */
+export function forwardFanOut(def, inputs) {
+    const handles = expandSourceHandles(def, inputs)?.filter((h) => !NOT_FORWARD.has(h));
+    return handles !== undefined && handles.length > 1 ? handles : undefined;
+}

package/dist/core/raw-node-exits.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The exits `.stepSwitch` routes over when its step is a `rawNode`: the
+ * manifest's forward source handles, `repeat` ones expanded over the node's
+ * inputs, each arm's `value` being its port. A `core.logic.agentic-switch`
+ * with choices `returns` and `billing` has `case-returns`, `case-billing` and
+ * `default`:
+ *
+ * ```ts
+ * .stepSwitch('route', rawNode({ nodeType: 'core.logic.agentic-switch', … }), [
+ *   { value: 'case-returns', body: (b) => b.step('returns', …) },
+ *   { value: 'case-billing', body: (b) => b.step('billing', …) },
+ *   { value: 'default', body: (b) => b.step('triage', …) },
+ * ])
+ * ```
+ *
+ * Internal, not package API: `raw-node.ts` (whose module the package
+ * re-exports) puts the answer on its node under this symbol, and
+ * `flow-step-exits.ts` reads it. `decompile` reads the same handles off the
+ * file's definition, so what it emits recompiles (#1141).
+ */
+import type { DeclaredExit } from './step-ports.js';
+/** The method a raw node answers its exits under. */
+export declare const RAW_NODE_EXITS: unique symbol;
+/**
+ * `action`'s exits when it is a raw node whose manifest declares more than one
+ * forward exit; `undefined` otherwise (then it has nothing to route).
+ */
+export declare function rawNodeExits(action: unknown): DeclaredExit[] | undefined;

package/dist/core/raw-node-exits.js

@@ -0,0 +1,10 @@
+/** The method a raw node answers its exits under. */
+export const RAW_NODE_EXITS = Symbol('rawNodeExits');
+/**
+ * `action`'s exits when it is a raw node whose manifest declares more than one
+ * forward exit; `undefined` otherwise (then it has nothing to route).
+ */
+export function rawNodeExits(action) {
+    const own = action?.[RAW_NODE_EXITS];
+    return typeof own === 'function' ? own.call(action) : undefined;
+}

package/dist/decompile.js

@@ -46,6 +46,7 @@ import { mapJsCode } from './core/js-code-spans.js';
 import { missingBindingLabels } from './core/binding-messages.js';
 import { prepareCommand } from './core/cli-spelling.js';
 import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
+import { forwardFanOut } from './core/definition-handles.js';
 import { STICKY_NOTE_TYPE } from './core/definitionless-node-types.js';
 import { eventFilterFromTreeLeaf } from './core/event-filters.js';
 import { sdkFormFieldType } from './core/form-field-type.js';
@@ -2534,7 +2535,9 @@ function declaredExitsOfNode(node) {
     // A registered type that declares exits answers from its own spec, lifted off
     // this node; one that declares none is not lifted at all (this runs per edge).
     const impl = registeredImpl(node);
-    if (!impl?.exits)
+    if (!impl)
+        return rawNodeExits(node);
+    if (!impl.exits)
         return undefined;
     const lifted = liftRegistered(node, impl);
     const exits = lifted && impl.exits(lifted.spec);
@@ -2542,6 +2545,34 @@ function declaredExitsOfNode(node) {
         return undefined;
     return exits.map((e) => ({ value: e.value, port: e.port }));
 }
+/**
+ * The exits of a node that decompiles to a `rawNode` (a type this SDK has no
+ * factory for, carried with the file's own definition): that definition's
+ * forward source handles, `repeat` ones expanded over the node's inputs, when it
+ * has more than one. `core.logic.agentic-switch` declares `case-{item.id}` over
+ * `inputs.criteria` plus `default`, so a node with choices `returns` and
+ * `billing` has the exits `case-returns`, `case-billing`, `default`. Each exit's
+ * value is its port, which is what `.stepSwitch` over a `rawNode` matches
+ * (`rawNodeExits` in raw-node.ts reads the same handles off the manifest).
+ *
+ * Without this, a fully wired multi-exit raw node had ONE exit to the walker:
+ * it emitted `.step(...)` with a TODO and dropped every arm (#1141).
+ *
+ * `undefined` for every node the decompiler names some other way (the walker's
+ * structural types, triggers, connectors, agents, published resources, IxP):
+ * their exits are not a raw node's, and an agent's artifact handles (`tool`,
+ * `context`, …) are not exits at all.
+ */
+function rawNodeExits(node) {
+    const type = String(node.type);
+    if (Object.values(T).includes(type) || isTrigger(type))
+        return undefined;
+    if (['uipath.connector.', 'uipath.core.', 'uipath.ixp.', 'uipath.agent.', 'uipath.conversational.']
+        .some((p) => type.startsWith(p)))
+        return undefined;
+    const def = runDefs.get(`${type}@${node.typeVersion}`) ?? runDefs.get(type);
+    return forwardFanOut(def, node.inputs)?.map((port) => ({ value: port, port }));
+}
 /**
  * Split a switch case expression into `<discriminant> === <literal>`, the only
  * form `.switch(on, [{ value }])` models. Returns `undefined` for any other

package/dist/flow-step-exits.js

@@ -8,6 +8,7 @@
 import { resolveVersion } from './core/nodes/versioned.js';
 import { declaredExits } from './core/step-ports.js';
 import { FLOW_NODE_TYPES } from './flow-node-registry.js';
+import { rawNodeExits } from './core/raw-node-exits.js';
 /**
  * The author-declared exits of a step's spec: a registered type's own `exits`,
  * at the version the step resolves to (its pin, else the type's choice; an
@@ -16,6 +17,10 @@ import { FLOW_NODE_TYPES } from './flow-node-registry.js';
  * here, so they agree on what a port means.
  */
 export function stepExits(spec, pinnedVersion) {
+    // A `rawNode` declares its exits through the manifest it carries (#1141).
+    const raw = rawNodeExits(spec);
+    if (raw !== undefined)
+        return raw;
     const entry = typeof spec?.kind === 'string' ? FLOW_NODE_TYPES.byKind(spec.kind, spec) : undefined;
     if (!entry)
         return declaredExits(spec, pinnedVersion);

package/dist/merge-roundtrip.js

@@ -50,6 +50,7 @@
  *   merged file still has it.
  */
 import { bindingIdentity } from './core/binding-identity.js';
+import { expandSourceHandles } from './core/definition-handles.js';
 import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
 /** A file's definitions, keyed `nodeType@version`. */
 function defsOf(f) {
@@ -279,32 +280,8 @@ export function roundTripFindings(original, baseline, merged) {
 }
 /** The source handles a node's definition declares, or `undefined` when they cannot be known. */
 function declaredSourceHandles(node, def) {
-    const groups = def?.handleConfiguration;
-    if (!Array.isArray(groups))
-        return undefined;
-    const out = new Set();
-    for (const g of groups) {
-        for (const h of (g?.handles ?? [])) {
-            if (h?.type !== 'source' || typeof h.id !== 'string')
-                continue;
-            const template = /\{item\.([A-Za-z0-9_]+)\}/.exec(h.id);
-            if (!template) {
-                out.add(h.id);
-                continue;
-            }
-            if (typeof h.repeat !== 'string' || !h.repeat.startsWith('inputs.'))
-                return undefined; // a template this check cannot expand
-            let items = node.inputs;
-            for (const seg of h.repeat.slice('inputs.'.length).split('.'))
-                items = items?.[seg];
-            for (const item of Array.isArray(items) ? items : []) {
-                const v = item?.[template[1]];
-                if (typeof v === 'string' || typeof v === 'number')
-                    out.add(h.id.replace(template[0], String(v)));
-            }
-        }
-    }
-    return out;
+    const handles = expandSourceHandles(def, node.inputs);
+    return handles === undefined ? undefined : new Set(handles);
 }
 /**
  * The handles a node derives from its own inputs, in order: a definition's

package/dist/raw-node.js

@@ -8,6 +8,8 @@
 import { FlowAction, } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { rawNodeInputProblem, rawNodeTypedFamilyWarning } from './raw-node-advice.js';
+import { forwardFanOut } from './core/definition-handles.js';
+import { RAW_NODE_EXITS } from './core/raw-node-exits.js';
 /**
  * Place a node this SDK has no factory for, carrying its definition verbatim
  * (`uipath.exotic.thing@2.1` and the manifest the platform served for it).
@@ -88,6 +90,11 @@ class RawNode extends FlowAction {
             out.push({ code: 'RAW_NODE_TYPED_FAMILY', severity: 'warning', message: typed });
         return out;
     }
+    /** Its exits, for `.stepSwitch` (core/raw-node-exits.ts). */
+    [RAW_NODE_EXITS]() {
+        const manifest = this.spec.manifest;
+        return forwardFanOut(manifest, this.spec.inputs ?? {})?.map((port) => ({ value: port, port }));
+    }
     contribute(context) {
         // compile does not run diagnostics(); refuse here too so the escape hatch
         // cannot emit an unconfigured connector node. (An input a registered node

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.29.0",
+  "version": "6.29.1",
   "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": "af71b0c21f732f056d19e802af1c987fd8528336"
+  "gitref": "5dee9e0ebdef1bca6c586f4802285a0f429ae432"
 }