@uipath/maestro-builder-sdk 5.4.1 → 6.0.1

package/dist/generators/prepare_connector.py

@@ -382,6 +382,12 @@ def main() -> None:
     # step that removes 4-7 tool calls per task: listing connections, filtering
     # them, and then hunting Orchestrator for a folder key that was on the
     # connection record all along.
+    # Whether the CALLER chose the connection, recorded before discovery
+    # overwrites `connection_id` with its own answer. An explicit choice is never
+    # second-guessed: the retry in `_write_resolutions` is for a connection this
+    # command picked, not for one the author named (flow-builder-sdk#744).
+    args._connection_pinned = bool(args.connection_id or args.connection)
+
     if not args.connection_id:
         try:
             found = _connections.discover_connection(args.key, args.connection)
@@ -1125,6 +1131,14 @@ def _write_resolutions(args, node_type: str) -> None:
                 args.key, specs[field], field, by, value,
                 args.connection_id, resolved_values,
             )
+        except _resolve.LookupExhausted as error:
+            # The collection was read to the END on this connection and the
+            # value is not in it. That is evidence about the CONNECTION, not
+            # only about the value — so before failing, try the other enabled
+            # connections for this connector. A transport failure is the
+            # sibling exception below and is never retried: retrying it would
+            # dress a broken call up as "no connection has it".
+            _retry_or_exit(args, node_type, specs, ordered, error)
         except _resolve.ResolutionError as error:
             sys.exit(f"prepare-connector: {error}")
         resolved_values[field] = got
@@ -1143,6 +1157,164 @@ def _write_resolutions(args, node_type: str) -> None:
     print(f"  wrote {len(existing)} resolution(s) to {path}")
 
 
+def _candidate_label(row: dict) -> str:
+    """`name (folder)` for a per-candidate report line."""
+    return f"{row.get('Name')} ({row.get('Folder')})"
+
+
+def _probe_candidate(args, specs, ordered, connection_id: str):
+    """Resolve every requested lookup against one connection.
+
+    Returns `None` when all of them resolve, or the first reason they did not:
+    `("exhausted", <LookupExhausted>)` or `("error", <ResolutionError>)`. The
+    two are kept apart all the way up, because only the first is evidence about
+    the connection.
+    """
+    resolved: dict[str, str] = {}
+    for field, by, value in ordered:
+        try:
+            resolved[field] = _resolve.resolve_one(
+                args.key, specs[field], field, by, value, connection_id, resolved,
+            )
+        except _resolve.LookupExhausted as error:
+            return ("exhausted", error)
+        except _resolve.ResolutionError as error:
+            return ("error", error)
+    return None
+
+
+def _retry_or_exit(args, node_type: str, specs, ordered, first) -> None:
+    """Try the other candidate connections, or exit explaining what was tried.
+
+    NEVER RETURNS. Either it re-execs this command pinned to a connection that
+    resolves everything, or it exits with a report.
+    """
+    if args._connection_pinned:
+        # An explicit --connection-id / --connection is the author's decision and
+        # is not overridden. The alternatives are still named, because the whole
+        # cost of this bug was not knowing they existed.
+        others = [
+            row for row in _connections.candidate_connections(args.key)
+            if str(row.get("Id")) != str(args.connection_id)
+        ]
+        extra = ""
+        if others:
+            extra = (
+                f"\n{len(others)} other enabled {args.key} connection"
+                f"{'s' if len(others) > 1 else ''} exist"
+                f"{'' if len(others) > 1 else 's'}:\n"
+                f"{_connections.candidate_listing(others)}\n"
+                "Re-run against one of those, or check the value. This run kept the "
+                "connection you named."
+            )
+        sys.exit(f"prepare-connector: {first}{extra}")
+
+    try:
+        candidates = _connections.candidate_connections(args.key, args.connection)
+    except _connections.ConnectionError_ as error:
+        # The listing itself failed; report the original lookup failure, which is
+        # the thing the author asked about.
+        sys.exit(f"prepare-connector: {first}\n(could not list other connections: {error})")
+
+    others = [row for row in candidates
+              if str(row.get("Id")) != str(args.connection_id)]
+    if not others:
+        sys.exit(
+            f"prepare-connector: {first}\n"
+            f"This is the only enabled {args.key} connection on the tenant, so the "
+            "value is what to check."
+        )
+
+    print(f"  {first.field}: not on this connection; trying "
+          f"{len(others)} other {args.key} connection(s)")
+    winners: list[dict] = []
+    report: list[str] = []
+    for row in others:
+        outcome = _probe_candidate(args, specs, ordered, str(row.get("Id")))
+        if outcome is None:
+            winners.append(row)
+            report.append(f"    {_candidate_label(row)}  resolves all "
+                          f"{len(ordered)} lookup(s)")
+            continue
+        kind, error = outcome
+        if kind == "exhausted":
+            report.append(
+                f"    {_candidate_label(row)}  {error.field}: "
+                f"{error.scanned} record(s) scanned, no match")
+        else:
+            report.append(f"    {_candidate_label(row)}  {error}")
+
+    if len(winners) == 1:
+        chosen = winners[0]
+        # Undo the bindings this run wrote for the connection that cannot serve
+        # the lookups, then start over pinned to the one that can. Re-running
+        # rather than switching in place is deliberate: the overlay and its
+        # lookup specs are described THROUGH a connection
+        # (`_lookup_specs_from_overlay`), so adopting a different connection
+        # after the describe would leave the overlay describing one connection
+        # while bindings.json names another.
+        _restore_bindings(args)
+        print(f"  connection: {_candidate_label(chosen)} resolves "
+              f"{first.field}; re-running against it "
+              f"(--connection-id {chosen.get('Id')})")
+        argv = [sys.executable, *sys.argv,
+                "--connection-id", str(chosen.get("Id"))]
+        # The ledger keys a resolution by [nodeType, field, by, value] and NOT by
+        # connection, so an id recorded against the connection just abandoned
+        # would be reused as "already resolved". Force the re-run to resolve
+        # against the connection it actually pins.
+        if not args.refresh_lookups:
+            argv.append("--refresh-lookups")
+        sys.stdout.flush()
+        try:
+            os.execv(sys.executable, argv)
+        except OSError as error:
+            # `execv` does not return on success, so reaching here means the
+            # re-run could not start. Hand back the command rather than a
+            # traceback: the author is one paste from the answer.
+            pinned = " ".join(argv[2:])
+            sys.exit(
+                f"prepare-connector: {first}\n"
+                f"{_candidate_label(chosen)} resolves it, but this command could "
+                f"not re-run itself ({error}). Run:\n  prepare {pinned}"
+            )
+        # Unreachable in production — execv replaced the process. Kept so the
+        # function can never fall through to the report below, which would
+        # contradict the line just printed.
+        raise SystemExit(0)
+
+    if len(winners) > 1:
+        sys.exit(
+            f"prepare-connector: {len(winners)} {args.key} connections resolve "
+            f"every requested lookup, and they are not interchangeable — the ids "
+            f"they return differ per connection. Pick the one you mean:\n"
+            f"{_connections.candidate_listing(winners)}"
+        )
+
+    # Nothing resolved anywhere. Report every candidate and what it held, the
+    # one connection first, so the reader can see the value really is absent
+    # rather than guess which connection was asked.
+    original = next(
+        (row for row in candidates
+         if str(row.get("Id")) == str(args.connection_id)),
+        {"Name": args.connection_id, "Folder": "?"},
+    )
+    lines = [f"    {_candidate_label(original)}  {first.field}: "
+             f"{first.scanned} record(s) scanned, no match", *report]
+    # HERE is where the collection listing finally belongs: every connection has
+    # been tried, so seeing what the collection actually holds is the next step
+    # rather than the detour it is while a retry is still available.
+    sys.exit(
+        f"prepare-connector: no {args.key} connection could resolve "
+        f"{first.field}: {first.by}={first.value!r}\n"
+        + "\n".join(lines) + "\n"
+        "Every candidate was read to the end, so the value is what to check now. "
+        f"To see what {first.collection!r} holds:\n"
+        f"  uip is resources run list {args.key} {first.collection} "
+        f"--connection-id {args.connection_id}"
+    )
+
+
 def _lookup_specs_from_overlay(
     out_dir: str, node_type: str, object_name: str | None = None,
 ) -> dict:

package/dist/serialize.js

@@ -14,6 +14,8 @@ import { Expr, toExpr, SCHEDULE_PRESETS, DELAY_PRESETS, parseIxpProjectType, fla
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { bindingSelfNameMessage } from './core/binding-messages.js';
+import { hitlRoutesPerOutcome } from './core/hitl-routing.js';
+import { declaredExits, hasExits } from './core/step-ports.js';
 import { buildConfiguration, transportHttpMethod } from './config.js';
 import { stableId } from './core/stable-id.js';
 import { readEventFilter, eventFilterProblem, eventFilterJmes, eventFilterTreeLeaf } from './event-filters.js';
@@ -38,6 +40,7 @@ function bodyUsesBreak(steps) {
     return steps.some((s) => s.kind === 'break'
         || (s.kind === 'branch' && (bodyUsesBreak(s.then) || bodyUsesBreak(s.otherwise)))
         || (s.kind === 'switch' && (s.cases.some((c) => bodyUsesBreak(c.body)) || (s.default ? bodyUsesBreak(s.default) : false)))
+        || (s.kind === 'stepSwitch' && s.cases.some((c) => bodyUsesBreak(c.body)))
         || (s.kind === 'parallel' && s.arms.some(bodyUsesBreak))
         || (s.kind === 'stepToList' && bodyUsesBreak(s.body)));
 }
@@ -3676,6 +3679,8 @@ function stepNamesOf(steps, out = []) {
             s.cases.forEach((c) => stepNamesOf(c.body, out));
             stepNamesOf(s.default ?? [], out);
         }
+        else if (s.kind === 'stepSwitch')
+            s.cases.forEach((c) => stepNamesOf(c.body, out));
         else if (s.kind === 'parallel')
             s.arms.forEach((a) => stepNamesOf(a, out));
         else if (s.kind === 'loop')
@@ -4982,18 +4987,24 @@ export function serialize(built, opts = {}) {
             const id = stepUid(scope, step.name);
             const hitlType = hitlNodeType(spec.inputs);
             // Rich options select a newer definition, same rule as the scheduled
-            // trigger's cron: `outcomePorts` needs 1.1 (per-outcome `outcome-<id>`
-            // exits) and `exposeError` needs 1.2 (adds the `error` output; its exits
-            // are the same per-outcome handles). Plain tasks stay on the pinned
-            // default, byte-identically.
-            const outcomeRouted = spec.inputs?.outcomePorts === true || spec.inputs?.exposeError === true;
+            // trigger's cron: per-outcome routing needs 1.1 (per-outcome
+            // `outcome-<id>` exits) and `exposeError` needs 1.2 (adds the `error`
+            // output; its exits are the same per-outcome handles). A zero- or
+            // one-outcome task stays on the pinned default, byte-identically.
+            //
+            // More than one outcome INFERS the routing — see `hitlRoutesPerOutcome`
+            // for the four things that turn that off, one of which is an explicit
+            // `{ version }`, which is what keeps decompile→compile exact.
+            const pinned = step.options?.version;
+            const outcomeRouted = hitlRoutesPerOutcome(spec.inputs, pinned);
             const neededVersion = spec.inputs?.exposeError ? '1.2' : outcomeRouted ? '1.1' : undefined;
             if (neededVersion !== undefined && hitlType !== NODE_TYPE.hitl) {
                 throw new Error(`"${step.name}": outcomePorts/exposeError need the base human task's ${neededVersion} `
                     + `definition — the '${spec.inputs?.variant}' variant has no per-outcome version. `
                     + `Drop the variant, or route on out('${step.name}', 'Action') downstream.`);
             }
-            const pinned = step.options?.version;
+            // Both refusals below can only be reached by an EXPLICIT flag: the
+            // inference already declines on a variant and on a pinned version.
             if (neededVersion !== undefined && pinned !== undefined && pinned !== neededVersion) {
                 throw new Error(`"${step.name}": ${spec.inputs?.exposeError ? 'exposeError' : 'outcomePorts'} needs the task's ${neededVersion} `
                     + `definition, but { version: '${pinned}' } pins it. Drop the pin or match it.`);
@@ -5307,6 +5318,72 @@ export function serialize(built, opts = {}) {
             else if (step.kind === 'stepToList') {
                 tails = emitPortList(step, lastAction ?? '?', tails, scope, parentId, breakTarget);
             }
+            else if (step.kind === 'stepSwitch') {
+                // The action, then EVERY exit it declares as an arm — no tacit tail.
+                //
+                // The exits are resolved BEFORE the node is emitted, because a spec with
+                // no routable fan-out (a human task pinned to 1.0, a variant, an http
+                // with no branches) must refuse rather than emit a node and then
+                // discover it has one port. `declaredExits` carries the reason.
+                const exits = declaredExits(step.spec, step.options?.version);
+                if (!hasExits(exits)) {
+                    throw new Error(`.stepSwitch("${step.name}"): ${exits.reason}, so there are no exits to route.`
+                        + (exits.suggestion ? ` ${exits.suggestion}` : ''));
+                }
+                const action = {
+                    kind: 'action', name: step.name, spec: step.spec,
+                    ...(step.options ? { options: step.options } : {}),
+                };
+                // The tail `emitAction` hands back is the family's tacit exit — the
+                // primary outcome, http's `default`. Discarded on purpose: every exit is
+                // an arm here, so that port is wired by the arm that names it (and
+                // wiring both is flow-builder-sdk#741).
+                emitAction(action, tails, scope, parentId);
+                applyUpdates(action);
+                applyLabel(action);
+                const nodeId = scope.stepNodeId.get(step.name);
+                if (!nodeId)
+                    throw new Error(`.stepSwitch("${step.name}"): emitted node not found.`);
+                const armTails = [];
+                const routed = new Set();
+                for (const c of step.cases) {
+                    const exit = exits.find((e) => e.value === c.value);
+                    if (!exit) {
+                        throw new Error(`.stepSwitch("${step.name}"): no exit named ${JSON.stringify(c.value)}. `
+                            + `It declares ${exits.map((e) => JSON.stringify(e.value)).join(', ')}.`);
+                    }
+                    routed.add(exit.port);
+                    // Arms CONVERGE, exactly as `.switch()`'s do: every arm that does not
+                    // end in `.return()` contributes its tail, so the next step fans in
+                    // from all of them. (`.stepToList` instead gives each arm a private
+                    // End, which silently drops the flow's outputs on that path —
+                    // flow-builder-sdk#742.)
+                    armTails.push(...emit(c.body, [{ node: nodeId, port: exit.port }], scope, parentId, breakTarget));
+                }
+                // A declared exit with no arm gets an End, so the run FINISHES there
+                // rather than reaching a port with no edge and stalling. `check` warns
+                // (STEP_SWITCH_EXIT_UNROUTED) — this is the compile-side half of it.
+                //
+                // `action: 'End'` outcomes get one TOO, and that is deliberate: the
+                // designer draws a handle for every entry in `inputs.schema.outcomes`
+                // whatever its action, so skipping them left a drawn handle wired to
+                // nothing. UiPath/skills' own gate says the same and is stricter than
+                // this was — `assert_outcome_wiring` requires an edge per outcome with
+                // no exemption, and its convention makes every non-primary outcome an
+                // `End`. What the action changes is the WARNING, not the edge: nobody
+                // needs to be told to write an arm for an outcome that ends the run.
+                for (const e of exits) {
+                    if (routed.has(e.port))
+                        continue;
+                    const endId = uid(scope, `${step.name}${e.port.charAt(0).toUpperCase()}${e.port.slice(1)}End`);
+                    const end = makeNode(NODE_TYPE.end, endId, 'End', parentId ? { parentId } : {});
+                    end.inputs = {};
+                    scope.nodes.push(end);
+                    addEdge(scope, { node: nodeId, port: e.port }, endId);
+                }
+                tails = armTails;
+                lastAction = step.name;
+            }
             else if (step.kind === 'branch') {
                 const id = stepUid(scope, step.name);
                 const node = makeNode(NODE_TYPE.decision, id, step.options?.label ?? step.label ?? step.name, { parentId, requestedVersion: step.options?.version });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "5.4.1",
+  "version": "6.0.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "b5437630666554168202df6a5fbfe43ee72c43d0"
+  "gitref": "21bfc3d02150e62bfca808d6dfdbf8b4c320870f"
 }