@uipath/maestro-builder-sdk 6.19.0 → 6.20.1

package/dist/flow-expr-check.js

@@ -75,7 +75,7 @@ function addStepNames(steps, roots) {
     for (const s of steps) {
         // `return` carries a synthetic name; the port-edge kinds carry none at all —
         // they are edges, not nodes, so there is nothing to reference them by.
-        if (s.kind !== 'return' && s.kind !== 'stepToRef' && s.kind !== 'stepToList' && s.kind !== 'break')
+        if (s.kind !== 'return' && s.kind !== 'stepToRef' && s.kind !== 'stepToList' && s.kind !== 'break' && s.kind !== 'continue')
             roots.add(s.name);
         switch (s.kind) {
             case 'stepToList':

package/dist/flow-sdk.d.ts

@@ -337,6 +337,13 @@ export type CaseValue = string | number | boolean;
 export interface SwitchArm {
     value: CaseValue;
     label?: string;
+    /**
+     * The case's wire id — `inputs.cases[].id`, and the `case-<id>` port its arm
+     * leaves from. Omitted, it is positional (`case_1`, `case_2`, …). Set it only
+     * to keep an id a flow already has (decompile does, for a designer-drawn
+     * switch whose ids are `default-1`, …).
+     */
+    id?: string;
     body: Step[];
 }
 /**
@@ -520,6 +527,14 @@ export type Step = {
  | {
     kind: 'break';
 }
+/**
+ * Go on to the enclosing loop/do-while's next iteration through its continue
+ * handle — the edge a body's last step gets. Terminal on its path. Only valid
+ * inside a container body.
+ */
+ | {
+    kind: 'continue';
+}
 /**
  * A fan-out and its join. `arms` is one step list per arm — an ARRAY, because
  * arms are positional and carry no author-supplied keys — and `name` names the
@@ -958,7 +973,8 @@ declare class StepList {
      * @param name - The switch node's id.
      * @param on - The value to compare each case against.
      * @param cases - One entry per arm, evaluated top to bottom; the first strict
-     * match wins. `label` names the arm's outgoing edge.
+     * match wins. `label` names the arm's outgoing edge. `id` keeps a case's wire
+     * id (`inputs.cases[].id`, port `case-<id>`); omitted, it is `case_<n>`.
      * @param defaultFn - Receives a sub-builder for the arm taken when nothing
      * matches. Omit it and an unmatched value simply continues.
      * @param options - Node options; `version` selects the exact definition
@@ -969,6 +985,7 @@ declare class StepList {
         value: CaseValue;
         body: (b: ArmBuilder) => void;
         label?: string;
+        id?: string;
     }[], defaultFn?: (b: StepList) => void, options?: NodeOptions): this;
     /**
      * Run two or more arms **in parallel** from this point and join them back
@@ -1053,6 +1070,21 @@ declare class StepList {
      * @returns This builder. Nothing after this call on the same path can run.
      */
     break(): this;
+    /**
+     * Go on to the **next iteration** of the enclosing `.loop()` / `.doWhile()`
+     * through its continue handle — the edge the body's last step gets anyway.
+     * Use it where a path would otherwise end the run: an `.onError()` handler or
+     * an HTTP-branch / outcome list inside the body ends on an End node of its own
+     * unless it says where to go, so "log the failure and skip this item" is
+     * `.onError((h) => h.step('log', …).continue())`. Terminal on its path, like
+     * `.break()`. Compilation fails when there is no enclosing container.
+     *
+     * Not `.stepToRef('<loop>')`: that names the loop as a step and enters it from
+     * its outer input — it restarts the loop, it does not go on to the next item.
+     *
+     * @returns This builder. Nothing after this call on the same path can run.
+     */
+    continue(): this;
     /**
      * Stop the **whole run**, here and now — not just this path.
      *

package/dist/flow-sdk.js

@@ -617,7 +617,8 @@ class StepList {
      * @param name - The switch node's id.
      * @param on - The value to compare each case against.
      * @param cases - One entry per arm, evaluated top to bottom; the first strict
-     * match wins. `label` names the arm's outgoing edge.
+     * match wins. `label` names the arm's outgoing edge. `id` keeps a case's wire
+     * id (`inputs.cases[].id`, port `case-<id>`); omitted, it is `case_<n>`.
      * @param defaultFn - Receives a sub-builder for the arm taken when nothing
      * matches. Omit it and an unmatched value simply continues.
      * @param options - Node options; `version` selects the exact definition
@@ -635,7 +636,7 @@ class StepList {
             // An arm's own `.label(...)` wins over the case config's `label`; either
             // overrides the serializer's derived `Case "<value>"`.
             const label = arm.armLabel ?? c.label;
-            return { value: c.value, ...(label !== undefined ? { label } : {}), body: arm.steps };
+            return { value: c.value, ...(label !== undefined ? { label } : {}), ...(c.id !== undefined ? { id: c.id } : {}), body: arm.steps };
         });
         let dflt;
         if (defaultFn) {
@@ -765,6 +766,24 @@ class StepList {
         this.steps.push({ kind: 'break' });
         return this;
     }
+    /**
+     * Go on to the **next iteration** of the enclosing `.loop()` / `.doWhile()`
+     * through its continue handle — the edge the body's last step gets anyway.
+     * Use it where a path would otherwise end the run: an `.onError()` handler or
+     * an HTTP-branch / outcome list inside the body ends on an End node of its own
+     * unless it says where to go, so "log the failure and skip this item" is
+     * `.onError((h) => h.step('log', …).continue())`. Terminal on its path, like
+     * `.break()`. Compilation fails when there is no enclosing container.
+     *
+     * Not `.stepToRef('<loop>')`: that names the loop as a step and enters it from
+     * its outer input — it restarts the loop, it does not go on to the next item.
+     *
+     * @returns This builder. Nothing after this call on the same path can run.
+     */
+    continue() {
+        this.steps.push({ kind: 'continue' });
+        return this;
+    }
     /**
      * Stop the **whole run**, here and now — not just this path.
      *

package/dist/flow-step-tree.js

@@ -9,7 +9,7 @@ export function stopsAtEnd(steps) {
         || (st.kind === 'branch' && (has(st.then, kinds) || has(st.otherwise, kinds)))
         || ((st.kind === 'switch' || st.kind === 'stepSwitch') && st.cases.some((c) => has(c.body, kinds)))
         || (st.kind === 'switch' && st.default !== undefined && has(st.default, kinds)));
-    return has(steps, new Set(['return'])) && !has(steps, new Set(['terminate', 'break']));
+    return has(steps, new Set(['return'])) && !has(steps, new Set(['terminate', 'break', 'continue']));
 }
 /**
  * The step lists nested DIRECTLY inside `step` — the bodies a walk over this
@@ -37,6 +37,7 @@ export function childStepLists(step) {
             return step.arms;
         case 'action':
         case 'break':
+        case 'continue':
         case 'terminate':
         case 'stepToRef':
         case 'return':

package/dist/index.d.ts

@@ -14,7 +14,8 @@ export type { EmitFlowOpts } from './emit.js';
 export { decompile as decompileFlow } from './decompile.js';
 export type { DecompileOptions as FlowDecompileOptions } from './decompile.js';
 export { mergeFlow } from './merge.js';
-export type { MergeOptions as FlowMergeOptions } from './merge.js';
+export type { MergeOptions as FlowMergeOptions, MergeFinding as FlowMergeFinding } from './merge.js';
+export { MergeRefusedError as FlowMergeRefusedError } from './merge.js';
 export { Library } from './library.js';
 export { Bindings } from './bindings.js';
 export { check } from './check.js';

package/dist/index.js

@@ -18,6 +18,7 @@ export { serialize } from './serialize.js';
 export { emitFlow } from './emit.js';
 export { decompile as decompileFlow } from './decompile.js';
 export { mergeFlow } from './merge.js';
+export { MergeRefusedError as FlowMergeRefusedError } from './merge.js';
 export { Library } from './library.js';
 export { Bindings } from './bindings.js';
 export { check } from './check.js';

package/dist/merge-cli.js

@@ -3,23 +3,25 @@
  * merge-cli — merge an edited flow back into the original `.flow` (bin `flow-merge`)
  *
  * Usage:
- *   flow-merge <original.flow> <edited.flow> [-o merged.flow] [--baseline <baseline.flow>]
+ *   flow-merge <original.flow> <edited.flow> [-o merged.flow] [--baseline <baseline.flow>] [--strict]
  *
  * `edited.flow` is compile(decompile(original) after your edits). `--baseline`
  * is compile(decompile(original)) BEFORE any edit — supplying it enables the
  * delta merge (untouched nodes keep their original content, placeholder-safe);
  * omit it for a two-way merge (take the edited graph, re-attach original layout).
- * See merge.ts.
+ * With `--baseline`, every wire-identity difference between the baseline and
+ * the original (what the no-edit round trip changed) is printed as a warning;
+ * `--strict` refuses instead (exit 1, nothing written). See merge.ts.
  */
 import { reportResult } from './cli-result.js';
 import { writeJsonFile } from './core/json-file.js';
 import { readFileSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
-import { mergeFlow } from './merge.js';
+import { MergeRefusedError, mergeFlow } from './merge.js';
 import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
 export function run(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
-        console.error('usage: flow-merge <original.flow> <edited.flow> [-o merged.flow] [--baseline <baseline.flow>]');
+        console.error('usage: flow-merge <original.flow> <edited.flow> [-o merged.flow] [--baseline <baseline.flow>] [--strict]');
         return 2;
     }
     const flags = new Set(['-o', '--baseline']);
@@ -33,10 +35,25 @@ export function run(argv) {
     const edited = JSON.parse(readFileSync(editedPath, 'utf8'));
     const baselinePath = flagValue(argv, '--baseline');
     const baseline = baselinePath ? JSON.parse(readFileSync(baselinePath, 'utf8')) : undefined;
-    const merged = mergeFlow(original, edited, {
-        baseline,
-        warn: (m) => console.error(`flow-merge: warning: ${m}`),
-    });
+    const strict = argv.includes('--strict');
+    if (strict && !baseline) {
+        console.error('flow-merge: --strict compares the no-edit round trip with the original; pass --baseline <baseline.flow>');
+        return 2;
+    }
+    let merged;
+    try {
+        merged = mergeFlow(original, edited, {
+            baseline,
+            strict,
+            warn: (m) => console.error(`flow-merge: warning: ${m}`),
+        });
+    }
+    catch (error) {
+        if (!(error instanceof MergeRefusedError))
+            throw error;
+        console.error(`flow-merge: ${error.message}`);
+        return 1;
+    }
     const out = flagValue(argv, '-o') ?? 'merged.flow';
     writeJsonFile(out, merged);
     console.log(`flow-merge: wrote ${basename(out)} (${(merged.nodes ?? []).length} nodes, ${(merged.edges ?? []).length} edges)`);

package/dist/merge-roundtrip.d.ts

@@ -0,0 +1,81 @@
+/** A node as merge sees it: only the fields these checks read. */
+interface RtNode {
+    id: string;
+    type: string;
+    typeVersion?: string;
+    inputs?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/** An edge as merge sees it. */
+interface RtEdge {
+    id?: string;
+    sourceNodeId: string;
+    sourcePort: string;
+    targetNodeId: string;
+    targetPort: string;
+    [k: string]: unknown;
+}
+/** A `.flow` file as merge sees it. */
+interface RtFlow {
+    nodes?: RtNode[];
+    edges?: RtEdge[];
+    definitions?: Array<{
+        nodeType?: string;
+        [k: string]: unknown;
+    }>;
+    subflows?: Record<string, unknown>;
+    bindings?: Array<{
+        id?: string;
+        [k: string]: unknown;
+    }>;
+    [k: string]: unknown;
+}
+/** One difference, or one inconsistency in the merged file. */
+export interface MergeFinding {
+    /** Which comparison found it. */
+    kind: 'node-removed' | 'node-added' | 'node-type' | 'implicit-end' | 'edge-handle-renamed' | 'edge-rewired' | 'edge-removed' | 'edge-added' | 'handle-ids' | 'binding-removed' | 'binding-added' | 'undeclared-handle' | 'duplicate-binding';
+    /** The finding, phrased for the author, naming the node, edge or row. */
+    message: string;
+    /**
+     * Whether `strict` refuses the merge over it. False for `implicit-end` and
+     * `binding-removed`, which leave the merged file doing what the original does.
+     */
+    refuses: boolean;
+}
+/**
+ * Every wire-identity difference between the original and its no-edit round
+ * trip that the merged file still carries, phrased as what the merge writes.
+ *
+ * A difference the author's edit undid is not reported: an edge the round trip
+ * dropped that the merged file has again, an edge or node the round trip added
+ * that the merged file lacks, a node whose type or handles the round trip
+ * changed that the merged file no longer has (or has with the original's).
+ *
+ * @param original - The file being merged into.
+ * @param baseline - compile(decompile(original)) before any edit.
+ * @param merged - The merged file, before it is written.
+ * @returns One finding per difference, in a stable order.
+ */
+export declare function roundTripFindings(original: RtFlow, baseline: RtFlow, merged: RtFlow): MergeFinding[];
+/**
+ * Inconsistencies in the merged file that come from mixing its sources: a root
+ * edge leaving a handle its source node does not declare, and two binding rows
+ * binding the same resource property.
+ *
+ * A node with no definition in `merged.definitions` (a sticky note, a type
+ * neither input carried) is not judged. Neither is anything the original
+ * already had — an edge it carries verbatim, or as many same-identity binding
+ * rows as it already holds — because the merge did not cause it.
+ *
+ * @param merged - The merged file.
+ * @param original - The file merged into.
+ * @returns One finding per inconsistency.
+ */
+export declare function mergedFileFindings(merged: RtFlow, original?: RtFlow): MergeFinding[];
+/** Thrown by `mergeFlow` under `strict` when a finding refuses the merge. */
+export declare class MergeRefusedError extends Error {
+    /** Every refusing finding, in report order. */
+    readonly findings: readonly MergeFinding[];
+    constructor(findings: readonly MergeFinding[]);
+}
+export {};