@uipath/maestro-builder-sdk 6.10.3 → 6.11.0

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/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-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.0",
   "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": "fa8ffa3eea8369ff520a8214644c971df0c4af74"
 }