@uipath/maestro-builder-sdk 6.33.1 → 6.33.2

package/dist/flow-variables.d.ts

@@ -9,6 +9,8 @@ export interface FlowGlobalDeclaration {
     subType?: string;
     schema?: Record<string, unknown>;
 }
+/** The keys of `variables` that hold declarations rather than name one (the map spelling). */
+export declare const CONTAINER_KEYS: ReadonlySet<string>;
 /** Read both supported Flow variable spellings into one declaration table. */
 export declare function readFlowGlobals(variables: unknown, strict?: boolean): FlowGlobalDeclaration[];
 /** The declaration fields `planFlowGlobals` reads (structurally a `VarDecl`). */

package/dist/flow-variables.js

@@ -1,5 +1,6 @@
 import { globalNameCollisionMessage, globalNameCollisions } from './core/global-names.js';
-const CONTAINER_KEYS = new Set(['globals', 'nodes', 'variableUpdates']);
+/** The keys of `variables` that hold declarations rather than name one (the map spelling). */
+export const CONTAINER_KEYS = new Set(['globals', 'nodes', 'variableUpdates']);
 const DIRECTIONS = new Set(['in', 'out', 'inout']);
 /** Read both supported Flow variable spellings into one declaration table. */
 export function readFlowGlobals(variables, strict = false) {

package/dist/merge-roundtrip.d.ts

@@ -33,7 +33,7 @@ interface RtFlow {
 /** 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' | 'agent-sidecar' | 'agent-storage' | 'agent-prompt-input' | 'agent-embedded-edit';
+    kind: 'node-removed' | 'node-added' | 'node-type' | 'implicit-end' | 'edge-handle-renamed' | 'edge-rewired' | 'edge-removed' | 'edge-added' | 'handle-ids' | 'binding-removed' | 'binding-added' | 'variable-added' | 'variable-changed' | 'undeclared-handle' | 'duplicate-binding' | 'agent-sidecar' | 'agent-storage' | 'agent-prompt-input' | 'agent-embedded-edit';
     /** The finding, phrased for the author, naming the node, edge or row. */
     message: string;
     /**

package/dist/merge-roundtrip.js

@@ -27,7 +27,10 @@
  * - switch case ids and human-task outcome ids, which name the handles the
  *   edges leave from;
  * - binding rows by what they bind (`core/binding-identity.ts`), never by the
- *   row `id`.
+ *   row `id`;
+ * - root `variables` entries (`globals`, `nodes`) by id. Merge restores an
+ *   entry the author did not touch (merge-variables.ts), so this reports only
+ *   what slipped past that rule, such as a section taken whole.
  *
  * Two checks run on the MERGED file whatever the baseline says, because merge
  * mixes sources (untouched nodes from the original, edges from the edited file):
@@ -52,6 +55,7 @@
 import { bindingIdentity } from './core/binding-identity.js';
 import { expandSourceHandles } from './core/definition-handles.js';
 import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
+import { isDeltaSpelling, stableJson } from './merge-variables.js';
 /** A file's definitions, keyed `nodeType@version`. */
 function defsOf(f) {
     const out = new Map();
@@ -276,6 +280,33 @@ export function roundTripFindings(original, baseline, merged) {
             out.push({ kind: 'binding-added', refuses: true, message: `the round trip adds a binding row for ${bindingText(r)}; merge will write it.` });
         }
     }
+    // ── Root variables, by section and id ──
+    // A map-spelled original is taken whole on any edit (merge-variables.ts), so
+    // what that carries is reported but never refused: the author cannot avoid it.
+    const refuses = isDeltaSpelling(original.variables);
+    const tail = refuses ? '' : ' (the original uses the map spelling, so merge takes the edited section whole; not refused under --strict)';
+    for (const section of ['globals', 'nodes']) {
+        const entries = (f) => {
+            const list = f.variables?.[section];
+            return new Map((Array.isArray(list) ? list : [])
+                .filter((v) => typeof v?.id === 'string').map((v) => [v.id, v]));
+        };
+        const o = entries(original);
+        const b = entries(baseline);
+        const m = entries(merged);
+        for (const [id, bv] of b) {
+            const mv = m.get(id);
+            const ov = o.get(id);
+            if (mv === undefined || stableJson(mv) !== stableJson(bv) || (ov !== undefined && stableJson(ov) === stableJson(bv)))
+                continue;
+            if (ov === undefined) {
+                out.push({ kind: 'variable-added', refuses, message: `the round trip adds variables.${section} "${id}"; merge will write it${tail}.` });
+                continue;
+            }
+            const fields = [...new Set([...Object.keys(ov), ...Object.keys(bv)])].filter((k) => stableJson(ov[k]) !== stableJson(bv[k]));
+            out.push({ kind: 'variable-changed', refuses, message: `the round trip rewrites ${fields.join(', ')} of variables.${section} "${id}"; merge will write it${tail}.` });
+        }
+    }
     return out;
 }
 /** The source handles a node's definition declares, or `undefined` when they cannot be known. */

package/dist/merge-variables.d.ts

@@ -0,0 +1,19 @@
+type Json = unknown;
+/** JSON with object keys sorted, so key order is not a difference. */
+export declare function stableJson(v: Json): string;
+/**
+ * Whether `variables` is spelled the way the delta reads it: absent, or an
+ * object whose keys are only the container keys (`globals`, `nodes`,
+ * `variableUpdates`). A map-spelled original is not, and is taken whole.
+ */
+export declare function isDeltaSpelling(variables: Json): boolean;
+/**
+ * The merged root `variables`. `goneNodeIds` are the original's nodes (root and
+ * subflows) the merged file no longer has: a node variable, or a
+ * `variableUpdates` key, kept from the original for one of them is dropped
+ * with the node.
+ */
+export declare function mergeVariables(original: Json, edited: Json, baseline: {
+    variables?: Json;
+} | undefined, goneNodeIds: Set<string>): Json;
+export {};

package/dist/merge-variables.js

@@ -0,0 +1,191 @@
+/**
+ * merge-variables — the delta rule for a flow's root `variables` (#1261).
+ *
+ * Nodes merge as a delta: one the author did not touch (edited equals
+ * baseline) is restored from the original. `variables` follow the same rule.
+ *
+ * The same rule, applied at three levels:
+ *
+ *   - the whole section: edited equals baseline → the original's, verbatim;
+ *   - a top-level key (`globals`, `nodes`, `variableUpdates`): edited equals
+ *     baseline → the original's (absent stays absent);
+ *   - an entry of an id-keyed list (`globals`, `nodes`) or a key of a map
+ *     (`variableUpdates`): the same, and inside an entry each field the same,
+ *     so an edited global's new `type` lands without the `name` compile adds.
+ *
+ * Presence follows the same logic. An entry the edited file lacks was removed
+ * by the author when the baseline has it, and lost by the round trip when it
+ * does not (kept). An entry the original lacks is the author's when the
+ * baseline lacks it or differs, and the round trip's when the baseline has it
+ * unchanged (dropped).
+ *
+ * Example, after the author changes `creditAmount`'s type and nothing else:
+ *
+ *     original  { id: 'creditAmount', direction: 'out', type: 'string' }
+ *     baseline  { id: 'creditAmount', name: 'creditAmount', direction: 'out', type: 'string' }
+ *     edited    { id: 'creditAmount', name: 'creditAmount', direction: 'out', type: 'number' }
+ *     merged    { id: 'creditAmount', direction: 'out', type: 'number' }
+ *
+ * An original with no `variables` section, or with no `globals` / `nodes` /
+ * `variableUpdates` key, is treated as empty there: what compile minted for
+ * the untouched part is still the round trip's, and only the author's
+ * additions land.
+ *
+ * Without a baseline there is nothing to tell an edit from the round trip, so
+ * the edited section is taken whole. So is a section whose original uses a key
+ * this file does not know (the older map spelling, `variables.city = {...}`)
+ * once the author changed anything: mixing two spellings in one section is
+ * worse than taking the compile's. The round-trip report still lists what that
+ * carries, but does not refuse it under `--strict`, because the author cannot
+ * avoid it short of making no edit ({@link isDeltaSpelling}).
+ */
+import { jsonClone } from './core/json-clone.js';
+import { CONTAINER_KEYS } from './flow-variables.js';
+/** `jsonClone`, which also passes `undefined` (an absent section or key) through. */
+const copy = (v) => (v === undefined ? v : jsonClone(v));
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** JSON with object keys sorted, so key order is not a difference. */
+export function stableJson(v) {
+    return JSON.stringify(v, (_k, val) => (isObj(val)
+        ? Object.fromEntries(Object.keys(val).sort().map((k) => [k, val[k]]))
+        : val));
+}
+const same = (a, b) => stableJson(a) === stableJson(b);
+/**
+ * Whether `variables` is spelled the way the delta reads it: absent, or an
+ * object whose keys are only the container keys (`globals`, `nodes`,
+ * `variableUpdates`). A map-spelled original is not, and is taken whole.
+ */
+export function isDeltaSpelling(variables) {
+    return variables === undefined || (isObj(variables) && Object.keys(variables).every((k) => CONTAINER_KEYS.has(k)));
+}
+/**
+ * The merged root `variables`. `goneNodeIds` are the original's nodes (root and
+ * subflows) the merged file no longer has: a node variable, or a
+ * `variableUpdates` key, kept from the original for one of them is dropped
+ * with the node.
+ */
+export function mergeVariables(original, edited, baseline, goneNodeIds) {
+    if (!baseline)
+        return copy(edited);
+    const base = baseline.variables;
+    if (same(edited, base))
+        return withoutGoneUpdates(copy(original), goneNodeIds);
+    if (!isDeltaSpelling(original) || !isObj(edited))
+        return copy(edited);
+    const orig = isObj(original) ? original : {};
+    const baseObj = isObj(base) ? base : {};
+    const out = {};
+    for (const key of keysInOrder(orig, edited)) {
+        const updates = key === 'variableUpdates';
+        const inner = updates
+            ? (o, b, e) => (isObj(o) && isObj(e) ? mergeFields(o, isObj(b) ? b : undefined, e) : copy(e))
+            : (o, b, e) => mergeList(o, b, e, goneNodeIds);
+        // A section the original lacks but the round trip writes is merged as an
+        // empty one, so its minted entries stay out and only the author's land.
+        const absent = !(key in orig) && key in baseObj && key in edited && !same(edited[key], baseObj[key]);
+        const value = absent
+            ? nonEmpty(inner(updates ? {} : [], baseObj[key], edited[key]))
+            : mergeKey(orig[key], baseObj[key], edited[key], key in orig, key in baseObj, key in edited, inner);
+        if (value !== undefined)
+            out[key] = value;
+    }
+    if (original === undefined && Object.keys(out).length === 0)
+        return undefined;
+    return withoutGoneUpdates(out, goneNodeIds);
+}
+/** `undefined` for an empty list or map, so an absent section stays absent. */
+function nonEmpty(v) {
+    if (Array.isArray(v))
+        return v.length ? v : undefined;
+    if (isObj(v))
+        return Object.keys(v).length ? v : undefined;
+    return v;
+}
+/**
+ * `variables` without the `variableUpdates` keys (node ids) of nodes the merge
+ * dropped. A key the round trip lost is kept from the original, so without
+ * this it would outlive its node.
+ */
+function withoutGoneUpdates(variables, goneNodeIds) {
+    const updates = isObj(variables) ? variables.variableUpdates : undefined;
+    if (!isObj(updates) || !Object.keys(updates).some((k) => goneNodeIds.has(k)))
+        return variables;
+    return { ...variables, variableUpdates: Object.fromEntries(Object.entries(updates).filter(([k]) => !goneNodeIds.has(k))) };
+}
+/** Original's keys in its order, then the edited file's new ones. */
+function keysInOrder(original, edited) {
+    return [...Object.keys(original), ...Object.keys(edited).filter((k) => !(k in original))];
+}
+/**
+ * One key's value under the delta rule; `undefined` = leave the key out.
+ * `inner` merges a value both sides have and the author changed.
+ */
+function mergeKey(o, b, e, inOriginal, inBaseline, inEdited, inner) {
+    if (!inEdited)
+        return inBaseline || !inOriginal ? undefined : copy(o); // removed by the author / lost by the round trip
+    if (inBaseline && same(e, b))
+        return inOriginal ? copy(o) : undefined; // untouched
+    if (!inOriginal)
+        return copy(e); // the author's addition
+    return inner(o, b, e);
+}
+/** An id-keyed list (`globals`, `nodes`): per entry, then per field. */
+function mergeList(o, b, e, goneNodeIds) {
+    if (!idList(o) || !idList(e))
+        return copy(e);
+    const base = new Map((idList(b) ? b : []).map((x) => [x.id, x]));
+    const edits = new Map(e.map((x) => [x.id, x]));
+    const out = [];
+    for (const entry of o) {
+        const id = entry.id;
+        if (!edits.has(id)) {
+            // The author removed it (baseline has it), or the round trip lost it; a
+            // lost node variable whose node is gone goes with the node.
+            if (!base.has(id) && !boundToGoneNode(entry, goneNodeIds))
+                out.push(copy(entry));
+            continue;
+        }
+        const ed = edits.get(id);
+        out.push(base.has(id) && same(ed, base.get(id)) ? copy(entry) : mergeFields(entry, base.get(id), ed));
+    }
+    const originalIds = new Set(o.map((x) => x.id));
+    for (const [i, ed] of e.entries()) {
+        const id = ed.id;
+        if (originalIds.has(id) || (base.has(id) && same(ed, base.get(id))))
+            continue; // kept above / minted by the round trip
+        out.splice(insertAt(out, e, i), 0, copy(ed));
+    }
+    return out;
+}
+/** After the nearest earlier edited entry already in `out`, else first. */
+function insertAt(out, edited, i) {
+    for (let j = i - 1; j >= 0; j--) {
+        const at = out.findIndex((x) => x.id === edited[j].id);
+        if (at >= 0)
+            return at + 1;
+    }
+    return 0;
+}
+/**
+ * An object the author changed — a list entry, or the `variableUpdates` map
+ * (keyed by node id): each key under the delta rule, each value taken whole,
+ * keys in the original's order.
+ */
+function mergeFields(o, b, e) {
+    const base = b ?? {};
+    const out = {};
+    for (const key of keysInOrder(o, e)) {
+        const v = mergeKey(o[key], base[key], e[key], key in o, key in base, key in e, (_o, _b, ev) => copy(ev));
+        if (v !== undefined)
+            out[key] = v;
+    }
+    return out;
+}
+function idList(v) {
+    return Array.isArray(v) && v.every((x) => isObj(x) && typeof x.id === 'string');
+}
+function boundToGoneNode(entry, goneNodeIds) {
+    const nodeId = isObj(entry.binding) ? entry.binding.nodeId : undefined;
+    return typeof nodeId === 'string' && goneNodeIds.has(nodeId);
+}

package/dist/merge.d.ts

@@ -26,7 +26,8 @@
  *
  * Layout, `metadata`, `solutionId`, `projectId`, `runtime` and `layout` are
  * preserved from the original; `subflows` and edges (with their ids) come from
- * `edited`; `definitions` and `bindings` are unioned
+ * `edited`; root `variables` merge as a delta per entry, like nodes
+ * (merge-variables.ts); `definitions` and `bindings` are unioned
  * (original wins on conflict, since the original's are the tenant-resolved
  * authority). A binding row's identity is what it binds, not its row id, and a
  * row the no-edit recompile minted only for nodes merge kept from the original
@@ -143,8 +144,8 @@ export interface MergeOptions {
      * - with a `baseline`, each wire-identity difference between the baseline
      *   (the no-edit round trip) and the original — a node or edge added, dropped
      *   or rewired, a switch case id or human-task outcome id renamed, a binding
-     *   row added or dropped — that the merged file still carries, i.e. the
-     *   author's edit did not undo it;
+     *   row added or dropped, a root `variables` entry added or rewritten — that
+     *   the merged file still carries, i.e. the author's edit did not undo it;
      * - an edited node whose `typeVersion` differs from the original node with
      *   the same id, because the edit took the SDK's version;
      * - a merged edge whose `sourcePort` is not a handle its source node declares,

package/dist/merge.js

@@ -26,7 +26,8 @@
  *
  * Layout, `metadata`, `solutionId`, `projectId`, `runtime` and `layout` are
  * preserved from the original; `subflows` and edges (with their ids) come from
- * `edited`; `definitions` and `bindings` are unioned
+ * `edited`; root `variables` merge as a delta per entry, like nodes
+ * (merge-variables.ts); `definitions` and `bindings` are unioned
  * (original wins on conflict, since the original's are the tenant-resolved
  * authority). A binding row's identity is what it binds, not its row id, and a
  * row the no-edit recompile minted only for nodes merge kept from the original
@@ -89,6 +90,7 @@ import { MergeRefusedError, mergedFileFindings, roundTripFindings } from './merg
 import { placeAddedNodes } from './node-placement.js';
 import { mergeAgentSidecars } from './merge-sidecars.js';
 import { embeddedAgentFindings, isEmbeddedAgent, mergeEmbeddedAgentNode } from './merge-embedded-agent.js';
+import { mergeVariables } from './merge-variables.js';
 export { MergeRefusedError } from './merge-roundtrip.js';
 function byId(nodes) {
     return new Map((nodes ?? []).map((n) => [n.id, n]));
@@ -256,8 +258,7 @@ function mergeFlowFindings(original, edited, options) {
     result.nodes = finalNodes;
     // Nodes present in the original but absent from `edited` were deleted by the
     // user; they are simply not carried over.
-    // ── Variables & subflows: the edited flow is authoritative (the user's graph). ──
-    result.variables = jsonClone(edited.variables);
+    // ── Subflows: the edited flow is authoritative (the user's graph). ──
     result.subflows = jsonClone(edited.subflows ?? {});
     // A subflow is taken from `edited` whole, so an embedded agent inside one
     // would flip to the edited shell even with no edit. Keep it embedded too.
@@ -267,6 +268,20 @@ function mergeFlowFindings(original, edited, options) {
     if (options.baseline)
         keepOriginalSourcesInSubflows(original, result.subflows, options.baseline);
     const subflowScopes = Object.values(result.subflows);
+    // ── Variables: the same delta as nodes, per entry — what the author did not
+    //    change stays the original's, so compile's own spellings (an added
+    //    `name`, a re-derived End output type) do not reach the file (#1261).
+    //    See merge-variables.ts. ──
+    const mergedNodeIds = new Set([...finalNodes, ...subflowScopes.flatMap((sf) => sf?.nodes ?? [])].map((n) => n.id));
+    const goneNodeIds = new Set([
+        ...(original.nodes ?? []),
+        ...Object.values(original.subflows ?? {}).flatMap((sf) => sf?.nodes ?? []),
+    ].map((n) => n.id).filter((id) => !mergedNodeIds.has(id)));
+    const variables = mergeVariables(original.variables, edited.variables, options.baseline, goneNodeIds);
+    if (variables === undefined)
+        delete result.variables;
+    else
+        result.variables = variables;
     // ── Edges: the edited graph's edges define the wiring, under the edited
     //    file's own ids. compile draws every edge id — root AND subflows — from
     //    one file-wide counter, so they are already unique. Renumbering the root

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.33.1",
+  "version": "6.33.2",
   "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": "a27439803ad2ab68ce5be0c4299649d3f4d92e0b"
+  "gitref": "04124f15f4e70827cb18bbd0f52c0bf676ceedd1"
 }