@uipath/maestro-builder-sdk 5.2.0

package/dist/generators/_objects.py

@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""Match the object a Generic connector action addresses, deterministically.
+
+`prepare --object Company__C` used to mean EXACTLY `Company__C`: the catalog is
+matched by equality, the user's casing is not the API's, and the failure was a
+dead end — "object was not found" with no candidates, against a catalog the
+command had just fetched. The author's recovery was the hand-written JMESPath
+recipe this module exists to retire.
+
+THE LADDER, strictest first, stopping at the first rung with EXACTLY one hit:
+
+  1. exact `Name`;
+  2. case-insensitive `Name`;
+  3. case-insensitive `DisplayName`.
+
+A unique case-insensitive match proceeds LOUDLY (the caller prints the
+normalization) — casing is presentation, so those rungs cannot pick a thing
+the author did not name. SUBSTRING MATCHING NEVER PROCEEDS, unique or not:
+"unique among what exists" is not "unique among what the author meant", and
+the two diverge exactly when it hurts — `--object Company` on a tenant whose
+only Create-capable hit is `DandBCompany` would silently prepare an object the
+author never named, and the same source line would prepare DIFFERENT objects
+on different tenants. So substring hits are how the REFUSAL finds its
+candidates, nothing more; a single candidate costs one confirm-and-re-run
+turn, which is the cheapest insurance in this file.
+
+Several matches refuse with the candidate table — a wrong field value is one
+wrong input, a wrong object is a wrong flow, so nothing here ever picks first.
+Zero matches on a multi-word input refuse with the candidates of the most
+selective word, because qualifier words are facets, not name material: "custom
+company" contains-matches nothing as a phrase, "custom" alone matches 26
+unrelated objects on a real Salesforce org, and "company" alone matches the 5
+rows the author actually has to choose between (measured, 2026-09-02).
+
+Candidates are narrowed to objects whose `Operations` include this action's
+verb before any matching: an object that cannot Create is never the right
+answer for insert-record, and showing it only lengthens the table.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+__all__ = [
+    "ObjectMatchError",
+    "LedgerError",
+    "match_object",
+    "format_candidates",
+    "read_ledger",
+    "record_object_resolution",
+]
+
+# Enough rows to choose from without dumping a catalog into the error. The
+# most-selective-token fallback can legitimately produce dozens of rows; past
+# this many the table stops being a choice and starts being the unfiltered
+# list the ladder exists to avoid.
+MAX_CANDIDATES = 15
+
+
+class ObjectMatchError(Exception):
+    """No unique object for the requested name, with the candidates a human
+    (or an agent with the prompt in hand) needs to choose.
+
+    `retriable` marks every outcome that fell PAST the name rungs — zero
+    matches, and the substring refusals (unique or ambiguous). All of them can
+    be caused by a stale `uip is resources list` cache hiding a real object:
+    `--object User` on a catalog that lacks `User` but carries `UserAlias`
+    would otherwise refuse with a recovery message pointing at the WRONG
+    object, and the cache never invalidates itself. The caller refreshes the
+    catalog once and re-runs the whole ladder before believing any of them.
+    Ambiguity WITHIN a name rung (two objects whose names are case-variants)
+    is not retriable — a fresh catalog has the same two names in it.
+    """
+
+    def __init__(self, message: str, retriable: bool = False):
+        super().__init__(message)
+        self.retriable = retriable
+
+
+def _name(row: dict) -> str:
+    return str(row.get("Name") or "")
+
+
+def _display(row: dict) -> str:
+    return str(row.get("DisplayName") or "")
+
+
+def _supports(row: dict, verb: str | None) -> bool:
+    if not verb:
+        return True
+    operations = row.get("Operations")
+    if not isinstance(operations, list):
+        # A catalog that does not report operations cannot be narrowed by one;
+        # keep the row rather than hiding it on missing data.
+        return True
+    return verb in operations
+
+
+def format_candidates(rows: list[dict]) -> str:
+    """The table an ambiguous match prints: enough columns to choose with.
+
+    `Custom: yes` is how a prompt's "custom" qualifier resolves — it is a facet
+    column here precisely so nothing upstream has to parse it out of English.
+    """
+    shown = rows[:MAX_CANDIDATES]
+    name_w = max([len("Name"), *(len(_name(r)) for r in shown)])
+    disp_w = max([len("DisplayName"), *(len(_display(r)) for r in shown)])
+    lines = [
+        f"  {'Name'.ljust(name_w)}  {'DisplayName'.ljust(disp_w)}  Custom  Operations",
+    ]
+    for row in shown:
+        operations = row.get("Operations")
+        ops = ",".join(operations) if isinstance(operations, list) else "?"
+        lines.append(
+            f"  {_name(row).ljust(name_w)}  {_display(row).ljust(disp_w)}  "
+            f"{str(row.get('Custom') or '?').ljust(6)}  {ops}"
+        )
+    if len(rows) > MAX_CANDIDATES:
+        lines.append(f"  … and {len(rows) - MAX_CANDIDATES} more")
+    return "\n".join(lines)
+
+
+def _contains(rows: list[dict], needle: str) -> list[dict]:
+    lowered = needle.lower()
+    return [
+        row for row in rows
+        if lowered in _name(row).lower() or lowered in _display(row).lower()
+    ]
+
+
+def match_object(
+    rows: list[dict], wanted: str, verb: str | None = None,
+) -> tuple[dict, str | None]:
+    """The catalog row for `wanted`, or raise `ObjectMatchError`.
+
+    Returns `(row, note)`: `note` is None on an exact match and the
+    normalization sentence otherwise, so the caller can print how the given
+    name became the API name.
+    """
+    wanted = (wanted or "").strip()
+    if not wanted:
+        raise ObjectMatchError("--object needs a name to match.")
+    pool = [row for row in rows if _supports(row, verb)]
+
+    exact = [row for row in pool if _name(row) == wanted]
+    if len(exact) == 1:
+        return exact[0], None
+
+    lowered = wanted.lower()
+    for rung, key in (("name", _name), ("display name", _display)):
+        hits = [row for row in pool if key(row).lower() == lowered]
+        if len(hits) == 1:
+            return hits[0], f'matched "{wanted}" -> {_name(hits[0])} (by {rung})'
+        if len(hits) > 1:
+            raise ObjectMatchError(_ambiguous(wanted, hits, verb))
+
+    # Substring hits only ever feed the refusal. A unique one is still a guess
+    # — the pool it is unique within is tenant state, not the author's intent —
+    # so it is offered back as the one candidate to confirm, never taken.
+    # Everything from here down is `retriable`: a stale catalog can hide the
+    # real object the author named, and these refusals would then recover
+    # toward the wrong one.
+    hits = _contains(pool, wanted)
+    if len(hits) == 1:
+        raise ObjectMatchError(
+            f'no object is NAMED "{wanted}"'
+            + (f" (of those that support {verb})" if verb else "")
+            + f'. One object contains it — if {_name(hits[0])!r} is the one '
+            "the task means, re-run with --object "
+            f"{_name(hits[0])}:\n" + format_candidates(hits),
+            retriable=True,
+        )
+    if len(hits) > 1:
+        raise ObjectMatchError(_ambiguous(wanted, hits, verb), retriable=True)
+
+    # Nothing contains the whole input. A multi-word input usually mixes name
+    # material with qualifiers; the most selective word's candidates are the
+    # smallest non-empty table the author can actually choose from.
+    tokens = [t for t in wanted.split() if t]
+    if len(tokens) > 1:
+        per_token = [(t, _contains(pool, t)) for t in tokens]
+        nonempty = [(t, h) for t, h in per_token if h]
+        if nonempty:
+            token, hits = min(nonempty, key=lambda pair: len(pair[1]))
+            raise ObjectMatchError(
+                f'no object matches "{wanted}" as one name'
+                + (f" (of those that support {verb})" if verb else "")
+                + f'. Its word "{token}" matches {len(hits)}'
+                + " — qualifiers like \"custom\" are the Custom column below,"
+                " not part of the name. Pick one and re-run with"
+                " --object <Name>:\n" + format_candidates(hits),
+                retriable=True,
+            )
+
+    raise ObjectMatchError(
+        f'no object in the connected catalog matches "{wanted}"'
+        + (f" and supports {verb}" if verb else "")
+        + f" ({len(pool)} object(s) searched by name, display name and"
+        " substring). Check the value against the words the task used,"
+        " or list the catalog to see what is there.",
+        retriable=True,
+    )
+
+
+def _ambiguous(wanted: str, hits: list[dict], verb: str | None) -> str:
+    return (
+        f'"{wanted}" matches {len(hits)} objects'
+        + (f" that support {verb}" if verb else "")
+        + ". Nothing here picks one for you: a wrong object is a wrong flow."
+        " Pick by the task's wording (Custom: yes marks a tenant-only object),"
+        " or present these and let the user choose, then re-run with"
+        " --object <Name>:\n" + format_candidates(hits)
+    )
+
+
+class LedgerError(Exception):
+    """The ledger file exists but cannot be read back — refuse, don't clobber."""
+
+
+def read_ledger(out_dir: str) -> dict:
+    """The whole `resolutions.json` ledger, or raise {@link LedgerError}.
+
+    A file that will not parse is REFUSED rather than silently reset to `{}` —
+    the same rule `bindings.json` follows: a corrupt-but-recoverable audit of
+    every resolution prepare ever made is worth more than this run finishing,
+    and overwriting it is the one way to make the corruption permanent.
+    """
+    path = os.path.join(out_dir, "resolutions.json")
+    if not os.path.exists(path):
+        return {}
+    try:
+        with open(path, encoding="utf-8") as handle:
+            ledger = json.load(handle)
+    except (OSError, ValueError) as error:
+        raise LedgerError(
+            f"{path} exists but cannot be read back ({error}); refusing to "
+            "overwrite it. Fix or remove the file and re-run."
+        ) from error
+    if not isinstance(ledger, dict):
+        # Parseable-but-not-a-dict (a top-level array, a bare string) is
+        # corruption wearing valid JSON; sliding it past the refusal above
+        # would overwrite whatever it used to be.
+        raise LedgerError(
+            f"{path} exists but is not a JSON object "
+            f"(found {type(ledger).__name__}); refusing to overwrite it. "
+            "Fix or remove the file and re-run."
+        )
+    return ledger
+
+
+def record_object_resolution(
+    out_dir: str, node_type: str, requested: str, row: dict, verb: str | None,
+) -> str:
+    """Record the match in the overlay ledger, as the FIRST resolution.
+
+    The run artifact (`bindings.json` + `resolutions.json`) is a complete,
+    diffable audit of everything prepare decided — except this decision, which
+    lived only in stdout. The row lands in a sibling `objects` section rather
+    than in `resolutions`: an object identity is not a field lookup, and it
+    should not wear a fake `field` key. Keys NEST (`objects[nodeType][given]`)
+    rather than encode a tuple: the lookup rows' tuple-string keys exist to
+    match a JavaScript `JSON.stringify` that reads them back, and nothing in
+    JavaScript reads this section — a hand-maintained "matches JSON.stringify"
+    encoding with no reader on the other side is exactly how the #660
+    resolution-key bug happened.
+
+    Unlike lookup rows, the current match is ALWAYS written, `--refresh` or
+    not. A lookup row stands because re-resolving costs a network call and can
+    silently change an artifact; this row costs nothing to recompute and MUST
+    agree with the overlay written beside it in this same run — an old row
+    kept "for stability" would describe a schema this run just replaced.
+    The ledger records the DECISION only; the schema it selected lives in the
+    overlay, never duplicated here.
+
+    The file's sections are additive under `schemaVersion: "1"`: readers
+    ignore keys they do not know (the JS resolutions loader reads only
+    `.resolutions`), and any change to the MEANING of an existing section
+    bumps the version.
+    """
+    ledger = read_ledger(out_dir)
+    objects = ledger.get("objects") or {}
+    per_type = objects.get(node_type) or {}
+    per_type[requested] = {
+        "value": _name(row),
+        "displayName": _display(row),
+        "custom": str(row.get("Custom") or "").strip().lower() in ("yes", "true", "1"),
+        **({"operation": verb} if verb else {}),
+    }
+    objects[node_type] = per_type
+    ledger["objects"] = objects
+    ledger["resolutions"] = ledger.get("resolutions") or {}
+    ledger["schemaVersion"] = "1"
+    os.makedirs(out_dir, exist_ok=True)
+    path = os.path.join(out_dir, "resolutions.json")
+    with open(path, "w", encoding="utf-8") as handle:
+        json.dump(ledger, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+    return path

package/dist/generators/_resolve.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""Resolve a connector lookup field against a live connection.
+
+`prepare --resolve channel:profile.email=dustin@example.com` turns a
+human-meaningful value into the opaque id the connector wants, and records the
+answer so `compile` can read it offline. This module is the retrieval half.
+
+WHY IT LIVES HERE AND NOT IN COMPILE. Resolution needs the network; compile must
+not have it. The eval harness runs `check` and `compile` with no `uip` login,
+and the byte-lock gates require that the same source produces the same bytes —
+a compile that made live calls would make those gates depend on tenant state and
+they would stop meaning anything. So the expensive call happens once, in an
+explicit command, and its result lands in a file that is diffable and reviewable.
+
+THE STRATEGY IS DATA, NOT CODE. `reference` says how to retrieve the collection:
+a `filterPattern` means one request; its absence means paging; `childPath` means
+a tree; `dependsOn` means another field must resolve first. That is why this is a
+generator reading metadata rather than 103 hand-written connector helpers.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+
+__all__ = [
+    "ResolutionError",
+    "parse_resolve_flag",
+    "resolve_one",
+    "order_resolutions",
+]
+
+# A scan has to stop somewhere, and the caps must be set against the MEASURED
+# page size rather than a guess. Integration Service serves **1,000 records per
+# page** for a curated collection (verified against a live Slack connection:
+# `curated_channels` returns 1000 with `HasMore: "true"`).
+#
+# The first version of this capped at 400 records — a number chosen for how many
+# rows a person might scroll, which is the wrong unit entirely. It meant the loop
+# broke partway through page ONE and never paginated at all. The eval task built
+# to exercise this puts its target channel on page 3 (record ~2,001), so the
+# resolver reported "not found" for a channel that is plainly there, and the
+# agent fell back to hand-rolling the paging this exists to do for it.
+#
+# 25 pages is ~30s of requests in the worst case, spent once, in an explicit
+# command whose whole job is this. A collection with a `filterPattern` never
+# reaches the scan at all.
+PAGE_SIZE_HINT = 1000
+MAX_SCANNED = 25 * PAGE_SIZE_HINT
+PAGE_GUARD = 50
+
+
+class ResolutionError(Exception):
+    """A lookup that could not be resolved, with the reason a human needs."""
+
+
+def parse_resolve_flag(raw: str) -> tuple[str, str, str]:
+    """`channel:profile.email=dustin@example.com` -> (field, by, value).
+
+    Split on the FIRST colon and the FIRST `=`. Both halves can legitimately
+    contain the other delimiter — `by` is a dotted path and a value can be
+    anything a person typed — so a greedy split silently mis-parses real input.
+    """
+    field, sep, rest = raw.partition(":")
+    if not sep or not field:
+        raise ResolutionError(
+            f"--resolve {raw!r}: expected <field>:<by>=<value>, "
+            "e.g. --resolve channel:profile.email=someone@example.com"
+        )
+    by, sep, value = rest.partition("=")
+    if not sep or not by:
+        raise ResolutionError(
+            f"--resolve {raw!r}: expected <field>:<by>=<value>, "
+            f"but found no '=' after the search field {by or rest!r}."
+        )
+    return field, by, value
+
+
+def order_resolutions(
+    requested: list[tuple[str, str, str]], specs: dict,
+) -> list[tuple[str, str, str]]:
+    """Order the requests so a `dependsOn` prerequisite resolves first.
+
+    27 fields in the shipped library are not addressable until another field is
+    known — Jira's issue type needs the project, Amazon Connect's phone number
+    needs the instance. Resolving in the order the flags were typed leaves an
+    unsubstituted `{placeholder}` in a URL, and the error the connector returns
+    for that names neither field.
+    """
+    by_field = {field: (field, by, value) for field, by, value in requested}
+    ordered: list[tuple[str, str, str]] = []
+    placed: set[str] = set()
+
+    def place(field: str, trail: tuple[str, ...] = ()) -> None:
+        if field in placed:
+            return
+        if field in trail:
+            cycle = " -> ".join([*trail, field])
+            raise ResolutionError(f"circular dependsOn among lookup fields: {cycle}")
+        for prerequisite in (specs.get(field, {}).get("dependsOn") or []):
+            if prerequisite in by_field:
+                place(prerequisite, (*trail, field))
+            else:
+                raise ResolutionError(
+                    f"cannot resolve {field!r}: its collection is addressed through "
+                    f"{prerequisite!r}, which has no --resolve of its own. Add "
+                    f"--resolve {prerequisite}:<by>=<value> and re-run."
+                )
+        placed.add(field)
+        ordered.append(by_field[field])
+
+    for field, _by, _value in requested:
+        place(field)
+    return ordered
+
+
+def _envelope_items(payload: dict) -> list:
+    """The records out of a `uip is resources run list` reply.
+
+    The reply is `{"Result": "Success", "Code": ..., "Data": {"items": [...],
+    "Pagination": {...}}}` — records live under `Data`, and `Result` is the
+    STATUS STRING, not a container. Reading a top-level `items` finds nothing
+    and reports "scanned 0 records" against a collection that is full, which is
+    exactly what this did until an eval run walked it into the real CLI.
+    """
+    data = payload.get("Data")
+    if isinstance(data, dict) and isinstance(data.get("items"), list):
+        return data["items"]
+    if isinstance(payload.get("items"), list):
+        return payload["items"]
+    return []
+
+
+def _envelope_pagination(payload: dict) -> dict:
+    """The `Pagination` block, from under `Data`."""
+    data = payload.get("Data")
+    if isinstance(data, dict) and isinstance(data.get("Pagination"), dict):
+        return data["Pagination"]
+    if isinstance(payload.get("Pagination"), dict):
+        return payload["Pagination"]
+    return {}
+
+
+def _truthy(value: object) -> bool:
+    """`HasMore` arrives as the STRING "false" as often as the boolean.
+
+    `if payload["Pagination"]["HasMore"]` on the string "false" is True, which
+    pages forever on a collection that just said it has no more.
+    """
+    if isinstance(value, str):
+        return value.strip().lower() in ("true", "1", "yes")
+    return bool(value)
+
+
+def _uip_list(connector_key: str, collection: str, connection_id: str,
+              query: str | None) -> dict:
+    """One `uip is resources run list` page, as parsed JSON."""
+    command = [
+        "uip", "is", "resources", "run", "list", connector_key, collection,
+        "--connection-id", connection_id, "--output", "json",
+    ]
+    if query:
+        command += ["--query", query]
+    result = subprocess.run(command, capture_output=True, text=True)
+    if result.returncode != 0:
+        # `uip` prints a self-update failure to stderr before its real output,
+        # so stderr being non-empty is not evidence of anything. Judge the exit
+        # code and the payload.
+        raise ResolutionError(
+            f"listing {collection} failed: {result.stderr.strip() or 'no output'}"
+        )
+    try:
+        return json.loads(result.stdout)
+    except ValueError as error:
+        raise ResolutionError(
+            f"listing {collection} returned output that is not JSON: {error}"
+        ) from error
+
+
+def _read_path(record: dict, dotted: str):
+    """`profile.email` out of a record, or None."""
+    cursor = record
+    for part in dotted.split("."):
+        if not isinstance(cursor, dict):
+            return None
+        cursor = cursor.get(part)
+    return cursor
+
+
+def _substitute(template: str, resolved: dict[str, str]) -> str:
+    """Fill `{fields.project.key}` placeholders from already-resolved fields."""
+    out = template
+    for field, value in resolved.items():
+        out = out.replace("{" + field + "}", str(value))
+    return out
+
+
+def resolve_one(
+    connector_key: str,
+    spec: dict,
+    field: str,
+    by: str,
+    value: str,
+    connection_id: str,
+    resolved: dict[str, str],
+) -> str:
+    """The connector-facing id for one lookup, or raise `ResolutionError`.
+
+    `resolved` carries the values of fields resolved earlier in this run, which
+    is what makes a `dependsOn` path addressable.
+    """
+    if by not in (spec.get("by") or []):
+        searchable = ", ".join(repr(b) for b in (spec.get("by") or []))
+        raise ResolutionError(
+            f"{field}: cannot search by {by!r}. Searchable by {searchable or '(nothing declared)'}."
+        )
+
+    path = _substitute(spec.get("path") or "", resolved)
+    if "{" in path:
+        missing = path[path.index("{") + 1: path.index("}")] if "}" in path else "?"
+        raise ResolutionError(
+            f"{field}: the collection path still contains {{{missing}}}. "
+            f"Resolve {missing!r} first with --resolve {missing}:<by>=<value>."
+        )
+    collection = path.split("?", 1)[0].strip("/")
+    query = path.partition("?")[2] or None
+    send = spec.get("value") or "id"
+
+    # A server-side filter turns the whole scan into one request. Where the
+    # metadata declares one, use it; where it does not, page.
+    filter_pattern = spec.get("filterPattern")
+    if filter_pattern:
+        filtered = filter_pattern.replace("{filter}", value)
+        query = f"{query}&{filtered}" if query else filtered
+
+    scanned = 0
+    pages = 0
+    while True:
+        payload = _uip_list(connector_key, collection, connection_id, query)
+        items = _envelope_items(payload)
+        for record in items:
+            scanned += 1
+            if str(_read_path(record, by)) == value:
+                got = _read_path(record, send)
+                if got is None:
+                    raise ResolutionError(
+                        f"{field}: matched a record on {by}={value!r}, but it "
+                        f"carries no {send!r} to send."
+                    )
+                return str(got)
+        pagination = _envelope_pagination(payload)
+        token = pagination.get("NextPageToken")
+        if not _truthy(pagination.get("HasMore")) or not token or scanned >= MAX_SCANNED:
+            break
+        pages += 1
+        if pages > PAGE_GUARD:
+            break
+        # Exactly `nextPage`. Guessing `page` / `pageToken` / `nextPageToken`
+        # is a documented way to loop forever on page one.
+        query = f"{query}&nextPage={token}" if query else f"nextPage={token}"
+
+    capped = scanned >= MAX_SCANNED or pages > PAGE_GUARD
+    raise ResolutionError(
+        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}"
+    )