@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

package/dist/generators/_lookups.py

@@ -1,114 +0,0 @@
-#!/usr/bin/env python3
-"""Classify a connector input field's `reference` block, for both generators.
-
-A `reference` with a `lookupValue` says a field's value is an opaque id that has
-to be resolved against a live connection. 1,365 input fields across the shipped
-library carry one. But not all of them are asking for a resolution, and
-generating a `.by*` helper for the ones that are not is actively harmful: a
-helper that shows up where it is not needed teaches a reader that the helper is
-noise, and then it is ignored on the fields that need it.
-
-Two classes are excluded, and they are excluded for different reasons.
-
-IDENTITY LOOKUPS (231 fields). `lookupValue` is the only entry in `lookupNames`,
-so the "resolution" is the identity function: call the API, match
-`label == 'Qualified'`, send back `'Qualified'`. Nothing is translated — the
-block enumerates legal values rather than mapping a name to an id. Detected
-mechanically here.
-
-INVARIANT COLLECTIONS (164 fields). The collection is a property of the
-CONNECTOR's API rather than of the CONNECTION — a country list is identical in
-every tenant — so the id cannot go stale on a move and resolving late buys
-nothing. NOT detectable from the metadata: `system_countries -> name` and
-`Users -> id` are structurally identical. Read from a curated ledger instead;
-see `invariant-collections.json` for why that ledger is closed at three rows.
-
-The fallback direction is deliberate and is the safe one. An unclassified field
-is treated as an ordinary lookup, which is never *wrong* — only occasionally
-ceremonial. The opposite default would drop the helper from a genuinely
-connection-scoped field and hand the author back the silent-wrongness failure
-the whole mechanism exists to remove.
-"""
-
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-__all__ = [
-    "LEDGER_FILENAME",
-    "load_invariant_collections",
-    "reference_of",
-    "is_identity_lookup",
-    "classify",
-    "resolvable_lookup_fields",
-]
-
-LEDGER_FILENAME = "invariant-collections.json"
-
-
-def load_invariant_collections(library_dir: str | Path | None) -> set[str]:
-    """The ledger's `objectName` set, or an empty set.
-
-    An absent or malformed ledger reads as EMPTY rather than raising, which
-    matches `loadListEnvelopes` in the SDK and is the same reasoning: the
-    permissive path is the pre-ledger behaviour, so the worst case of a bad edit
-    is losing the exactness, never breaking a build.
-    """
-    if not library_dir:
-        return set()
-    path = Path(library_dir) / LEDGER_FILENAME
-    if not path.is_file():
-        return set()
-    try:
-        with path.open(encoding="utf-8") as fh:
-            parsed = json.load(fh)
-    except (OSError, ValueError):
-        return set()
-    rows = parsed.get("collections")
-    if not isinstance(rows, list):
-        return set()
-    return {
-        row["objectName"] for row in rows
-        if isinstance(row, dict) and isinstance(row.get("objectName"), str)
-    }
-
-
-def reference_of(field: dict) -> dict | None:
-    """The field's `reference` block when it declares a resolvable value."""
-    reference = field.get("reference")
-    if not isinstance(reference, dict):
-        return None
-    if not reference.get("lookupValue"):
-        return None
-    return reference
-
-
-def is_identity_lookup(reference: dict) -> bool:
-    """True when resolving would return the value it was given."""
-    names = reference.get("lookupNames") or []
-    return len(names) == 1 and reference.get("lookupValue") in names
-
-
-def classify(field: dict, invariant: set[str]) -> str:
-    """One of `'none'`, `'identity'`, `'invariant'`, `'lookup'`.
-
-    Only `'lookup'` earns a helper and a `--resolve`. The two degenerate classes
-    are reported distinctly rather than merged because the markdown treats them
-    differently: an identity lookup keeps its enumeration command (its legal
-    values exist nowhere offline), while an invariant one is just a value the
-    author already knows how to write.
-    """
-    reference = reference_of(field)
-    if reference is None:
-        return "none"
-    if is_identity_lookup(reference):
-        return "identity"
-    if reference.get("objectName") in invariant:
-        return "invariant"
-    return "lookup"
-
-
-def resolvable_lookup_fields(fields: list[dict], invariant: set[str]) -> list[dict]:
-    """The subset of `fields` that earns a `.by*` helper, in declaration order."""
-    return [f for f in fields if classify(f, invariant) == "lookup"]

package/dist/generators/_naming.py

@@ -1,185 +0,0 @@
-#!/usr/bin/env python3
-"""Symbol-name derivation shared by the two library generators.
-
-`library-json/` feeds two derived views (see `lib/scripts/unpack-library.sh`):
-`generate_connectors_ts.py` emits the TypeScript descriptors an author imports,
-and `convert_library_to_md.py` emits the markdown an agent reads. The markdown
-now cites the TypeScript **by name** — `connector(SendMessageToUser, …)`,
-`.byEmail(…)` — and neither name exists anywhere in the JSON. Both are derived.
-
-That makes the derivation a shared contract rather than a private detail, and
-the failure mode of re-deriving it twice is the worst one available: a wrong
-*description* costs a reader one re-read, but a wrong *symbol* is an import that
-throws, printed by documentation, for a helper the reader was being told to
-prefer over a route that already worked. They will not try the helper again.
-
-So both generators import this module and neither owns a copy. The de-collision
-loop especially cannot be duplicated even in principle — it is stateful across a
-whole connector module, so a per-page re-derivation has no way to know that the
-name it is about to print was already taken by an earlier operation.
-"""
-
-from __future__ import annotations
-
-import re
-
-__all__ = [
-    "pascal",
-    "singular",
-    "op_identity",
-    "op_symbol_name",
-    "symbol_index",
-    "by_alias",
-    "by_aliases",
-]
-
-
-def pascal(action_id: str) -> str:
-    """`send-message-to-user` -> `SendMessageToUser`."""
-    return "".join(
-        w[:1].upper() + w[1:] for w in re.split(r"[^A-Za-z0-9]+", action_id) if w
-    ) or "Op"
-
-
-def singular(name: str) -> str:
-    """Small deterministic singularizer for array field names used as type names."""
-    if name.lower().endswith("ies") and len(name) > 3:
-        return name[:-3] + "y"
-    if name.lower().endswith("sses"):
-        return name[:-2]
-    if name.lower().endswith("s") and not name.lower().endswith(("ss", "us")):
-        return name[:-1]
-    return name
-
-
-def op_identity(entry: dict) -> tuple[str, str, str]:
-    """`(nodeType, activityType, label)` from either entry shape.
-
-    The same operation is described by two different JSON shapes: `index.json`
-    rows are flat (`activityType`, `label` at the top level) while the per-op
-    entry files nest them (`operation.activityType`, `display.label`). The
-    descriptor generator reads the nested one and the markdown generator walks
-    the flat one, so a naming helper that accepted only one of them would push
-    the caller into re-deriving the other — which is the drift this module
-    exists to prevent.
-    """
-    node_type = entry.get("nodeType") or ""
-    operation = entry.get("operation")
-    if isinstance(operation, dict):
-        activity_type = operation.get("activityType") or ""
-    else:
-        activity_type = entry.get("activityType") or ""
-    display = entry.get("display")
-    if isinstance(display, dict) and display.get("label"):
-        label = display["label"]
-    else:
-        label = entry.get("label") or ""
-    if not label:
-        label = node_type.rsplit(".", 1)[-1]
-    return node_type, activity_type, label
-
-
-def op_symbol_name(entry: dict, seen: set[str]) -> str:
-    """The exported const name for one operation, de-collided within its module.
-
-    `seen` is the per-connector-module set of names already emitted, and it is
-    MUTATED here — that is the whole point of centralising this. A module emits
-    its operations in index order, so two operations whose labels pascal to the
-    same symbol are distinguished by a trailing `_` on the later one, and which
-    one gets the underscore depends on the order the caller walks the entries in.
-    Both generators must therefore walk in the same order and share this set.
-
-    A `GenericExpanded` entry is named from its display label rather than its
-    action id, because its action id is the shared generic verb (`create`,
-    `list-all-records`) and would collide for every object the generic covers.
-    """
-    node_type, activity_type, label = op_identity(entry)
-    action_id = node_type.rsplit(".", 1)[-1]
-    name = pascal(label if activity_type == "GenericExpanded" else action_id)
-    while name in seen:
-        name += "_"
-    seen.add(name)
-    return name
-
-
-def symbol_index(
-    entries: list[dict], include_generic_expanded: bool = False
-) -> dict[str, str]:
-    """`{nodeType: exportedConstName}` for every operation a module will export.
-
-    THE reason this exists. The descriptor generator groups entries by connector
-    and walks each group sorted by `nodeType`; the markdown generator walks
-    `index.json` in its own order, one operation at a time, and never groups. The
-    de-collision loop is stateful, so those two walks assign DIFFERENT names the
-    moment any connector has two operations whose labels collide — and the
-    markdown would then print an import that does not resolve.
-
-    Computing the map once, here, from the same grouping both must agree on, is
-    what makes that impossible rather than merely unlikely.
-
-    An operation with no entry in the returned map has no generated descriptor
-    (a `GenericExpanded` one, by default) and must be authored through the
-    library by key/action/object instead.
-    """
-    by_connector: dict[str, list[dict]] = {}
-    for entry in entries:
-        node_type, activity_type, _ = op_identity(entry)
-        if activity_type == "GenericExpanded" and not include_generic_expanded:
-            continue
-        key = entry.get("connectorKey")
-        if not key:
-            # `uipath.connector.<key>.<action>` — the only other place the key lives.
-            rest = node_type.replace("uipath.connector.", "")
-            key = rest.rsplit(".", 1)[0] if "." in rest else rest
-        by_connector.setdefault(key, []).append(entry)
-
-    names: dict[str, str] = {}
-    for _key, group in sorted(by_connector.items()):
-        seen: set[str] = set()
-        for entry in sorted(group, key=lambda e: e.get("nodeType") or ""):
-            names[entry["nodeType"]] = op_symbol_name(entry, seen)
-    return names
-
-
-def by_alias(lookup_name: str) -> str:
-    """`profile.email` -> `byEmail`; `profile.real_name` -> `byRealName`.
-
-    Only the LAST dotted segment is used. The leading path is where the value
-    lives in the vendor's record, which is a fact about their API rather than
-    about what the author is searching by — `byProfileEmail` would be noise, and
-    the generic `.by('profile.email', v)` is always available for the exact form.
-    """
-    last = lookup_name.rsplit(".", 1)[-1]
-    words = [w for w in re.split(r"[^A-Za-z0-9]+", last) if w]
-    if not words:
-        return ""
-    head, *rest = words
-    return "by" + head[:1].upper() + head[1:] + "".join(
-        w[:1].upper() + w[1:] for w in rest
-    )
-
-
-def by_aliases(lookup_names: list[str]) -> dict[str, str]:
-    """`{lookupName: alias}` for every name that earns an unambiguous alias.
-
-    Two `lookupNames` can camelise to one alias — `email` and `contact.email`
-    both give `byEmail` — and there is no non-arbitrary way to award it to one of
-    them. Rather than guess, BOTH are dropped from the alias map and reachable
-    only through the generic `.by(name, value)`. Silently binding `byEmail` to
-    whichever came first in the array would compile, run, and search the wrong
-    field, which is precisely the class of quiet wrongness the lookup surface
-    exists to remove.
-
-    An empty return is normal and means "generic form only".
-    """
-    counts: dict[str, int] = {}
-    for name in lookup_names:
-        alias = by_alias(name)
-        if alias:
-            counts[alias] = counts.get(alias, 0) + 1
-    out: dict[str, str] = {}
-    for name in lookup_names:
-        alias = by_alias(name)
-        if alias and counts[alias] == 1:
-            out[name] = alias
-    return out

package/dist/generators/_objects.py

@@ -1,299 +0,0 @@
-#!/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