@uipath/maestro-builder-sdk 6.31.2 → 6.31.4

package/dist/decompile-cli.js

@@ -117,6 +117,23 @@ const BASELINE = ${JSON.stringify(join(base + '.baseline', basename(base) + '.fl
 const EDITED   = ${JSON.stringify(join(base + '.edited', basename(base) + '.flow'))};
 const MERGED   = ${JSON.stringify(base + '.merged.flow')};
 
+// Options. \`--strict\` goes to step 2's merge: refuse, writing nothing, when the
+// no-edit round trip (BASELINE) differs from ORIGINAL anywhere, instead of
+// warning and writing. An unknown option stops the run: silently ignoring one
+// would run a merge the caller did not ask for.
+const USAGE = 'usage: node ' + ${JSON.stringify(basename(pipelinePath))} + ' [--strict]';
+const argv = process.argv.slice(2);
+if (argv.includes('-h') || argv.includes('--help')) {
+  console.log(USAGE + '\\n  --strict  merge refuses (exit 1, nothing written) when the no-edit round trip differs from the original');
+  process.exit(0);
+}
+const unknown = argv.find((a) => a !== '--strict');
+if (unknown !== undefined) {
+  console.error(${JSON.stringify(basename(pipelinePath))} + ': unknown option ' + JSON.stringify(unknown) + '\\n' + USAGE);
+  process.exit(2);
+}
+const STRICT = argv.includes('--strict');
+
 // Ensure the decompiled source exists (a fresh clone may have only the .flow).
 if (!existsSync(TS)) run('decompile', [ORIGINAL, '-o', TS, '--no-pipeline']);
 
@@ -128,14 +145,6 @@ if (!existsSync(BASELINE)) {
   console.log('\\n>>> Baseline captured. Now EDIT ' + ${JSON.stringify(basename(tsPath))} + ', then re-run this script to compile + merge.');
 } else {
   // ── Step 2: compile your edits, then merge them back into the original. ──
-  mkdirSync(dirname(EDITED), { recursive: true });
-  run('compile', [TS, '-o', EDITED, '--no-check']);
-
-  // ── DIFF GATE (seam) ──────────────────────────────────────────────────────
-  // A future step can diff ORIGINAL vs the about-to-be-written MERGED here and
-  // ask for confirmation before the write. Left as a no-op for now.
-  // ---------------------------------------------------------------------------
-
   // \`merge <edited> --original <original>\` is the grammar; the positional
   // \`merge <original> <edited>\` pair is deprecated. A \`uip\` from before
   // UiPath/cli#4526 knows only the pair, so ask its \`merge --help\` first.
@@ -144,10 +153,27 @@ if (!existsSync(BASELINE)) {
   const mergeHelp = frontDoor.via === 'uip'
     ? spawnSync(frontDoor.file, [...frontDoor.prefix, 'merge', '--help'], { encoding: 'utf8' })
     : undefined;
-  const namedOriginal = mergeHelp === undefined
-    || \`\${mergeHelp.stdout ?? ''}\${mergeHelp.stderr ?? ''}\`.includes('--original');
+  const mergeHelpText = mergeHelp === undefined ? undefined : \`\${mergeHelp.stdout ?? ''}\${mergeHelp.stderr ?? ''}\`;
+  const namedOriginal = mergeHelpText === undefined || mergeHelpText.includes('--original');
+  // A \`uip\` from before \`merge --strict\` existed would reject the flag with a
+  // bare "unknown option"; name the remedy instead, and never drop the flag.
+  // Both checks run before the compile, so a run that cannot merge does no work.
+  if (STRICT && mergeHelpText !== undefined && !mergeHelpText.includes('--strict')) {
+    console.error(${JSON.stringify(basename(pipelinePath))} + ': --strict was asked for, but this uip has no \`maestro flow merge --strict\`. '
+      + 'Update uip, or run without --strict.');
+    process.exit(2);
+  }
+  mkdirSync(dirname(EDITED), { recursive: true });
+  run('compile', [TS, '-o', EDITED, '--no-check']);
+
+  // ── DIFF GATE (seam) ──────────────────────────────────────────────────────
+  // A future step can diff ORIGINAL vs the about-to-be-written MERGED here and
+  // ask for confirmation before the write. Left as a no-op for now.
+  // ---------------------------------------------------------------------------
+
   const args = namedOriginal ? [EDITED, '--original', ORIGINAL, '-o', MERGED] : [ORIGINAL, EDITED, '-o', MERGED];
   if (existsSync(BASELINE)) args.push('--baseline', BASELINE);
+  if (STRICT) args.push('--strict');
   run('merge', args);
   console.log('\\n>>> Wrote ' + ${JSON.stringify(base + '.merged.flow')}
     + '. Replace the original with it, together with every <source>/ file merge reports writing beside it,'

package/dist/decompile.js

@@ -2132,8 +2132,10 @@ function droppedEdgeMessage(e) {
  */
 function droppedEdgesSeg(node, ctx) {
     const dropped = ctx.graph.outEdges(node.id).filter((e) => !ctx.graph.accounted.has(e));
-    if (dropped.length === 0)
-        return undefined;
+    return dropped.length === 0 ? undefined : dropEdges(dropped, ctx);
+}
+/** Account `dropped` as dropped: warn each once, remember it for strict mode, and return the site's `/* TODO *\/`. */
+function dropEdges(dropped, ctx) {
     for (const e of dropped) {
         ctx.graph.accounted.add(e);
         runDropped.push(e);
@@ -2200,11 +2202,12 @@ function commonPostDominator(targets, ipdom) {
  * decompiles to that `.parallel(...)`, then the region continues from the
  * merge's output (flow-builder-sdk#1155).
  *
- * Every edge in `edges` is accounted (edge accounting, #1125): the fold
- * recreates each one. A fork whose arms never meet at a merge node has no
- * builder spelling. Like the same shape mid-flow (`region`), it throws under
- * `bestEffort: false`, and otherwise keeps the first arm behind a
- * `TODO: unstructured fan-out` marker, which is what reports the other edges.
+ * When the arms meet at a merge node, every edge in `edges` is accounted
+ * (edge accounting, #1125): the fold recreates each one. A fork whose arms
+ * never meet at a merge node has no builder spelling. Like the same shape
+ * mid-flow (`region`), it throws under `bestEffort: false`, and otherwise keeps
+ * the first arm behind a `TODO: unstructured fan-out` marker. Only the kept
+ * first edge is accounted; the others are reported as dropped at the marker.
  */
 function forkRegion(edges, stop, scope, ipdom, ctx, refInto) {
     if (edges.length <= 1)
@@ -2215,10 +2218,10 @@ function forkRegion(edges, stop, scope, ipdom, ctx, refInto) {
     if (join === undefined || join === stop || joinNode?.type !== T.merge) {
         if (ctx.o.bestEffort === false)
             throw new Error(`decompile: unstructured fan-out (${edges.length} edges).`);
-        for (const e of edges)
-            ctx.graph.accounted.add(e);
+        ctx.graph.accounted.add(edges[0]);
         return [
             `/* TODO: unstructured fan-out (${commentText(edges.length)} edges) */`,
+            dropEdges(edges.slice(1), ctx),
             ...region(targets[0], stop, scope, ipdom, ctx, refInto),
         ];
     }
@@ -2617,13 +2620,11 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
             cursor = fork.next.cursor;
             continue;
         }
-        // Unstructured fan-out we can't fold — best-effort marker. Its successor
-        // edges are what the marker reports, so they are not reported twice.
+        // Unstructured fan-out we can't fold — best-effort marker.
+        // No successor is walked: leave the edges unaccounted so `flagDropped` names each.
         if (ctx.o.bestEffort === false)
             throw new Error(`decompile: unstructured fan-out at "${node.id}".`);
         segs.push(`/* TODO: unstructured fan-out at ${commentText(node.id)} (${commentText(succ.length)} successors) */`);
-        for (const t of succ)
-            follow(ctx.graph, node.id, t);
         flagDropped(node, ctx, segs);
         return segs;
     }

package/dist/flow-sdk.d.ts

@@ -479,8 +479,12 @@ export interface ReturnOptions extends NodeOptions {
  * Loop-specific options. Every `.loop()` emits the loop's v2.4 definition (the
  * version the registry serves: inner `start`/`continue`/`break` handles, and a
  * 1-based `currentIteration` output). The legacy 1.0.0 shape is emitted only for
- * an explicit `{ version: '1.0.0' }`, and that combined with any of these options
- * fails compilation: that definition cannot express them.
+ * an explicit `{ version: '1.0.0' }`. That definition declares `parallel` but no
+ * `completionCondition`, no `breakEnabled` and no `break` handle, so either of
+ * those options, or a `b.break()` in the body, fails `check` and compilation
+ * (`LOOP_VERSION_UNSUPPORTED`). `parallel: true` on 1.0.0 compiles, to round-trip
+ * a canvas loop, but `check` warns (`LOOP_PARALLEL_LEGACY`): that version is not
+ * confirmed to run iterations in parallel. `b.continue()` works on both versions.
  */
 export interface LoopOptions extends NodeOptions {
     /** Run iterations in parallel instead of sequentially. */

package/dist/loop-version.d.ts

@@ -0,0 +1,41 @@
+import type { LoopOptions, Step } from './flow-sdk.js';
+/** The wire type of `.loop()`. */
+export declare const LOOP_NODE_TYPE = "core.logic.loop";
+/** The `core.logic.loop` version `.loop()` emits unless `{ version }` pins another. */
+export declare const LOOP_DEFAULT_VERSION = "2.4";
+/** The version `.loop()` emits for these options. */
+export declare function loopVersion(options: LoopOptions | undefined): string;
+/**
+ * True when this loop version's body runs from the inner `start` handle and goes
+ * back through `continue` (2.x); false for the legacy `output`/`loopBack` shape.
+ * A version with no bundled definition counts as 2.x; its lookup fails later.
+ */
+export declare function loopHasInnerHandles(version: string): boolean;
+/**
+ * The features this loop uses that its version's definition cannot express, in
+ * a fixed order (`parallel`, `completionCondition`, `breakEnabled`, `break()`).
+ * Empty when all are supported, or when no definition is bundled for the version
+ * (an unknown version is reported elsewhere, by the definition lookup).
+ */
+export declare function unsupportedLoopFeatures(options: LoopOptions | undefined, usesBreak: boolean): string[];
+/**
+ * The refusal for a loop whose options or body need a definition the requested
+ * version does not have, or `undefined` when there is nothing to refuse.
+ * `serialize` throws it; `check` reports it as `LOOP_VERSION_UNSUPPORTED` with
+ * the same text, so the author reads one message in both places.
+ */
+export declare function loopVersionRefusal(name: string, options: LoopOptions | undefined, usesBreak: boolean): string | undefined;
+/**
+ * The warning for `parallel: true` on a 1.0.0 loop, or `undefined`. The 1.0.0
+ * definition declares the input, so the loop compiles and a canvas 1.0.0 loop
+ * round-trips; whether the 1.0.0 runtime runs its iterations in parallel is not
+ * confirmed, so a new loop that needs that should use the default version.
+ * `check` reports it as `LOOP_PARALLEL_LEGACY`.
+ */
+export declare function loopParallelWarning(name: string, options: LoopOptions | undefined): string | undefined;
+/**
+ * True when a container body (or an arm/handler inside it, but not a NESTED
+ * container's body) breaks: a nested `.loop()`/`.doWhile()` owns its own
+ * `.break()`.
+ */
+export declare function bodyUsesBreak(steps: Step[]): boolean;

package/dist/loop-version.js

@@ -0,0 +1,97 @@
+/**
+ * What each `core.logic.loop` version can express, read from the bundled
+ * definition of that version — the one answer `serialize` and `check` share.
+ *
+ * The definition is the authority:
+ * - an option is supported when the definition declares an input of that name;
+ * - `.break()` is supported when the definition declares a `break` target handle.
+ */
+import { BUNDLED_DEFINITIONS } from './flow-definitions.js';
+/** The wire type of `.loop()`. */
+export const LOOP_NODE_TYPE = 'core.logic.loop';
+/** The `core.logic.loop` version `.loop()` emits unless `{ version }` pins another. */
+export const LOOP_DEFAULT_VERSION = '2.4';
+/** The version `.loop()` emits for these options. */
+export function loopVersion(options) {
+    return options?.version ?? LOOP_DEFAULT_VERSION;
+}
+/**
+ * True when this loop version's body runs from the inner `start` handle and goes
+ * back through `continue` (2.x); false for the legacy `output`/`loopBack` shape.
+ * A version with no bundled definition counts as 2.x; its lookup fails later.
+ */
+export function loopHasInnerHandles(version) {
+    return loopDefinition(version) ? targetHandleIds(version).has('continue') : true;
+}
+/** The loop options whose support depends on the version, in message order. */
+const VERSIONED_OPTIONS = ['parallel', 'completionCondition', 'breakEnabled'];
+/**
+ * The features this loop uses that its version's definition cannot express, in
+ * a fixed order (`parallel`, `completionCondition`, `breakEnabled`, `break()`).
+ * Empty when all are supported, or when no definition is bundled for the version
+ * (an unknown version is reported elsewhere, by the definition lookup).
+ */
+export function unsupportedLoopFeatures(options, usesBreak) {
+    const def = loopDefinition(loopVersion(options));
+    if (!def)
+        return [];
+    const inputs = def.inputDefinition?.properties ?? {};
+    const out = VERSIONED_OPTIONS.filter((k) => options?.[k] !== undefined && !(k in inputs));
+    if (usesBreak && !targetHandleIds(loopVersion(options)).has('break'))
+        out.push('break()');
+    return out;
+}
+/**
+ * The refusal for a loop whose options or body need a definition the requested
+ * version does not have, or `undefined` when there is nothing to refuse.
+ * `serialize` throws it; `check` reports it as `LOOP_VERSION_UNSUPPORTED` with
+ * the same text, so the author reads one message in both places.
+ */
+export function loopVersionRefusal(name, options, usesBreak) {
+    const missing = unsupportedLoopFeatures(options, usesBreak);
+    if (missing.length === 0)
+        return undefined;
+    const version = loopVersion(options);
+    return `loop "${name}": ${missing.join('/')} ${missing.length === 1 ? 'needs' : 'need'} the loop's `
+        + `${LOOP_DEFAULT_VERSION} definition, but { version: '${version}' } was requested. `
+        + `Drop the version or request ${LOOP_DEFAULT_VERSION}.`;
+}
+/**
+ * The warning for `parallel: true` on a 1.0.0 loop, or `undefined`. The 1.0.0
+ * definition declares the input, so the loop compiles and a canvas 1.0.0 loop
+ * round-trips; whether the 1.0.0 runtime runs its iterations in parallel is not
+ * confirmed, so a new loop that needs that should use the default version.
+ * `check` reports it as `LOOP_PARALLEL_LEGACY`.
+ */
+export function loopParallelWarning(name, options) {
+    if (options?.parallel !== true || loopHasInnerHandles(loopVersion(options)))
+        return undefined;
+    return `loop "${name}": parallel: true on { version: '${loopVersion(options)}' } is written to the node, but `
+        + `that version is not confirmed to run iterations in parallel, so the loop may run them one by one. `
+        + `Keep it to round-trip an existing loop; for a new parallel loop, drop the version (${LOOP_DEFAULT_VERSION}).`;
+}
+/**
+ * True when a container body (or an arm/handler inside it, but not a NESTED
+ * container's body) breaks: a nested `.loop()`/`.doWhile()` owns its own
+ * `.break()`.
+ */
+export function bodyUsesBreak(steps) {
+    return steps.some((s) => s.kind === 'break'
+        || (s.kind === 'branch' && (bodyUsesBreak(s.then) || bodyUsesBreak(s.otherwise)))
+        || (s.kind === 'switch' && (s.cases.some((c) => bodyUsesBreak(c.body)) || (s.default ? bodyUsesBreak(s.default) : false)))
+        || (s.kind === 'stepSwitch' && s.cases.some((c) => bodyUsesBreak(c.body)))
+        || (s.kind === 'parallel' && s.arms.some(bodyUsesBreak))
+        || (s.kind === 'stepToList' && bodyUsesBreak(s.body)));
+}
+function loopDefinition(version) {
+    return BUNDLED_DEFINITIONS[`${LOOP_NODE_TYPE}@${version}`];
+}
+function targetHandleIds(version) {
+    const ids = new Set();
+    for (const group of loopDefinition(version)?.handleConfiguration ?? []) {
+        for (const h of group.handles ?? [])
+            if (h.type === 'target')
+                ids.add(h.id);
+    }
+    return ids;
+}

package/dist/registry/curated-overlay.d.ts

@@ -3,46 +3,81 @@ import { type Reporter } from "./reporter.js";
 export declare function bundledOverlayPath(): string;
 /** Stable identity of the curated data, so a changed overlay gets a new cache entry. */
 export declare function curatedOverlayIdentity(overlayPath?: string): Promise<string>;
+/** The ledger of deliberate patches; read here, never copied into a library. */
+export declare const CORRECTIONS_FILE = "overlay-corrections.json";
+/** One row of {@link CORRECTIONS_FILE}. */
+export interface OverlayCorrection {
+    path: string;
+    since: string;
+    reason: string;
+    /** Added to the entry's `inputSchema.fields` and the sidecar's `inputDefinition.fields` when absent. */
+    inputFields?: string[];
+    /** Top-level sidecar keys added when absent. */
+    sidecarKeys?: string[];
+}
 export interface CuratedOverlayResult {
-    /** Overlay files copied into the library. */
+    /** Files written into the library: definitions added, corrections patched, side-tables. */
     files: number;
     /** Index rows added for identities the library did not already carry. */
     entries: number;
     /**
      * Overlay entry files NOT copied, because the library resolves their
-     * identity to a different path. POSIX-relative to the overlay, sorted. Each
-     * one is also reported through the reporter — see {@link applyCuratedOverlay}.
+     * identity to a different path. POSIX-relative to the overlay, sorted.
      */
     skipped: string[];
+    /** Overlay entries added because the library lacked their identity. Sorted. */
+    added: string[];
+    /** Corrections patched into the library's own definition. Sorted. */
+    corrected: string[];
+    /**
+     * Overlay entries the library already carries at the same path, so its
+     * published definition was kept. Sorted. Not a problem: these are the
+     * directory's test fixtures, which the overlay must never copy over a
+     * published file (#1148).
+     */
+    kept: string[];
 }
 /**
- * Apply the SDK's curated corrections after extracting the raw registry dump.
+ * The bundled corrections, checked against the overlay they ship in. A row
+ * that names no indexed overlay entry, or a field that entry does not define,
+ * is a fault in the SDK's own data, so it throws rather than patching nothing.
+ */
+export declare function readOverlayCorrections(overlayPath: string): Promise<OverlayCorrection[]>;
+/**
+ * Apply the SDK's curated overlay after extracting the raw registry dump.
  *
- * Files replace the dump's copy, while index rows are a union where the dump
- * wins collisions. This is the same contract as the former unpack script: a
- * correction changes the referenced file, and a definition absent from the
- * dump (notably connector triggers) is made resolvable by its added index row.
+ * THE RULE. The overlay ADDS what the library lacks and never replaces what it
+ * carries, apart from the deliberate patches listed in {@link CORRECTIONS_FILE}:
  *
- * WHEN THE LIBRARY ALREADY RESOLVES THE IDENTITY ELSEWHERE, the file is not
- * copied at all and the skip is reported. That case is not hypothetical: four
- * of the bundled `event-*@1.0.0.json` files carry a (nodeType, version) the
- * raw dump lacks TODAY but a refreshed catalog serves at its own path — the
- * per-object event variants land under `<connector>/events/<object>/`, keeping
- * the template's nodeType. Since the union keeps the library's row, copying
- * anyway left a file no index row pointed at, which `--check-orphans` (the
- * image build passes it) rejects. The three ways out are not equal:
+ *   - an overlay entry whose (nodeType, version) the library does not index is
+ *     copied with its sidecar, and its index row is added. This is what makes
+ *     the connector start triggers resolvable, which the raw dump lacks;
+ *   - an entry the library indexes at the SAME path is kept as published. The
+ *     overlay's copy is a snapshot, and the published library moves on: until
+ *     #1148 every such file was copied over the download while the download's
+ *     index row stayed, so nine 2026-07 snapshots replaced newer definitions and
+ *     Outlook `send-email` read `send-mail` (no `saveAsDraft`, no multipart
+ *     parts) under an index row that said `send-mail-v2`. The entry files carry
+ *     no date or build number to compare, so "is the published one newer?" is
+ *     not answerable per file; the answer is that the overlay never decides it;
+ *   - a listed correction is PATCHED into the library's own definition: the
+ *     named input fields and sidecar keys are added when absent, and nothing
+ *     else is touched. It cannot change the operation's object or endpoint, so
+ *     index row and entry file cannot be made to disagree. When the published
+ *     definition already has everything, the correction is reported as no
+ *     longer needed so its row can be removed;
+ *   - an entry the library indexes at a DIFFERENT path is not copied: the copy
+ *     would be a file no index row points at, which `--check-orphans` (the
+ *     image build passes it) rejects, and stamping the flat curated file over
+ *     each per-object variant the library serves would destroy their schemas.
+ *     A correction in that position is warned about, since it no longer takes
+ *     effect;
+ *   - the SDK's side-tables (`list-envelopes.json`, `invariant-collections.json`)
+ *     are the SDK's own data and are always copied.
  *
- *   - copying and teaching the orphan check to tolerate the file would keep
- *     the build green and hide the real loss, which is that the hand-verified
- *     CORRECTION never takes effect once the index points somewhere else;
- *   - redirecting the correction onto the indexed path cannot be done safely
- *     here, because ONE event identity maps to MANY per-object paths in a
- *     refreshed library, and stamping the flat curated definition over each
- *     per-object variant would destroy the per-object schema the library just
- *     served — a worse regression than the one being fixed;
- *   - so the copy is skipped and said out loud. The library keeps the
- *     definition it resolves, the tree gains no unreachable file, and the
- *     operator is told which overlay row has been overtaken and needs
- *     re-verifying. The image build is then green before AND after a refresh.
+ * What was done is reported in one line, and recorded in `.curated-overlay.json`
+ * beside the index, so a second application recognises its own patches: the
+ * record keeps a sha256 of each patched entry and sidecar, and a correction
+ * whose files no longer match it is patched again.
  */
 export declare function applyCuratedOverlay(libraryPath: string, overlayPath?: string, reporter?: Reporter): Promise<CuratedOverlayResult>;