@uipath/maestro-builder-sdk 6.0.0 → 6.0.1

package/dist/generators/_connections.py

@@ -30,6 +30,8 @@ __all__ = [
     "ConnectionError_",
     "byoa_connections",
     "byoa_listing",
+    "candidate_connections",
+    "candidate_listing",
     "discover_connection",
     "lookup_connection",
     "merge_bindings",
@@ -130,6 +132,48 @@ def discover_connection(connector_key: str, name: str | None = None) -> dict:
     return rows[0]
 
 
+def candidate_connections(connector_key: str, name: str | None = None) -> list[dict]:
+    """Every enabled connection for `connector_key`, own folder FIRST.
+
+    `discover_connection` answers "which one" and stops at the first non-empty
+    scope, which is right for picking a connection and wrong for retrying one:
+    when the own-folder listing holds exactly one, the tenant-wide connections
+    are never even looked at. So a lookup that exhausts the personal-workspace
+    connection reports a bad VALUE while the record sits in another folder's
+    connection (flow-builder-sdk#744, measured on two Jira connections where
+    only the second carried project `TS`).
+
+    Ordering is the same preference `discover_connection` encodes — the caller's
+    own folder is the likeliest and is tried first — but nothing is dropped.
+    Deduplicated by `Id`, because the tenant-wide listing repeats the own-folder
+    rows.
+
+    This does NOT decide anything, and in particular does not raise on several
+    matches: choosing among them is the caller's job, and the only honest way to
+    choose is evidence (a lookup that resolves on exactly one). That keeps this
+    module's rule intact — ambiguity is never resolved by guessing.
+    """
+    ordered: list[dict] = []
+    seen: set[str] = set()
+    for all_folders in (False, True):
+        for row in _matching(_list(all_folders=all_folders), connector_key, name):
+            identifier = str(row.get("Id", ""))
+            if identifier and identifier in seen:
+                continue
+            seen.add(identifier)
+            ordered.append(row)
+    return ordered
+
+
+def candidate_listing(rows: list[dict], indent: str = "    ") -> str:
+    """The candidates, one pasteable `--connection-id` line each."""
+    return "\n".join(
+        f"{indent}{row.get('Name')}  --connection-id {row.get('Id')}"
+        f"  (folder: {row.get('Folder')})"
+        for row in rows
+    )
+
+
 def _enabled_listing(rows: list[dict], connector_key: str) -> str:
     """The enabled connections for `connector_key`, one per line, pasteable."""
     enabled = _matching(rows, connector_key, None)

package/dist/generators/_resolve.py

@@ -25,6 +25,7 @@ import subprocess
 import sys
 
 __all__ = [
+    "LookupExhausted",
     "ResolutionError",
     "parse_resolve_flag",
     "resolve_one",
@@ -55,6 +56,36 @@ class ResolutionError(Exception):
     """A lookup that could not be resolved, with the reason a human needs."""
 
 
+class LookupExhausted(ResolutionError):
+    """The collection was read to the end on THIS connection and had no match.
+
+    Split out from its parent because the two failures want opposite responses
+    and the caller cannot tell them apart from a message. A transport or
+    permission failure says nothing about whether the value exists — retrying it
+    on another connection would hide a broken call behind a confident "no
+    connection has it". An exhaustive miss is positive evidence about this
+    connection specifically, and is the signal `prepare` uses to demote it and
+    try the next candidate (flow-builder-sdk#744).
+
+    `capped` flips that: a scan stopped at the record cap did NOT reach the end,
+    so it is not evidence of absence and must not demote anything.
+
+    The attributes carry the counts so a caller can report per-candidate results
+    without re-parsing the sentence.
+    """
+
+    def __init__(self, message: str, *, field: str, collection: str, by: str,
+                 value: str, scanned: int, pages: int, capped: bool) -> None:
+        super().__init__(message)
+        self.field = field
+        self.collection = collection
+        self.by = by
+        self.value = value
+        self.scanned = scanned
+        self.pages = pages
+        self.capped = capped
+
+
 def parse_resolve_flag(raw: str) -> tuple[str, str, str]:
     """`channel:profile.email=dustin@example.com` -> (field, by, value).
 
@@ -261,13 +292,28 @@ def resolve_one(
         query = f"{query}&nextPage={token}" if query else f"nextPage={token}"
 
     capped = scanned >= MAX_SCANNED or pages > PAGE_GUARD
-    raise ResolutionError(
+    # This states the FACT and stops; `prepare` owns the remedy, because
+    # `prepare` is what knows the other candidate connections.
+    #
+    # It deliberately carries NO "check the value" and NO `uip is resources`
+    # pointer. The old text led with both: it named only the value as suspect
+    # when the connection is equally suspect, and then sent the reader to a
+    # tenant crawl the skill explicitly rules out ("Tenant discovery is not a
+    # phase of either loop", references/CLI-LOOP.md). An agent followed that
+    # advice into exactly what it had been told not to do — 50 of 94 Bash calls
+    # hand-crawling Integration Service, 41 of them paging this collection, and
+    # the run hit its ceiling without producing a flow (flow-builder-sdk#744).
+    #
+    # The listing command is still offered, once, by the caller's terminal
+    # report — where every connection has been tried and seeing what IS there
+    # is finally the next step rather than a detour.
+    raise LookupExhausted(
         f"{field}: no record in {collection!r} has {by}={value!r} "
         f"(scanned {scanned} record(s) across {pages + 1} page(s)"
         + (f"; STOPPED AT THE {MAX_SCANNED}-record cap, so the value may be "
-           f"further in" if capped else "")
-        + ").\n"
-        f"Check the value, or list the collection to see what is there:\n"
-        f"  uip is resources run list {connector_key} {collection} "
-        f"--connection-id {connection_id}"
+           f"further in" if capped
+           else "; collection exhausted")
+        + f") on connection {connection_id}.",
+        field=field, collection=collection, by=by, value=value,
+        scanned=scanned, pages=pages + 1, capped=capped,
     )

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.0.0",
+  "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": "8c327b39940d34432128dd713c731027bb00fbde"
+  "gitref": "21bfc3d02150e62bfca808d6dfdbf8b4c320870f"
 }