@uipath/maestro-builder-sdk 6.10.3 → 6.11.1

package/dist/cli/commands/registry.js

@@ -130,6 +130,7 @@ export function registerRegistryCommands(program) {
         // `uip is connections list` and writes both keys into bindings.json.
         .option('--connection-id <id>', 'connection to read the schema through')
         .option('--connection <name>', 'pick the connection by name when several match')
+        .option('--connection-folder <folder>', 'pick the connection in the folder the flow runs in (name or key) when several match')
         .option('--bindings <file>', 'bindings file to update (default: ./bindings.json)')
         .option('--bind-connection <name>', 'symbolic connection name (default: the one label the source uses for this connector, else the connector suffix)')
         .option('--bind-folder <name>', 'symbolic folder name (default: the one folder label the source uses, else shared)')
@@ -170,6 +171,7 @@ export function registerRegistryCommands(program) {
         const argv = [connectorKey, action];
         addValue(argv, '--connection-id', options.connectionId);
         addValue(argv, '--connection', options.connection);
+        addValue(argv, '--connection-folder', options.connectionFolder);
         addValue(argv, '--bindings', options.bindings);
         addValue(argv, '--bind-connection', options.bindConnection);
         addValue(argv, '--bind-folder', options.bindFolder);

package/dist/registry/prepare/connections.d.ts

@@ -53,7 +53,68 @@ export declare function selectConnection(rows: readonly ConnectionRow[], connect
  * connection where the tenant-wide view is many. Widening first would turn an
  * unambiguous case into an ambiguous one.
  */
-export declare function discoverConnection(client: UipClient, connectorKey: string, name?: string): Promise<ConnectionRow>;
+export declare function discoverConnection(client: UipClient, connectorKey: string, name?: string, prefer?: ConnectionPreference): Promise<ConnectionRow>;
+/**
+ * What settles a choice among several enabled connections for one connector,
+ * consulted in this order, each only when the one before it did not decide.
+ *
+ * The eval tenant holds `is-sandboxes` (Slack), `is.sandboxes.test@gmail.com`
+ * (Drive) and the Outlook connections twice each, once in the
+ * `uipath-maestro-flow` folder and once in `uipath-maestro-case`. A name
+ * cannot tell them apart, and a lookup cannot either when both reach the same
+ * workspace — so every connector task paid one refused call and a re-run with
+ * `--connection-id` (flow-builder-sdk#818: 13 refusals in one run). What does
+ * tell them apart is WHERE the flow runs, and there are two honest sources for
+ * that: the author saying so, and the solution having already recorded it.
+ */
+export interface ConnectionPreference {
+    /**
+     * `--connection-folder`: the folder the flow runs in, by name
+     * (case-insensitive, as Orchestrator folder names are) or by folder key.
+     */
+    folder?: string;
+    /**
+     * Connection ids the solution already records for this connector —
+     * `resources/<folder>/connection/<connectorKey>/*.json`, whose `key` is the
+     * connection id `uip solution resources refresh` bound. See
+     * {@link solutionConnectionIds}.
+     */
+    solutionIds?: ReadonlySet<string>;
+}
+/** How {@link chooseConnection} settled on its row, for the line that reports it. */
+export type ConnectionChoice = "only" | "folder" | "solution";
+/** True when `row` is in `folder`: its `Folder` name ignoring case, or its `FolderKey` exactly. */
+export declare function inFolder(row: ConnectionRow, folder: string): boolean;
+/**
+ * {@link discoverConnection} with the reason it chose. Never guesses: each
+ * step either narrows to exactly one row or hands the choice on, and the last
+ * step is the refusal listing every candidate.
+ *
+ * 1. `--connection-folder` given: every enabled connection in the tenant (own
+ *    folder first, as {@link candidateConnections} orders them) in that
+ *    folder. Exactly one is the answer; none or several is a refusal, because
+ *    the author named a folder and a silent fallback would ignore them.
+ * 2. Otherwise the default discovery — own folder, then the tenant. One row is
+ *    the answer as before.
+ * 3. Several: those the solution already records. Exactly one is the answer.
+ * 4. Otherwise the ambiguity refusal, which names both flags.
+ */
+export declare function chooseConnection(client: UipClient, connectorKey: string, name?: string, prefer?: ConnectionPreference): Promise<{
+    row: ConnectionRow;
+    by: ConnectionChoice;
+}>;
+/**
+ * The connection ids a solution records for `connectorKey`: the `key` of every
+ * `resources/<folder>/connection/<connectorKey>/*.json` under each solution
+ * (a directory holding a `.uipx`) at `cwd`, above it, or one level below it —
+ * the flow-sdk layout keeps the solution as a child of the working directory.
+ *
+ * `uip solution resources refresh` writes these, and a seeded or re-edited
+ * solution carries them, so they are the tenant's own record of which
+ * connection this solution deploys with. A file that will not parse, or whose
+ * `type` names another connector, contributes nothing.
+ */
+export declare function solutionConnectionIds(cwd: string, connectorKey: string): Set<string>;
 /**
  * Every enabled connection for `connectorKey`, own folder FIRST
  * (`_connections.candidate_connections`).

package/dist/registry/prepare/connections.js

@@ -21,7 +21,8 @@
  * a {@link UipClient} and hand the rows to them. Every refusal's text is kept
  * verbatim — agents read these messages and follow them.
  */
-import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
 import { pyJsonStringify } from "../codecs/pyjson.js";
 import { Refusal, messageOf } from "../errors.js";
 import { isConnectionsList } from "../uip/commands.js";
@@ -102,10 +103,11 @@ export function selectConnection(rows, connectorKey, name, scope = "the tenant")
         const names = new Set(matched.map((row) => pyStrAny(row.Name)));
         // Python tested `name is not None`: an empty-string name takes this branch too.
         const remedy = (name !== undefined && name !== null) || names.size < matched.length
-            ? "They share a name, so --connection <name> cannot pick one; pass " +
-                "the id of the one in the folder you mean with --connection-id:"
-            : "Name the one you want with --connection <name>, or pass its id " +
-                "with --connection-id:";
+            ? "They share a name, so --connection <name> cannot pick one; name " +
+                "the folder the flow runs in with --connection-folder <folder>, or " +
+                "pass the id of the one you mean with --connection-id:"
+            : "Name the one you want with --connection <name>, name its folder " +
+                "with --connection-folder <folder>, or pass its id with --connection-id:";
         throw new ConnectionRefusal(`${matched.length} enabled ${connectorKey} connections in ${scope}, and they ` +
             "are not interchangeable — a record that exists in one workspace need " +
             `not exist in another. ${remedy}\n${listed}`, "CONNECTION_AMBIGUOUS");
@@ -121,14 +123,137 @@ export function selectConnection(rows, connectorKey, name, scope = "the tenant")
  * connection where the tenant-wide view is many. Widening first would turn an
  * unambiguous case into an ambiguous one.
  */
-export async function discoverConnection(client, connectorKey, name) {
+export async function discoverConnection(client, connectorKey, name, prefer = {}) {
+    return (await chooseConnection(client, connectorKey, name, prefer)).row;
+}
+/** True when `row` is in `folder`: its `Folder` name ignoring case, or its `FolderKey` exactly. */
+export function inFolder(row, folder) {
+    const wanted = folder.trim();
+    if (!wanted)
+        return false;
+    return (pyStrAny(pyGet(row, "Folder", "")).toLowerCase() === wanted.toLowerCase() ||
+        pyStrAny(pyGet(row, "FolderKey", "")) === wanted);
+}
+/**
+ * {@link discoverConnection} with the reason it chose. Never guesses: each
+ * step either narrows to exactly one row or hands the choice on, and the last
+ * step is the refusal listing every candidate.
+ *
+ * 1. `--connection-folder` given: every enabled connection in the tenant (own
+ *    folder first, as {@link candidateConnections} orders them) in that
+ *    folder. Exactly one is the answer; none or several is a refusal, because
+ *    the author named a folder and a silent fallback would ignore them.
+ * 2. Otherwise the default discovery — own folder, then the tenant. One row is
+ *    the answer as before.
+ * 3. Several: those the solution already records. Exactly one is the answer.
+ * 4. Otherwise the ambiguity refusal, which names both flags.
+ */
+export async function chooseConnection(client, connectorKey, name, prefer = {}) {
+    if (prefer.folder !== undefined && prefer.folder.trim() !== "") {
+        const folder = prefer.folder.trim();
+        const all = await candidateConnections(client, connectorKey, name);
+        const there = all.filter((row) => inFolder(row, folder));
+        if (there.length === 1)
+            return { row: there[0], by: "folder" };
+        if (there.length === 0) {
+            const qualifier = name ? ` named ${pyRepr(name)}` : "";
+            throw new ConnectionRefusal(`no enabled ${connectorKey} connection${qualifier} in folder ${pyRepr(folder)}. ` +
+                (all.length > 0
+                    ? `The enabled ones are:\n${candidateLines(all)}`
+                    : "List what exists with:\n  uip is connections list --all-folders"), "CONNECTION_NONE_IN_FOLDER");
+        }
+        return { row: selectConnection(there, connectorKey, name, "the tenant"), by: "folder" };
+    }
     let rows = enabledConnections(await listConnections(client, { allFolders: false }), connectorKey, name);
     let scope = "your folder";
     if (rows.length === 0) {
         rows = enabledConnections(await listConnections(client, { allFolders: true }), connectorKey, name);
         scope = "the tenant";
     }
-    return selectConnection(rows, connectorKey, name, scope);
+    if (rows.length > 1 && prefer.solutionIds !== undefined && prefer.solutionIds.size > 0) {
+        const recorded = rows.filter((row) => prefer.solutionIds.has(pyStrAny(pyGet(row, "Id", ""))));
+        if (recorded.length === 1)
+            return { row: recorded[0], by: "solution" };
+    }
+    return { row: selectConnection(rows, connectorKey, name, scope), by: "only" };
+}
+/**
+ * The connection ids a solution records for `connectorKey`: the `key` of every
+ * `resources/<folder>/connection/<connectorKey>/*.json` under each solution
+ * (a directory holding a `.uipx`) at `cwd`, above it, or one level below it —
+ * the flow-sdk layout keeps the solution as a child of the working directory.
+ *
+ * `uip solution resources refresh` writes these, and a seeded or re-edited
+ * solution carries them, so they are the tenant's own record of which
+ * connection this solution deploys with. A file that will not parse, or whose
+ * `type` names another connector, contributes nothing.
+ */
+export function solutionConnectionIds(cwd, connectorKey) {
+    const ids = new Set();
+    const solutions = new Set();
+    const hasUipx = (dir) => {
+        try {
+            return readdirSync(dir).some((entry) => entry.endsWith(".uipx"));
+        }
+        catch {
+            return false;
+        }
+    };
+    let dir = resolvePath(cwd);
+    for (let depth = 0; depth < 6; depth++) {
+        if (hasUipx(dir))
+            solutions.add(dir);
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    try {
+        for (const entry of readdirSync(cwd, { withFileTypes: true })) {
+            if (entry.isDirectory() && hasUipx(join(cwd, entry.name)))
+                solutions.add(resolvePath(cwd, entry.name));
+        }
+    }
+    catch {
+        // An unreadable cwd records nothing.
+    }
+    for (const solution of solutions) {
+        const resources = join(solution, "resources");
+        let folders;
+        try {
+            folders = readdirSync(resources);
+        }
+        catch {
+            continue;
+        }
+        for (const folder of folders) {
+            const connectorDir = join(resources, folder, "connection", connectorKey);
+            let files;
+            try {
+                files = readdirSync(connectorDir).filter((file) => file.endsWith(".json"));
+            }
+            catch {
+                continue;
+            }
+            for (const file of files) {
+                try {
+                    const resource = pyGet(JSON.parse(readFileSync(join(connectorDir, file), "utf8")), "resource", null);
+                    if (!isPlainObject(resource))
+                        continue;
+                    const type = pyGet(resource, "type", null);
+                    if (pyTruthy(type) && type !== connectorKey)
+                        continue;
+                    const key = pyStrAny(pyGet(resource, "key", ""));
+                    if (key)
+                        ids.add(key);
+                }
+                catch {
+                    // Not JSON: records nothing.
+                }
+            }
+        }
+    }
+    return ids;
 }
 /**
  * Every enabled connection for `connectorKey`, own folder FIRST

package/dist/registry/prepare/ledger.js

@@ -146,7 +146,10 @@ export async function writeResolutions(run, specs) {
         }
         let got;
         try {
-            got = await resolveOne(run.client, run.connectorKey, table.get(field), field, by, value, run.connectionId, resolved);
+            const notes = [];
+            got = await resolveOne(run.client, run.connectorKey, table.get(field), field, by, value, run.connectionId, resolved, notes);
+            for (const note of notes)
+                run.reporter.info(note);
         }
         catch (error) {
             // The collection was read to the END on this connection and the value

package/dist/registry/prepare/messages.d.ts

@@ -42,6 +42,11 @@ export declare class PrepareRefusal extends Refusal {
 export declare function exitText(error: unknown): string;
 /** `  connection: <Name> (<id>)` — `found.get('Name')` renders `None` when the row has none, as Python did. */
 export declare function connectionLine(row: Record<string, unknown>, connectionId: string): string;
+/**
+ * Why discovery chose this connection when several matched: the folder the
+ * author named, or the solution's own record of the connection.
+ */
+export declare function connectionChoiceLine(row: Record<string, unknown>, by: "folder" | "solution", folder?: string): string;
 /** `  bindings: <symbolic name> -> <bindings.json>`, once per row this run changed. */
 export declare function bindingsLine(symbolicName: string, bindingsPath: string): string;
 /** ` (the label Demo.flow.ts uses)` — appended to a bindings line whose name came from the source. */

package/dist/registry/prepare/messages.js

@@ -58,6 +58,16 @@ export function exitText(error) {
 export function connectionLine(row, connectionId) {
     return `  connection: ${pyStrAny(pyGet(row, "Name", null))} (${connectionId})`;
 }
+/**
+ * Why discovery chose this connection when several matched: the folder the
+ * author named, or the solution's own record of the connection.
+ */
+export function connectionChoiceLine(row, by, folder) {
+    const where = pyStrAny(row.Folder);
+    return by === "folder"
+        ? `  connection: chose the one in folder ${pyRepr(pyOr(folder, where))} (--connection-folder)`
+        : `  connection: chose the one the solution records (resources/*/connection/…, folder: ${where})`;
+}
 /** `  bindings: <symbolic name> -> <bindings.json>`, once per row this run changed. */
 export function bindingsLine(symbolicName, bindingsPath) {
     return `  bindings: ${symbolicName} -> ${bindingsPath}`;

package/dist/registry/prepare/pipeline.d.ts

@@ -10,6 +10,12 @@ export interface PrepareOptions {
     connectionId?: string;
     /** `--connection <name>`: pick the connection by name when several match. */
     connection?: string;
+    /**
+     * `--connection-folder <folder>`: the folder the flow runs in (name or key).
+     * Picks among several enabled connections; without it, the ids the solution
+     * already records are tried before the ambiguity refusal.
+     */
+    connectionFolder?: string;
     /** `--bindings` (default `./bindings.json`). */
     bindings?: string;
     /**

package/dist/registry/prepare/pipeline.js

@@ -36,11 +36,11 @@ import { expandGenericForConnector, genericTemplatesByOp } from "../library-buil
 import { planLibrary } from "../library-build/plan.js";
 import { MemoryResponseCache } from "../uip/response-cache.js";
 import { registryCatalog } from "./actions.js";
-import { discoverConnection, listConnections, lookupConnection, mergeBindings, restoreBindings, snapshotBindings, } from "./connections.js";
+import { chooseConnection, listConnections, lookupConnection, mergeBindings, restoreBindings, snapshotBindings, solutionConnectionIds, } from "./connections.js";
 import { prepareEvent } from "./event.js";
 import { descriptorUsage } from "./handoff.js";
 import { ResolutionsExhausted, allParentsResolved, resolvedParentValues, writeResolutions } from "./ledger.js";
-import { PREPARE_COMMAND, PrepareRefusal, ambiguousLabelsMessage, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, flagDiffersFromSourceLine, keptSchemaMessage, labelTakenMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, registryGetFailedMessage, sharedLabelMessage, sourceLabelSuffix, tsNote, partlyUnreadableLabelLine, unreadableLabelLine, unresolvedOperationMessage, } from "./messages.js";
+import { PREPARE_COMMAND, PrepareRefusal, ambiguousLabelsMessage, connectionChoiceLine, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, flagDiffersFromSourceLine, keptSchemaMessage, labelTakenMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, registryGetFailedMessage, sharedLabelMessage, sourceLabelSuffix, tsNote, partlyUnreadableLabelLine, unreadableLabelLine, unresolvedOperationMessage, } from "./messages.js";
 import { ObjectMatchRefusal, RESOLUTIONS_FILENAME, matchObject, recordObjectResolution } from "./objects.js";
 import { countInputFields, keepPreparedSchema, lookupSpecsFromOverlay, mergeFilesInto, parentFields as overlayParentFields, schemaActionParents, } from "./overlay.js";
 import { declaredParents, objectActionRequest, objectActionSpecs, parseFields } from "./parents.js";
@@ -195,12 +195,19 @@ async function connect(options, ports) {
     const labels = options.noBindings ? undefined : chooseLabels(options, ports);
     let row;
     let connectionId;
+    let chosenBy = "only";
     if (!options.connectionId) {
         // Discover the connection when the caller did not name one, and record it
         // in bindings.json so the author never has to look up either key — the
         // step that removes 4-7 tool calls per task.
-        row = await discoverConnection(ports.client, options.connectorKey, options.connection);
+        const cwd = ports.cwd ?? process.cwd();
+        const choice = await chooseConnection(ports.client, options.connectorKey, options.connection, {
+            folder: options.connectionFolder,
+            solutionIds: solutionConnectionIds(cwd, options.connectorKey),
+        });
+        row = choice.row;
         connectionId = pyStrAny(row.Id);
+        chosenBy = choice.by;
     }
     else {
         // An explicit id gets the same gate discovery applies: a `State: Failed`
@@ -209,6 +216,8 @@ async function connect(options, ports) {
         row = await lookupConnection(ports.client, options.connectorKey, connectionId);
     }
     info(connectionLine(row, connectionId));
+    if (chosenBy !== "only")
+        info(connectionChoiceLine(row, chosenBy, options.connectionFolder));
     if (!labels)
         return { connectionId, row };
     // Recorded on BOTH routes. Until 3.30.5 only discovery wrote it, and the
@@ -251,7 +260,9 @@ export async function prepareConnector(options, ports) {
     // Whether the CALLER chose the connection, recorded before discovery answers
     // with its own. An explicit choice is never second-guessed: the retry below
     // is for a connection this command picked, not for one the author named.
-    const pinned = pyTruthy(options.connectionId) || pyTruthy(options.connection);
+    // A named folder is a choice too: probing the other folders' connections
+    // after the author said which folder the flow runs in would overrule them.
+    const pinned = pyTruthy(options.connectionId) || pyTruthy(options.connection) || pyTruthy(options.connectionFolder);
     const connected = await connect(options, ports);
     try {
         return await prepareOnConnection(options, ports, connected);

package/dist/registry/prepare/resolve.d.ts

@@ -229,7 +229,7 @@ export declare function scanCollection(client: UipClient, connectorKey: string,
  * A collection read to its end with no match throws {@link LookupExhausted},
  * the subclass the caller's retry keys on; every other failure is the parent.
  */
-export declare function resolveOne(client: UipClient, connectorKey: string, spec: ResolveSpec, field: string, by: string, value: string, connectionId: string, resolved?: Resolved): Promise<string>;
+export declare function resolveOne(client: UipClient, connectorKey: string, spec: ResolveSpec, field: string, by: string, value: string, connectionId: string, resolved?: Resolved, notes?: string[]): Promise<string>;
 /**
  * The child collection of `parent`: `childPath` with each `{Field}` read off
  * the parent record (`{ID}` → the folder's id), split into collection and

package/dist/registry/prepare/resolve.js

@@ -449,7 +449,7 @@ export async function* scanCollection(client, connectorKey, collection, connecti
  * A collection read to its end with no match throws {@link LookupExhausted},
  * the subclass the caller's retry keys on; every other failure is the parent.
  */
-export async function resolveOne(client, connectorKey, spec, field, by, value, connectionId, resolved = new Map()) {
+export async function resolveOne(client, connectorKey, spec, field, by, value, connectionId, resolved = new Map(), notes) {
     const searchableBy = Array.isArray(spec.by) ? spec.by : [];
     if (!searchableBy.includes(by)) {
         const searchable = searchableBy.map(pyRepr).join(", ");
@@ -482,13 +482,15 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
     // pasting a literal id (flow-builder-sdk#818). A server-side filter still
     // wins: it answers from the whole collection in one request.
     if (pyTruthy(spec.childPath) && !pyTruthy(filterPattern)) {
-        return resolveInTree(client, connectorKey, spec, field, by, value, connectionId, resolved, collection, query, send);
+        return resolveInTree(client, connectorKey, spec, field, by, value, connectionId, resolved, collection, query, send, notes);
     }
     const scan = scanCollection(client, connectorKey, collection, connectionId, query);
     // What the collection DOES hold at `by`, for the refusal: kept only while it
     // could still be listed in full, plus the first case-insensitive equal.
     const held = [];
-    let near;
+    // Records whose `by` equals the value ignoring case only, first per distinct
+    // spelling: the fallback when no record matches exactly.
+    const caseOnly = new Map();
     let step = await scan.next();
     while (!step.done) {
         for (const record of step.value) {
@@ -497,8 +499,8 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
                 const text = pyStrAny(at);
                 if (held.length <= CANDIDATE_LIMIT && !held.includes(text))
                     held.push(text);
-                if (near === undefined && text !== value && text.toLowerCase() === value.toLowerCase())
-                    near = text;
+                if (text !== value && text.toLowerCase() === value.toLowerCase() && !caseOnly.has(text))
+                    caseOnly.set(text, record);
             }
             if (matchRecord(record, by, value)) {
                 const got = readPath(record, send);
@@ -512,6 +514,27 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
         step = await scan.next();
     }
     const { scanned, pages, capped } = step.value;
+    // No exact match anywhere in the collection: try the case-only ones. Exact
+    // first, because an id picked by a looser rule while the exact record sat
+    // on a later page would be the wrong id. Only once the scan has read to the
+    // END — a capped scan may still hold the exact record further in, so it
+    // keeps the refusal and the hint.
+    //
+    // `send_as:name=user` against `available_tokens` ('Bot', 'User') and
+    // `E2E-testing` against `E2E-Testing` each cost a refused `prepare` and a
+    // re-run whose only change was the letter case the refusal had already
+    // named (flow-builder-sdk#818). One spelling is unambiguous, so it is taken
+    // and said; two spellings that differ only in case are two records, and
+    // choosing between them would be a guess.
+    const near = caseOnly.size > 0 ? [...caseOnly.keys()][0] : undefined;
+    if (!capped && caseOnly.size > 0) {
+        const record = findRecord([...caseOnly.values()], field, by, value, notes);
+        const got = readPath(record, send);
+        if (got === null) {
+            throw new ResolutionRefusal(`${field}: matched a record on ${by}=${pyRepr(pyStrAny(readPath(record, by)))}, but it carries no ${pyRepr(send)} to send.`, "RESOLVE_NO_VALUE");
+        }
+        return pyStrAny(got);
+    }
     // This states the FACT and stops; `prepare` owns the remedy, because
     // `prepare` is what knows the other candidate connections.
     //
@@ -529,8 +552,8 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
     // is finally the next step rather than a detour.
     //
     // What it DOES carry is what the collection holds, when that is small enough
-    // to read in one line, and a case-only near miss: facts about this
-    // connection, not a remedy. `matchRecord` stays exact — nothing is picked.
+    // to read in one line, and — when the cap stopped the scan — a case-only
+    // near miss that was NOT taken: facts about this connection, not a remedy.
     //
     // Never under a server-side filter: the scan then read only the records the
     // filter returned (`name like '%Coder Eval%'` gives 'Coder Evals' and 'Coder
@@ -541,13 +564,43 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
         `(scanned ${scanned} record(s) across ${pages + 1} page(s)` +
         (capped ? `; STOPPED AT THE ${MAX_SCANNED}-record cap, so the value may be further in` : "; collection exhausted") +
         `) on connection ${connectionId}.` +
-        (near !== undefined ? ` Did you mean ${pyRepr(near)}? The match is exact, case included.` : "") +
+        (near !== undefined
+            ? ` Did you mean ${pyRepr(near)}? It differs only in case and was not taken: the scan stopped before the end, where an exact match may still be.`
+            : "") +
         (candidates !== undefined ? ` It holds: ${candidates.map(pyRepr).join(", ")}.` : ""), {
         field, collection, by, value, scanned, pages: pages + 1, capped,
         ...(candidates !== undefined ? { candidates } : {}),
         ...(near !== undefined ? { near } : {}),
     });
 }
+/**
+ * The record in `records` matching `value` on `by`: exact first, else the one
+ * case-only spelling (reported through `notes`), else `undefined`. Two
+ * case-only spellings are a refusal, as in the flat scan.
+ */
+function findRecord(records, field, by, value, notes) {
+    const exact = records.find((record) => matchRecord(record, by, value));
+    if (exact !== undefined)
+        return exact;
+    const caseOnly = new Map();
+    for (const record of records) {
+        const at = readPath(record, by);
+        if (at === null || at === undefined)
+            continue;
+        const text = pyStrAny(at);
+        if (text !== value && text.toLowerCase() === value.toLowerCase() && !caseOnly.has(text))
+            caseOnly.set(text, record);
+    }
+    if (caseOnly.size === 0)
+        return undefined;
+    if (caseOnly.size > 1) {
+        throw new ResolutionRefusal(`${field}: no record has ${by}=${pyRepr(value)} exactly, and ${caseOnly.size} differ from it only in case: ` +
+            `${[...caseOnly.keys()].map(pyRepr).join(", ")}. They are different records; pass the one you mean exactly.`, "RESOLVE_CASE_AMBIGUOUS");
+    }
+    const [[text, record]] = [...caseOnly.entries()];
+    notes?.push(`  ${field}: no record has ${by}=${pyRepr(value)} exactly; took ${pyRepr(text)}, the only one that differs from it only in case`);
+    return record;
+}
 async function listAll(client, connectorKey, collection, connectionId, query) {
     const records = [];
     const scan = scanCollection(client, connectorKey, collection, connectionId, query);
@@ -602,7 +655,7 @@ function isContainer(record) {
  * connections. A path whose segment is missing from a listing read to the end
  * IS evidence, and is reported as an exhaustive miss like a flat scan's.
  */
-async function resolveInTree(client, connectorKey, spec, field, by, value, connectionId, resolved, rootCollection, rootQuery, send) {
+async function resolveInTree(client, connectorKey, spec, field, by, value, connectionId, resolved, rootCollection, rootQuery, send, notes) {
     const childPath = pyStrAny(spec.childPath);
     const answer = (record) => {
         const got = readPath(record, send);
@@ -625,12 +678,14 @@ async function resolveInTree(client, connectorKey, spec, field, by, value, conne
     const exact = root.records.find((record) => matchRecord(record, by, value));
     if (exact !== undefined)
         return answer(exact);
+    // A whole-value case-only match at the root is deferred: a path value, or a
+    // bare name one level down, may still match exactly.
     const segments = value.split("/").map((segment) => pyStrip(segment)).filter((segment) => segment !== "");
     if (segments.length > 1) {
         let level = root;
         let where = rootCollection;
         for (const [i, segment] of segments.entries()) {
-            const hit = level.records.find((record) => matchRecord(record, by, segment));
+            const hit = findRecord(level.records, field, by, segment, notes);
             if (hit === undefined) {
                 const held = level.records.map((record) => pyStrAny(readPath(record, by))).filter((text) => text !== "None");
                 const shown = !level.outcome.capped && held.length > 0 && held.length <= CANDIDATE_LIMIT ? ` It holds: ${held.map(pyRepr).join(", ")}.` : "";
@@ -651,6 +706,7 @@ async function resolveInTree(client, connectorKey, spec, field, by, value, conne
         }
     }
     // Bare name: one level below every root container.
+    const below = [];
     for (const parent of root.records) {
         if (!isContainer(parent))
             continue;
@@ -660,10 +716,16 @@ async function resolveInTree(client, connectorKey, spec, field, by, value, conne
         if (child === undefined)
             continue;
         const level = await list(child.collection, child.query);
-        const hit = level.records.find((record) => matchRecord(record, by, value));
-        if (hit !== undefined)
-            return answer(hit);
+        const exactBelow = level.records.find((record) => matchRecord(record, by, value));
+        if (exactBelow !== undefined)
+            return answer(exactBelow);
+        below.push(...level.records);
     }
+    // No exact match at either depth: the case-only one, root and one level
+    // down together, so a spelling in each is two records and a refusal.
+    const loose = findRecord([...root.records, ...below], field, by, value, notes);
+    if (loose !== undefined)
+        return answer(loose);
     const top = root.records.map((record) => pyStrAny(readPath(record, by))).filter((text) => text !== "None");
     const example = `${top[0] ?? "<top-level>"}/<folder>/${value}`;
     throw new LookupExhausted(`${field}: no record in ${pyRepr(rootCollection)} or one level below it has ${by}=${pyRepr(value)} ` +

package/dist/registry/prepare-cli.d.ts

@@ -26,6 +26,8 @@ export interface PrepareConnectorOptions {
     connectionId?: string;
     /** Pick the connection by name when several match. */
     connection?: string;
+    /** `--connection-folder`: the folder the flow runs in, when several connections match. */
+    connectionFolder?: string;
     /** bindings file to add the discovered connection to. */
     bindings?: string;
     bindConnection?: string;

package/dist/registry/prepare-cli.js

@@ -15,7 +15,8 @@ import { defaultUipClient } from "./uip/client.js";
 const DEFAULT_CONNECTOR_IMPORT = PACKAGE_NAME;
 const USAGE = [
     "Usage: flow-sdk registry prepare <connector-key> --action <name> [--connection-id <id>]",
-    "                                [--connection <name>] [--bindings <file>] [--no-bindings]",
+    "                                [--connection <name>] [--connection-folder <folder>]",
+    "                                [--bindings <file>] [--no-bindings]",
     "                                [--object <name> | --all-objects] [-f NAME=VALUE ...]",
     "                                [--resolve FIELD:BY=VALUE ...] [--refresh-lookups]",
     "                                [--out <dir>] [--version <v>] [--import <specifier>]",
@@ -29,6 +30,7 @@ export function pipelineOptions(options) {
         action: options.action,
         connectionId: options.connectionId,
         connection: options.connection,
+        connectionFolder: options.connectionFolder,
         bindings: options.bindings,
         bindConnection: options.bindConnection,
         bindFolder: options.bindFolder,
@@ -101,6 +103,7 @@ export function parseArgs(argv) {
     for (const name of [
         "--connection-id",
         "--connection",
+        "--connection-folder",
         "--bindings",
         "--bind-connection",
         "--bind-folder",
@@ -147,6 +150,7 @@ export function parseArgs(argv) {
         action: positionals[1],
         connectionId: value(argv, "--connection-id"),
         connection: value(argv, "--connection"),
+        connectionFolder: value(argv, "--connection-folder"),
         bindings: value(argv, "--bindings"),
         bindConnection: value(argv, "--bind-connection"),
         bindFolder: value(argv, "--bind-folder"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.10.3",
+  "version": "6.11.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "d3639fb590ef392d76c174521c9cc1d280f7125a"
+  "gitref": "85e9b8d11773bb7e83aed5deb38eea2ecd25bd2a"
 }