@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

package/dist/generators/_resolve.py

@@ -1,319 +0,0 @@
-#!/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__ = [
-    "LookupExhausted",
-    "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."""
-
-
-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).
-
-    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
-    # 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 "; collection exhausted")
-        + f") on connection {connection_id}.",
-        field=field, collection=collection, by=by, value=value,
-        scanned=scanned, pages=pages + 1, capped=capped,
-    )