@uipath/maestro-builder-sdk 6.45.1 → 6.46.0

package/dist/bpmn/uipath-moddle.v1.json

@@ -233,6 +233,11 @@
           "name": "value",
           "isAttr": true,
           "type": "String"
+        },
+        {
+          "name": "isDefault",
+          "isAttr": true,
+          "type": "Boolean"
         }
       ]
     },

package/dist/check.js

@@ -651,7 +651,7 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
                             level: 'error',
                             code: 'SWITCH_CASE_ID',
                             message: typeof caseId !== 'string' || caseId === ''
-                                ? `Switch "${s.name}" case ${JSON.stringify(c.value)} has an id that is not a non-empty string. Leave \`id\` out for the positional case_<n>.`
+                                ? `Switch "${s.name}" case ${i + 1} has an id that is not a non-empty string. Leave \`id\` out for the positional case_<n>.`
                                 : `Switch "${s.name}" has two cases with the id "${caseId}", so both would leave from one 'case-${caseId}' port. Give one a different \`id\`.`,
                             step: s.name,
                         });

package/dist/compile-cli.js

@@ -20,7 +20,7 @@
 import { reportDiagnostics, reportResult, thrownDiagnostic } from './cli-result.js';
 import { writeJsonFile } from './core/json-file.js';
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { serializeWithSidecars } from './serialize.js';
 import { compileOwnsResource } from './core/agent-tool-resources.js';
@@ -272,8 +272,18 @@ export async function run(argv) {
             }
             if (!compileOwnsResource(body))
                 continue;
+            try {
+                rmSync(join(resourcesDir, entry), { recursive: true, force: true });
+            }
+            catch (error) {
+                // Studio Web's project file system refuses deletes. Only a surviving file keeps its row: a later compile skips a folder with no resource.json.
+                if (existsSync(file)) {
+                    console.error(`compile: could not remove stale ${relative(outDir, file)} (${error instanceof Error ? error.message : String(error)}); `
+                        + 'it is still declared as a resource of this agent until it is deleted.');
+                    continue;
+                }
+            }
             removedResources.push(body);
-            rmSync(join(resourcesDir, entry), { recursive: true, force: true });
             console.log(`compile: removed stale ${join('resources', entry, 'resource.json')}`);
         }
     }

package/dist/core/read-text.d.ts

@@ -21,6 +21,10 @@
  * `process.getBuiltinModule`, not an `import`, so the library loads no `node:` builtin
  * (FB015 exempts this fallback), and `process` is read through `globalThis`, as in
  * `core/typescript-module.ts`.
+ *
+ * The tenant calls (`registry prepare`'s `uip` runs) have a sibling slot,
+ * `globalThis[Symbol.for('uipath.maestro-builder-sdk.uip')]`, documented on
+ * `defaultUipClient` in `registry/uip/client.ts`.
  */
 /** The file's text, or `undefined` when there is none. */
 export type ReadText = (path: string) => string | undefined;

package/dist/core/read-text.js

@@ -21,6 +21,10 @@
  * `process.getBuiltinModule`, not an `import`, so the library loads no `node:` builtin
  * (FB015 exempts this fallback), and `process` is read through `globalThis`, as in
  * `core/typescript-module.ts`.
+ *
+ * The tenant calls (`registry prepare`'s `uip` runs) have a sibling slot,
+ * `globalThis[Symbol.for('uipath.maestro-builder-sdk.uip')]`, documented on
+ * `defaultUipClient` in `registry/uip/client.ts`.
  */
 const HOST_READ_TEXT = Symbol.for('uipath.maestro-builder-sdk.readText');
 /** The reader a default read uses: the host's, when one is in the slot, else the disk. */

package/dist/registry/library-build/context.js

@@ -13,7 +13,7 @@
  * a `--keep-temp` cache the Python wrote drives this code to the same bytes,
  * which is how the port is proven.
  */
-import { createHash } from "node:crypto";
+import { bytesToHex, sha256 } from "../../core/sha.js";
 import { pyJsonStringify } from "../codecs/pyjson.js";
 import { sortedByKeys } from "../compat/compare.js";
 import { isActivitiesList as isActivitiesListArgv, isConnectorsMetadata, isResourcesDescribeObject, isResourcesDescribeOperation, isResourcesList as isResourcesListArgv, registryGet as registryGetArgv, } from "../uip/commands.js";
@@ -47,7 +47,7 @@ export function fieldScope(parentFields) {
         return "";
     const pairs = sortedByKeys([...parentFields.entries()], ([k]) => k, ([, v]) => v);
     const flat = pairs.map(([k, v]) => `${k}=${v}`).join("\0");
-    return `f-${createHash("sha256").update(flat, "utf8").digest("hex").slice(0, 12)}`;
+    return `f-${bytesToHex(sha256(flat)).slice(0, 12)}`;
 }
 /** Cache file for one `flow registry get`: the node type with `.` → `_`. */
 export function registryCacheName(nodeType) {

package/dist/registry/prepare/connections.js

@@ -21,12 +21,13 @@
  * 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, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { readdirSync } 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";
 import { dataItems, failureReason, parseEnvelope } from "../uip/envelope.js";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "./staged-files.js";
 import { isPlainObject, notJsonReason, pyGet, pyOr, pyRepr, pyStrAny, pyTruthy } from "./support.js";
 /** No usable connection, with the reason and the way forward (`_connections.ConnectionError_`). */
 export class ConnectionRefusal extends Refusal {

package/dist/registry/prepare/handoff.js

@@ -13,12 +13,12 @@
  * `_unwrap_value` in `prepare_connector.py`. The text lives in `messages.ts`;
  * this module reads the generated module and parses it.
  */
-import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { relativePosix, toPosix } from "../compat/paths.js";
 import { pyStrip } from "../compat/pystr.js";
 import { isRelativeSpecifier } from "./source-import.js";
 import { descriptorUsageFallbackLines, descriptorUsageLines, descriptorUsageUnparsedLines } from "./messages.js";
+import { readFileSync } from "./staged-files.js";
 /**
  * `ConnectorValue<string>` → `string`, for the handoff skeleton. The generated
  * property type says what the field ACCEPTS — the literal or an expression —

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

@@ -30,6 +30,15 @@ export declare const PREPARE_COMMAND = "npx flow-sdk registry prepare";
 export declare function prefixed(text: string): string;
 /** `prepare-connector: next: <text>` — the last lines of a run, each one a call the reader can paste. */
 export declare function nextLine(text: string): string;
+/**
+ * The run's last line: the `registry describe` that prints the page just
+ * prepared. `overlay` is `--out` when it is not the default describe reads.
+ */
+export declare function describeNextLine(cli: string, nodeType: string, objectName?: string, overlay?: string): string;
+/** The line a refusal gains when the run had already staged files, which its progress lines may have named. */
+export declare function discardedNote(count: number): string;
+/** A write failed after the run succeeded, so the files written before it remain. */
+export declare function partialWriteMessage(path: string, reason: string): string;
 /**
  * A refusal whose message is the COMPLETE text the Python passed to
  * `sys.exit`, prefix included. Every other {@link Refusal} reaching the exit

package/dist/registry/prepare/messages.js

@@ -36,6 +36,24 @@ export function prefixed(text) {
 export function nextLine(text) {
     return prefixed(`next: ${text}`);
 }
+/**
+ * The run's last line: the `registry describe` that prints the page just
+ * prepared. `overlay` is `--out` when it is not the default describe reads.
+ */
+export function describeNextLine(cli, nodeType, objectName, overlay) {
+    const object = objectName ? ` --object ${objectName}` : "";
+    const local = overlay ? ` --connectors-local ${overlay}` : "";
+    return nextLine(`read the prepared page: ${cli} registry describe ${nodeType}${object}${local}`);
+}
+/** The line a refusal gains when the run had already staged files, which its progress lines may have named. */
+export function discardedNote(count) {
+    return `Nothing was written: the ${count} file(s) this run staged, including any reported above, were discarded.`;
+}
+/** A write failed after the run succeeded, so the files written before it remain. */
+export function partialWriteMessage(path, reason) {
+    return prefixed(`could not write ${path} (${reason}). The files written before it remain, so the overlay or bindings.json `
+        + "may be partly updated; fix the cause and run the same prepare again.");
+}
 /**
  * A refusal whose message is the COMPLETE text the Python passed to
  * `sys.exit`, prefix included. Every other {@link Refusal} reaching the exit

package/dist/registry/prepare/objects.js

@@ -31,11 +31,11 @@
  *
  * Ported from `integrations/scripts/_objects.py`; the refusal text is verbatim.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { pyJsonStringify } from "../codecs/pyjson.js";
 import { pyStrip } from "../compat/pystr.js";
 import { Refusal, messageOf } from "../errors.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "./staged-files.js";
 import { isPlainObject, pyOr, pyRepr, pySplitWhitespace, pyStrAny, pyTruthy, pyTypeName } from "./support.js";
 /**
  * Enough rows to choose from without dumping a catalog into the error. The

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

@@ -10,8 +10,14 @@ export declare function variantKey(entry: Record<string, unknown>): string;
 export declare function descriptorOverlayPath(path: string): string;
 /**
  * `_migrate_legacy_descriptor_roots`: move `<dst>/<key>/**` written by an
- * earlier `prepare` under `<dst>/descriptors/<key>/**`, bottom-up, leaving no
- * empty directory behind. Only roots the index still names are touched.
+ * earlier `prepare` under `<dst>/descriptors/<key>/**`, leaving no empty
+ * directory behind. Only roots the index still names are touched.
+ *
+ * The files are copied with the run's other writes, and only once those are
+ * written is each old file renamed over its copy and its emptied folder
+ * removed, so a refused run moves nothing. Where the file system refuses
+ * renames or deletes (Studio Web), the old files stay beside their copies;
+ * once the index names `descriptors/`, nothing reads them.
  */
 export declare function migrateLegacyDescriptorRoots(dst: string, entries: readonly unknown[]): void;
 /**

package/dist/registry/prepare/overlay.js

@@ -20,8 +20,8 @@
  * `_keep_prepared_schema` and `_lookup_specs_from_overlay` in
  * `prepare_connector.py`.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { lstatSync, readdirSync, renameSync, rmdirSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { pyJsonDocument } from "../codecs/pyjson.js";
 import { sortedByKeys, sortedStrings } from "../compat/compare.js";
 import { toPosix } from "../compat/paths.js";
@@ -30,6 +30,7 @@ import { SCHEMA_VERSION } from "../library-build/canonical.js";
 import { sidecarPath, unwrapV1Def } from "../library-reader.js";
 import { catalogReferences, loadInvariantCollections, specsFromFields } from "../lookup-specs.js";
 import { isEventNodeType } from "../model/library.js";
+import { afterWrites, existsSync, mkdirSync, readFileSync, stagedReadText, writeFileSync } from "./staged-files.js";
 import { isPlainObject, pyGet, pyOr, pyStrAny, pyTruthy, pyTypeName } from "./support.js";
 export const INDEX_FILENAME = "index.json";
 export const DESCRIPTORS_ROOT = "descriptors";
@@ -55,8 +56,14 @@ export function descriptorOverlayPath(path) {
 }
 /**
  * `_migrate_legacy_descriptor_roots`: move `<dst>/<key>/**` written by an
- * earlier `prepare` under `<dst>/descriptors/<key>/**`, bottom-up, leaving no
- * empty directory behind. Only roots the index still names are touched.
+ * earlier `prepare` under `<dst>/descriptors/<key>/**`, leaving no empty
+ * directory behind. Only roots the index still names are touched.
+ *
+ * The files are copied with the run's other writes, and only once those are
+ * written is each old file renamed over its copy and its emptied folder
+ * removed, so a refused run moves nothing. Where the file system refuses
+ * renames or deletes (Studio Web), the old files stay beside their copies;
+ * once the index names `descriptors/`, nothing reads them.
  */
 export function migrateLegacyDescriptorRoots(dst, entries) {
     const legacyRoots = new Set();
@@ -71,27 +78,74 @@ export function migrateLegacyDescriptorRoots(dst, entries) {
             legacyRoots.add(parts[0]);
     }
     for (const legacyRoot of sortedStrings(legacyRoots)) {
-        const sourceRoot = join(dst, legacyRoot);
-        if (!existsSync(sourceRoot) || !statSync(sourceRoot).isDirectory())
+        const sourceRoot = legacyRootDir(dst, legacyRoot);
+        if (sourceRoot === undefined)
             continue;
-        const destinationRoot = join(dst, DESCRIPTORS_ROOT, legacyRoot);
-        const walk = (dir) => {
-            const children = readdirSync(dir, { withFileTypes: true });
-            const subdirs = children.filter((c) => c.isDirectory()).map((c) => c.name);
-            // `os.walk(topdown=False)`: the children are handled before their parent.
-            for (const name of subdirs)
-                walk(join(dir, name));
-            const destination = join(destinationRoot, toPosix(dir.slice(sourceRoot.length)).replace(/^\//, ""));
+        const moved = [];
+        // Dirent types do not follow symlinks, so a linked file or folder is neither and is skipped.
+        const walk = (dir, destination) => {
             mkdirSync(destination, { recursive: true });
-            for (const child of children) {
-                if (child.isFile())
-                    renameSync(join(dir, child.name), join(destination, child.name));
+            for (const child of readdirSync(dir, { withFileTypes: true })) {
+                if (child.isDirectory())
+                    walk(join(dir, child.name), join(destination, child.name));
+                else if (child.isFile()) {
+                    writeFileSync(join(destination, child.name), readFileSync(join(dir, child.name)));
+                    moved.push([join(dir, child.name), join(destination, child.name)]);
+                }
             }
-            for (const name of subdirs)
-                rmdirSync(join(dir, name));
         };
-        walk(sourceRoot);
-        rmdirSync(sourceRoot);
+        walk(sourceRoot, join(dst, DESCRIPTORS_ROOT, legacyRoot));
+        afterWrites(() => moveOver(sourceRoot, moved));
+    }
+}
+/** A connector key as the legacy layout named its folder: one plain path segment. */
+const LEGACY_ROOT = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+/**
+ * `<dst>/<legacyRoot>`, or `undefined` unless it is a real folder strictly
+ * inside `dst`. The name comes from `index.json`, a project file anyone with
+ * the project can edit, so `..` or a link must not reach the files beside the
+ * overlay.
+ */
+function legacyRootDir(dst, legacyRoot) {
+    if (!LEGACY_ROOT.test(legacyRoot))
+        return undefined;
+    const root = resolve(dst, legacyRoot);
+    const inside = relative(resolve(dst), root);
+    if (inside === "" || inside.startsWith("..") || isAbsolute(inside))
+        return undefined;
+    try {
+        const stat = lstatSync(root);
+        return stat.isDirectory() && !stat.isSymbolicLink() ? root : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Rename each copied file over its copy, then remove the folders between it
+ * and `root` once empty, deepest first. Only these files and folders: anything
+ * added to the old tree since the copy stays where it is.
+ */
+function moveOver(root, moved) {
+    try {
+        for (const [source, destination] of moved)
+            renameSync(source, destination);
+    }
+    catch {
+        return; // refused (Studio Web): the old files stay beside their copies
+    }
+    const folders = new Set();
+    for (const [source] of moved) {
+        for (let folder = dirname(source); folder.startsWith(root); folder = dirname(folder))
+            folders.add(folder);
+    }
+    for (const folder of [...folders].sort((a, b) => b.length - a.length)) {
+        try {
+            rmdirSync(folder);
+        }
+        catch {
+            // not empty, or refused: it stays
+        }
     }
 }
 function sortKey(entry, key) {
@@ -463,7 +517,7 @@ export function lookupSpecsFromOverlay(out, nodeType, objectName) {
     const entries = isPlainObject(index) ? pyGet(index, "entries", []) : [];
     if (!Array.isArray(entries))
         return new Map();
-    const invariant = loadInvariantCollections(out);
+    const invariant = loadInvariantCollections(out, stagedReadText());
     for (const row of entries) {
         if (!isPlainObject(row) || row.nodeType !== nodeType)
             continue;

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

@@ -53,8 +53,8 @@ export interface PreparePorts {
     /** The project root the Python read as `Path.cwd()`. Defaults to the process's. */
     cwd?: string;
     timeoutMs?: number;
-    /** How the pasteable `registry prepare` is spelled in the notes. */
-    prepareCommand?: string;
+    /** How the CLI is spelled in the pasteable commands; defaults to {@link cliSpelling}. */
+    cli?: string;
 }
 /**
  * Where prepare writes its overlay when `--out` is not given, as shown to the
@@ -102,10 +102,13 @@ export declare function matchCatalogObject(ctx: BuildContext, connectorKey: stri
  * command PICKED and finds nothing, the other enabled connections for the
  * connector are probed, and the run starts over pinned to the one that
  * resolves everything (flow-builder-sdk#744). The Python re-exec'd itself for
- * that; here the bindings snapshot is restored and `prepareConnector` is
- * re-entered with `--connection-id <winner> --refresh-lookups`. The refresh is
+ * that; here the bindings snapshot is restored and the run starts over, inside
+ * the same held writes, with `--connection-id <winner> --refresh-lookups`. The refresh is
  * NOT optional: the ledger keys a resolution by `[nodeType, field, by, value]`
  * and not by connection, so an id recorded against the connection just
  * abandoned would come back as "already resolved" on the re-run.
+ *
+ * Nothing reaches the disk until the whole command, re-run included, has
+ * succeeded; a refusal writes nothing (`staged-files.ts`).
  */
 export declare function prepareConnector(options: PrepareOptions, ports: PreparePorts): Promise<PrepareReport>;

package/dist/registry/prepare/pipeline.js

@@ -24,9 +24,9 @@
  * into the lines verbatim, as `args.out` and `args.bindings` did — while the
  * file system is reached through paths resolved against `cwd`.
  */
-import { existsSync, readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { GUID_RE } from "../../core/binding-messages.js";
+import { cliSpelling } from "../../core/cli-spelling.js";
 import { PACKAGE_NAME } from "../../package-name.js";
 import { afterLast } from "../compat/pystr.js";
 import { extractCanonical, isHttpPassthrough, nodeOf } from "../library-build/canonical.js";
@@ -41,7 +41,7 @@ import { prepareEvent } from "./event.js";
 import { integrationServiceEntry } from "./integration-service.js";
 import { descriptorUsage } from "./handoff.js";
 import { ResolutionsExhausted, allParentsResolved, resolvedParentValues, writeResolutions } from "./ledger.js";
-import { PREPARE_COMMAND, PrepareRefusal, ambiguousLabelsMessage, connectionChoiceLine, bindingsLine, bpmnConnectorUsageLines, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, flagDiffersFromSourceLine, keptSchemaMessage, labelTakenMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedFromIntegrationServiceLine, actionCanonicalizedLine, catalogRefreshFailedLine, refreshingCatalogLine, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, registryGetFailedMessage, sharedLabelMessage, sourceLabelSuffix, tsNote, partlyUnreadableLabelLine, unreadableLabelLine, unresolvedOperationMessage, } from "./messages.js";
+import { PrepareRefusal, ambiguousLabelsMessage, connectionChoiceLine, bindingsLine, bpmnConnectorUsageLines, candidateLabel, connectionLine, describeNextLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, flagDiffersFromSourceLine, keptSchemaMessage, labelTakenMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedFromIntegrationServiceLine, actionCanonicalizedLine, catalogRefreshFailedLine, refreshingCatalogLine, 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";
@@ -50,6 +50,7 @@ import { retryOtherConnections } from "./retry.js";
 import { repointSource } from "./source-import.js";
 import { sourceBindingLabels } from "./source-labels.js";
 import { isPlainObject, pyGet, pyOr, pyPathJoin, pyPathlibStr, pyStrAny, pyTruthy } from "./support.js";
+import { existsSync, readFileSync, stagedWrites } from "./staged-files.js";
 import { workPath } from "../../workdir.js";
 /**
  * Where prepare writes its overlay when `--out` is not given, as shown to the
@@ -119,7 +120,7 @@ export async function matchCatalogObject(ctx, connectorKey, wanted, verb) {
 function chooseLabels(options, ports) {
     const info = (line) => ports.reporter.info(line);
     const warn = (line) => ports.reporter.warn(line);
-    const command = ports.prepareCommand ?? PREPARE_COMMAND;
+    const command = `${ports.cli ?? cliSpelling()} registry prepare`;
     const labels = sourceBindingLabels({
         cwd: ports.cwd ?? process.cwd(),
         out: options.out ?? defaultOverlayOut(ports.cwd ?? process.cwd()),
@@ -263,13 +264,19 @@ async function connect(options, ports) {
  * command PICKED and finds nothing, the other enabled connections for the
  * connector are probed, and the run starts over pinned to the one that
  * resolves everything (flow-builder-sdk#744). The Python re-exec'd itself for
- * that; here the bindings snapshot is restored and `prepareConnector` is
- * re-entered with `--connection-id <winner> --refresh-lookups`. The refresh is
+ * that; here the bindings snapshot is restored and the run starts over, inside
+ * the same held writes, with `--connection-id <winner> --refresh-lookups`. The refresh is
  * NOT optional: the ledger keys a resolution by `[nodeType, field, by, value]`
  * and not by connection, so an id recorded against the connection just
  * abandoned would come back as "already resolved" on the re-run.
+ *
+ * Nothing reaches the disk until the whole command, re-run included, has
+ * succeeded; a refusal writes nothing (`staged-files.ts`).
  */
-export async function prepareConnector(options, ports) {
+export function prepareConnector(options, ports) {
+    return stagedWrites(() => prepareOrRetry(options, ports));
+}
+async function prepareOrRetry(options, ports) {
     const info = (line) => ports.reporter.info(line);
     const warn = (line) => ports.reporter.warn(line);
     // Whether the CALLER chose the connection, recorded before discovery answers
@@ -324,7 +331,7 @@ export async function prepareConnector(options, ports) {
         // The labels this run chose ride along as flags, so the re-entry binds under
         // the same names instead of deriving them again.
         const labels = connected.bound ? { bindConnection: connected.bound.connection, bindFolder: connected.bound.folder } : {};
-        return prepareConnector({ ...options, ...labels, connectionId: chosenId, refreshLookups: true }, ports);
+        return prepareOrRetry({ ...options, ...labels, connectionId: chosenId, refreshLookups: true }, ports);
     }
 }
 /**
@@ -336,7 +343,8 @@ async function prepareOnConnection(options, ports, connected, registryRefresh) {
     const cwd = ports.cwd ?? process.cwd();
     const info = (line) => ports.reporter.info(line);
     const warn = (line) => ports.reporter.warn(line);
-    const command = ports.prepareCommand ?? PREPARE_COMMAND;
+    const cli = ports.cli ?? cliSpelling();
+    const command = `${cli} registry prepare`;
     const { connectorKey } = options;
     // Rebound to the activity's own action id when Integration Service supplies
     // the entry, so the overlay path, the summary and the handoff all spell the
@@ -349,6 +357,7 @@ async function prepareOnConnection(options, ports, connected, registryRefresh) {
     const importSpecifier = options.importSpecifier ?? PACKAGE_NAME;
     const jsonOnly = options.jsonOnly ?? false;
     const { connectionId, bound, rollback } = connected;
+    const describeOverlay = out === resolve(cwd, defaultOverlayOut(cwd)) ? undefined : outShown;
     const ctx = createBuildContext({ client: ports.client, caches: ports.caches ?? memoryCaches(), reporter: ports.reporter, concurrency: 1, timeoutMs: ports.timeoutMs }, { connectionId, parentFields });
     let nodeType = `uipath.connector.${connectorKey}.${action}`;
     let fromIntegrationService;
@@ -376,6 +385,7 @@ async function prepareOnConnection(options, ports, connected, registryRefresh) {
             prepareCommand: command,
         });
         if (!("missed" in event)) {
+            info(describeNextLine(cli, event.eventNodeType, event.objectName, describeOverlay));
             return { kind: "event", nodeType: event.eventNodeType, connectionId, bound, objectName: event.objectName };
         }
         const probes = [actionProbe.miss, event.missed];
@@ -574,5 +584,6 @@ async function prepareOnConnection(options, ports, connected, registryRefresh) {
         for (const line of usage)
             info(nextLine(line));
     }
+    info(describeNextLine(cli, nodeType, options.allObjects ? "<object>" : objectName, describeOverlay));
     return { kind: "action", nodeType, connectionId, bound, variants, inputFields, kept, objectName };
 }

package/dist/registry/prepare/regenerate.js

@@ -18,12 +18,12 @@
  * `generate_connectors_ts.py --library <out> --output <out>`; the generator is
  * now `renderDescriptorModules`, called in-process.
  */
-import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { Refusal } from "../errors.js";
 import { formatRequiredInputGaps, renderDescriptorModules } from "../generators/descriptors.js";
 import { loadLibrary } from "../library-reader.js";
 import { overlayHasGenericExpanded } from "./overlay.js";
+import { mkdirSync, stagedReadText, writeFileSync } from "./staged-files.js";
 /**
  * Write `<out>/<connectorKey>.ts` for every connector in the overlay and
  * return the module names written; nothing at all under `--json-only`.
@@ -35,7 +35,7 @@ import { overlayHasGenericExpanded } from "./overlay.js";
 export function regenerateDescriptors(out, importSpecifier, jsonOnly = false) {
     if (jsonOnly)
         return [];
-    const library = loadLibrary(out);
+    const library = loadLibrary(out, stagedReadText());
     const output = renderDescriptorModules(library, {
         importSpecifier,
         includeGenericExpanded: overlayHasGenericExpanded(out),

package/dist/registry/prepare/source-import.js

@@ -19,13 +19,14 @@
  * Ported from `_IMPORT_RE`, `_resolves_to`, `_sources_importing`,
  * `_repoint_import` and `_repoint_source` in `prepare_connector.py`.
  */
-import { readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
+import { readdirSync, realpathSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { compareCodePoints } from "../compat/compare.js";
 import { relativePosix } from "../compat/paths.js";
 import { workPath } from "../../workdir.js";
 import { isFile } from "../files.js";
 import { repointedLine, severalSourcesLine, sourceNotAFileLine } from "./messages.js";
+import { existsSync, readFileSync, writeFileSync } from "./staged-files.js";
 /**
  * `import … from "<specifier>"` — the specifier is group 3, quotes preserved.
  * Anchored to a real import statement on purpose (see the module comment).
@@ -180,9 +181,10 @@ export function repointImport(source, baked, prepared) {
  */
 export function repointSource(options) {
     const cwd = options.cwd ?? process.cwd();
-    const prepared = canonicalPath(resolve(cwd, options.out, `${options.connectorKey}.ts`));
-    if (options.noSourceRewrite || !isFile(prepared))
+    const module = resolve(cwd, options.out, `${options.connectorKey}.ts`);
+    if (options.noSourceRewrite || !existsSync(module))
         return [];
+    const prepared = canonicalPath(module);
     const root = canonicalPath(cwd);
     // Where `registry pull` put the module: `.flow-sdk/connectors/`, or a legacy `connectors/`.
     const baked = canonicalPath(join(workPath("connectors", { cwd: root }), `${options.connectorKey}.ts`));

package/dist/registry/prepare/staged-files.d.ts

@@ -0,0 +1,21 @@
+import { type ReadText } from "../../core/read-text.js";
+/**
+ * Run `work` with its writes held, then write them all, or none when it throws.
+ * One run at a time per process: the held files are process-wide, so a second
+ * run started before the first ends is refused rather than mixed into it.
+ */
+export declare function stagedWrites<T>(work: () => Promise<T>): Promise<T>;
+/** Run `step` once the held files are written: at once outside a run, never for a run that throws. */
+export declare function afterWrites(step: () => void): void;
+export declare function writeFileSync(path: string, content: string | Uint8Array, encoding?: "utf8"): void;
+/** A held file's parent is made when it is written, so there is nothing to make yet. */
+export declare function mkdirSync(path: string, options: {
+    recursive: true;
+}): void;
+export declare function existsSync(path: string): boolean;
+export declare function readFileSync(path: string): Uint8Array;
+export declare function readFileSync(path: string, encoding: "utf8"): string;
+/** Drops a held file; only outside a run does it reach the disk. */
+export declare function rmSync(path: string): void;
+/** The library reader `loadLibrary` takes, seeing held files first. */
+export declare function stagedReadText(): ReadText;

package/dist/registry/prepare/staged-files.js

@@ -0,0 +1,110 @@
+/**
+ * `prepare`'s file writes, held in memory until the run has succeeded.
+ *
+ * Studio Web's project file system refuses deletes, and so renames, which
+ * rules out both ways a failed run used to be cleaned up: writing a scratch
+ * copy and swapping it in, and removing what a refusal left behind. Instead
+ * the prepare modules read and write through these functions. While
+ * {@link stagedWrites} runs, a write lands in memory and a later read in the
+ * same run sees it; when the run resolves, each file is written once, with a
+ * plain write. A run that throws writes nothing.
+ *
+ * Outside {@link stagedWrites} every function is the `node:fs` one, so a
+ * helper called on its own (the tests, `mergeInto`) writes at once as before.
+ */
+import * as fs from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { defaultReadText } from "../../core/read-text.js";
+import { Refusal, messageOf } from "../errors.js";
+import { PrepareRefusal, discardedNote, partialWriteMessage } from "./messages.js";
+let pending;
+let afterwards = [];
+/**
+ * Run `work` with its writes held, then write them all, or none when it throws.
+ * One run at a time per process: the held files are process-wide, so a second
+ * run started before the first ends is refused rather than mixed into it.
+ */
+export async function stagedWrites(work) {
+    if (pending !== undefined) {
+        throw new Error("registry prepare is already running in this process; run one prepare at a time, and wait for it to end before the next.");
+    }
+    const files = new Map();
+    pending = files;
+    const then = [];
+    afterwards = then;
+    let result;
+    try {
+        result = await work();
+    }
+    catch (error) {
+        if (error instanceof Refusal && files.size > 0)
+            error.message += `\n${discardedNote(files.size)}`;
+        throw error;
+    }
+    finally {
+        pending = undefined;
+    }
+    // An index written before a failed write would name descriptors that are not there.
+    const indexLast = [...files].sort(([a], [b]) => Number(basename(a) === "index.json") - Number(basename(b) === "index.json"));
+    for (const [path, content] of indexLast) {
+        try {
+            fs.mkdirSync(dirname(path), { recursive: true });
+            fs.writeFileSync(path, content);
+        }
+        catch (error) {
+            throw new PrepareRefusal(partialWriteMessage(path, messageOf(error)), "PREPARE_WRITE_FAILED");
+        }
+    }
+    for (const step of then)
+        step();
+    return result;
+}
+/** Run `step` once the held files are written: at once outside a run, never for a run that throws. */
+export function afterWrites(step) {
+    if (pending !== undefined)
+        afterwards.push(step);
+    else
+        step();
+}
+function held(path) {
+    return pending?.get(resolve(path));
+}
+export function writeFileSync(path, content, encoding) {
+    if (pending !== undefined)
+        pending.set(resolve(path), content);
+    else
+        fs.writeFileSync(path, content, encoding);
+}
+/** A held file's parent is made when it is written, so there is nothing to make yet. */
+export function mkdirSync(path, options) {
+    if (pending === undefined)
+        fs.mkdirSync(path, options);
+}
+export function existsSync(path) {
+    return held(path) !== undefined || fs.existsSync(path);
+}
+export function readFileSync(path, encoding) {
+    const content = held(path);
+    if (content === undefined)
+        return encoding === undefined ? fs.readFileSync(path) : fs.readFileSync(path, encoding);
+    if (encoding === undefined)
+        return typeof content === "string" ? new TextEncoder().encode(content) : content;
+    return typeof content === "string" ? content : new TextDecoder().decode(content);
+}
+/** Drops a held file; only outside a run does it reach the disk. */
+export function rmSync(path) {
+    if (pending !== undefined)
+        pending.delete(resolve(path));
+    else
+        fs.rmSync(path);
+}
+/** The library reader `loadLibrary` takes, seeing held files first. */
+export function stagedReadText() {
+    const read = defaultReadText();
+    return (path) => {
+        const content = held(path);
+        if (content === undefined)
+            return read(path);
+        return typeof content === "string" ? content : new TextDecoder().decode(content);
+    };
+}

package/dist/registry/uip/client.d.ts

@@ -109,6 +109,24 @@ export declare class OfflineUipClient implements UipClient {
  * ask for with `host` (see `host.ts`): every call then spawns its own `uip`,
  * which is how the registry ran before flow-builder-sdk#965 and the shape to
  * compare against when a prepare misbehaves.
+ *
+ * A host that cannot start a process (Studio Web runs the SDK's CLI in a
+ * sandbox with no `child_process`), and so cannot pass a client in, hands one
+ * over before the run: `globalThis[Symbol.for('uipath.maestro-builder-sdk.uip')]
+ * = client`, an object with the {@link UipClient} shape. Its `run(argv, options)`
+ * gets the argv `uip` would (`argv[0]` is `"uip"`) and resolves a {@link UipResult}
+ * — `code` 0 and the JSON envelope on `stdout` for a success, as the CLI prints
+ * it. The argv carries the author's values (`-f`, `--resolve`), so a host
+ * hands it to the CLI as an array and never through a shell. A rejection or a
+ * malformed answer reads as a failed run (`code` 1, the reason on `stderr`),
+ * and a call past its `timeoutMs` as a timed-out one. It answers every call in
+ * place of a spawned `uip`, `host` and `FLOW_SDK_UIP_HOST` included, and no
+ * `node:child_process` is loaded. Calls can
+ * overlap: the library builder runs several at once. `registry prepare` calls
+ * `close()`, if it has one, when it ends, and nothing else does, so a client
+ * that outlives the command leaves `close` out. `UIP_REPLAY_DIR` still wins over it, so a replay
+ * never reaches the tenant, and `UIP_RECORD_DIR` records what it answers. This is
+ * the tenant's counterpart of the library's `readText` slot (`core/read-text.ts`).
  */
 export declare function defaultUipClient(options?: UipRunOptions & {
     host?: HostUipClientOptions | boolean;

package/dist/registry/uip/client.js

@@ -210,6 +210,59 @@ export class OfflineUipClient {
         };
     }
 }
+const HOST_UIP = Symbol.for("uipath.maestro-builder-sdk.uip");
+/** A call the slot's client could not answer, read like a failed run. */
+function slotFailure(reason) {
+    return { code: 1, signal: null, stdout: "", stderr: `uip slot: ${reason}`, timedOut: false };
+}
+/** Why `answer` is not a {@link UipResult}, or `undefined` when it is one. */
+function notAResult(answer) {
+    if (answer === null || typeof answer !== "object")
+        return `answered ${answer === null ? "null" : typeof answer}, not a result object`;
+    const { code, stdout, stderr } = answer;
+    if (typeof code !== "number")
+        return `answered a result whose code is ${typeof code}, not a number`;
+    if (typeof stdout !== "string" || typeof stderr !== "string")
+        return "answered a result whose stdout or stderr is not a string";
+    return undefined;
+}
+/**
+ * The host's client in the slot, held to the contract the spawning client
+ * keeps: a timeout is enforced, and a rejection or a malformed answer is a
+ * failed run, never a throw.
+ */
+class SlotUipClient {
+    hosted;
+    defaults;
+    constructor(hosted, defaults) {
+        this.hosted = hosted;
+        this.defaults = defaults;
+    }
+    async run(argv, options = {}) {
+        const answer = Promise.resolve()
+            .then(() => this.hosted.run(argv, options))
+            .then((result) => {
+            const reason = notAResult(result);
+            return reason === undefined ? result : slotFailure(reason);
+        }, (error) => slotFailure(`the call failed: ${error instanceof Error ? error.message : String(error)}`));
+        const timeoutMs = options.timeoutMs ?? this.defaults.timeoutMs;
+        if (timeoutMs === undefined || timeoutMs <= 0)
+            return answer;
+        let timer;
+        const expired = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({ code: null, signal: null, stdout: "", stderr: `uip slot: no answer within ${timeoutMs} ms`, timedOut: true }), timeoutMs);
+        });
+        try {
+            return await Promise.race([answer, expired]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    close() {
+        this.hosted.close?.();
+    }
+}
 /**
  * The client a verb should use, honouring the recording and replay switches.
  *
@@ -237,12 +290,39 @@ export class OfflineUipClient {
  * ask for with `host` (see `host.ts`): every call then spawns its own `uip`,
  * which is how the registry ran before flow-builder-sdk#965 and the shape to
  * compare against when a prepare misbehaves.
+ *
+ * A host that cannot start a process (Studio Web runs the SDK's CLI in a
+ * sandbox with no `child_process`), and so cannot pass a client in, hands one
+ * over before the run: `globalThis[Symbol.for('uipath.maestro-builder-sdk.uip')]
+ * = client`, an object with the {@link UipClient} shape. Its `run(argv, options)`
+ * gets the argv `uip` would (`argv[0]` is `"uip"`) and resolves a {@link UipResult}
+ * — `code` 0 and the JSON envelope on `stdout` for a success, as the CLI prints
+ * it. The argv carries the author's values (`-f`, `--resolve`), so a host
+ * hands it to the CLI as an array and never through a shell. A rejection or a
+ * malformed answer reads as a failed run (`code` 1, the reason on `stderr`),
+ * and a call past its `timeoutMs` as a timed-out one. It answers every call in
+ * place of a spawned `uip`, `host` and `FLOW_SDK_UIP_HOST` included, and no
+ * `node:child_process` is loaded. Calls can
+ * overlap: the library builder runs several at once. `registry prepare` calls
+ * `close()`, if it has one, when it ends, and nothing else does, so a client
+ * that outlives the command leaves `close` out. `UIP_REPLAY_DIR` still wins over it, so a replay
+ * never reaches the tenant, and `UIP_RECORD_DIR` records what it answers. This is
+ * the tenant's counterpart of the library's `readText` slot (`core/read-text.ts`).
  */
 export function defaultUipClient(options = {}) {
     const { replay, record } = uipSwitches();
     if (replay)
         return new ReplayUipClient(replay);
     const { host, ...runOptions } = options;
+    const hosted = globalThis[HOST_UIP];
+    if (hosted !== undefined && hosted !== null) {
+        if (typeof hosted.run !== "function") {
+            throw new Error("globalThis[Symbol.for('uipath.maestro-builder-sdk.uip')] holds no uip client: it needs a " +
+                "run(argv, options) method that resolves { code, stdout, stderr }.");
+        }
+        const slot = new SlotUipClient(hosted, runOptions);
+        return record ? new RecordingUipClient(slot, record) : slot;
+    }
     const spawning = new SpawnUipClient(runOptions);
     // One `uip mcp serve` for the command's whole chain of calls, where the
     // caller asked for it and the operator has not switched it off. Serial, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.45.1",
+  "version": "6.46.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -93,5 +93,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "f8fe049e27996a1862ea9ce5c48507b15b6178d0"
+  "gitref": "b61f819d0271c38d3231a0183daeb2a5f880f9a4"
 }