@uipath/maestro-builder-sdk 6.19.0 → 6.20.1

package/dist/merge.js

@@ -28,7 +28,7 @@
  * preserved from the original; `subflows` and edges (with their ids) come from
  * `edited`; `definitions` and `bindings` are unioned
  * (original wins on conflict, since the original's are the tenant-resolved
- * authority). Node ids are stable by construction (decompile names every step by
+ * authority). A binding row's identity is what it binds, not its row id. Node ids are stable by construction (decompile names every step by
  * its node id), which is what lets every re-attach key on id.
  *
  * ## Definitions are keyed by `nodeType@version`, not by `nodeType`
@@ -63,8 +63,23 @@
  * A node whose pair is in NEITHER file cannot be given a definition here, and a
  * merge that stayed silent about it wrote a file it already knew would fail
  * `validate`. Those are reported through {@link MergeOptions.warn}.
+ *
+ * ## The baseline is also compared with the original
+ *
+ * `baseline` is the no-edit round trip, so wherever it differs from the original
+ * in wire identity (a node, an edge, a switch case id, a human-task outcome id,
+ * a binding row), the merged file inherits that change unless the author's edit
+ * undid it. Each difference the merged file still carries is reported through
+ * `warn`, and `strict` refuses the merge over it; the merged file is also
+ * checked for an edge that leaves a handle its kept source node does not
+ * declare. See merge-roundtrip.ts.
  */
+import { bindingIdentity } from './core/binding-identity.js';
 import { jsonClone } from './core/json-file.js';
+import { DEFINITIONLESS_NODE_TYPES } from './core/definitionless-node-types.js';
+import { MergeRefusedError, mergedFileFindings, roundTripFindings } from './merge-roundtrip.js';
+import { placeAddedNodes } from './node-placement.js';
+export { MergeRefusedError } from './merge-roundtrip.js';
 function byId(nodes) {
     return new Map((nodes ?? []).map((n) => [n.id, n]));
 }
@@ -82,11 +97,31 @@ function nodeUnchanged(a, b) {
         return false;
     return JSON.stringify(a.inputs ?? {}) === JSON.stringify(b.inputs ?? {});
 }
-/** Graft the original node's layout (`ui`) onto an edited node, by id. */
-function withOriginalLayout(edited, orig) {
-    if (!orig || orig.ui === undefined)
+/**
+ * Give an edited node the original's position, by id.
+ *
+ * The original stores it in one of two places: `node.ui` (an SDK-compiled file)
+ * or `layout.nodes[id]` (every canvas-saved file — the designer's save moves
+ * `ui` into `layout.nodes`). From `node.ui` it is grafted onto the node. With a
+ * `layout.nodes` entry, the merged file keeps that entry (it is carried over
+ * with the original's `layout`) and the edited node's compile placeholder `ui`
+ * is dropped, so the node has one position, not two.
+ */
+function withOriginalLayout(edited, orig, originalLayout) {
+    if (!orig)
         return edited;
-    return { ...edited, ui: jsonClone(orig.ui) };
+    if (orig.ui !== undefined)
+        return { ...edited, ui: jsonClone(orig.ui) };
+    if (originalLayout?.[orig.id] !== undefined) {
+        const { ui: _placeholder, ...rest } = edited;
+        return rest;
+    }
+    return edited;
+}
+/** The original's `layout.nodes` map, when it has one. */
+function layoutNodesOf(f) {
+    const nodes = f.layout?.nodes;
+    return nodes && typeof nodes === 'object' && !Array.isArray(nodes) ? nodes : undefined;
 }
 export function mergeFlow(original, edited, options = {}) {
     const result = jsonClone(original);
@@ -104,7 +139,11 @@ export function mergeFlow(original, edited, options = {}) {
         }
         else {
             // Added or edited → take the edited node, re-attaching original layout.
-            finalNodes.push(withOriginalLayout(jsonClone(e), orig));
+            finalNodes.push(withOriginalLayout(jsonClone(e), orig, layoutNodesOf(original)));
+            if (orig && orig.type === e.type && orig.typeVersion !== e.typeVersion) {
+                options.warn?.(`node ${JSON.stringify(e.id)} moved ${e.type}@${String(orig.typeVersion)} -> ${String(e.typeVersion)} `
+                    + `(the edited node takes the SDK's version; flow-builder-sdk#1167).`);
+            }
         }
     }
     result.nodes = finalNodes;
@@ -124,15 +163,25 @@ export function mergeFlow(original, edited, options = {}) {
     //    one already taken elsewhere in the file, gets a fresh id, from ids unused
     //    anywhere in the file. ──
     result.edges = withFileUniqueEdgeIds(edited.edges ?? [], subflowScopes);
+    // ── Placement: a node the edit ADDED has only compile's placeholder, an
+    //    emission-index slot that can land on an original node. Put it next to
+    //    its predecessor, collision-free, in the store the
+    //    original uses — see node-placement.ts. Root scope only: a subflow is
+    //    taken from `edited` whole, layout included. ──
+    placeAddedNodes(finalNodes, result.edges, layoutNodesOf(result), (id) => !origNodes.has(id));
     // ── Definitions: the (type, version) pairs used by EVERY node in the file —
     //    root and subflows — original winning on conflict (its defs are the
     //    tenant-resolved authority). Selecting by root nodes only dropped the
     //    definitions a subflow-only node needs, and validate refused the result
     //    ("has no matching definition"). ──
     const allNodes = [...finalNodes, ...subflowScopes.flatMap((sf) => sf?.nodes ?? [])];
-    result.definitions = mergeDefinitions(original.definitions, edited.definitions, allNodes, options.warn);
-    // ── Bindings: union by id (original wins), so resources for newly-added nodes
-    //    come from `edited` while the original's stay intact. ──
+    const originalNodes = [
+        ...(original.nodes ?? []),
+        ...Object.values(original.subflows ?? {}).flatMap((sf) => sf?.nodes ?? []),
+    ];
+    result.definitions = mergeDefinitions(original.definitions, edited.definitions, allNodes, originalNodes, options.warn);
+    // ── Bindings: union by what each row binds (original wins), so resources for
+    //    newly-added nodes come from `edited` while the original's stay intact. ──
     result.bindings = mergeBindings(original.bindings, edited.bindings);
     // metadata / solutionId / projectId / layout / runtime were carried by the
     // initial clone of `original` and are intentionally left untouched.
@@ -147,6 +196,19 @@ export function mergeFlow(original, edited, options = {}) {
     if (options.baseline && edited.version !== undefined && edited.version !== options.baseline.version) {
         result.version = edited.version;
     }
+    // ── What the no-edit round trip changed, and what mixing sources broke. ──
+    // Under strict, the findings that do not refuse are still warned, so a
+    // refused run shows them too.
+    const findings = [
+        ...(options.baseline ? roundTripFindings(original, options.baseline, result) : []),
+        ...mergedFileFindings(result, original),
+    ];
+    const refusing = options.strict ? findings.filter((f) => f.refuses) : [];
+    for (const f of findings)
+        if (!refusing.includes(f))
+            options.warn?.(f.message);
+    if (refusing.length > 0)
+        throw new MergeRefusedError(refusing);
     return result;
 }
 /**
@@ -186,8 +248,9 @@ function indexDefinitions(defs) {
     }
     return ix;
 }
-function mergeDefinitions(orig, edited, nodes, warn) {
+function mergeDefinitions(orig, edited, nodes, originalNodes, warn) {
     const origIx = indexDefinitions(orig);
+    const originalPairs = new Set(originalNodes.filter((n) => n.type !== undefined && n.typeVersion !== undefined).map((n) => defKey(n.type, n.typeVersion)));
     const editedIx = indexDefinitions(edited);
     const out = new Map();
     const missing = [];
@@ -207,25 +270,62 @@ function mergeDefinitions(orig, edited, nodes, warn) {
         const def = origIx.get(key) ?? editedIx.get(key);
         if (def)
             out.set(key, def);
-        else if (!missing.includes(key))
+        // A definitionless type is not missing anything.
+        else if (!DEFINITIONLESS_NODE_TYPES.has(n.type) && !missing.includes(key))
             missing.push(key);
     }
     for (const key of missing) {
-        warn?.(`node type ${key} is pinned by a merged node but neither the original nor the edited flow `
-            + `carries a definition for that exact pair, so the merged file has none; `
-            + `\`validate\` will report "has no matching definition". `
-            + `Recompile the edited source against an SDK that bundles ${key}, or align the node's typeVersion `
-            + `with a definition one of the inputs does carry.`);
+        // A pair the original already pinned with no definition still fails
+        // `validate`; the warning says the merge inherited it rather than caused it.
+        warn?.(originalPairs.has(key)
+            ? `node type ${key} is pinned by a merged node and already had no definition in the original, `
+                + `and the edited flow carries none either, so the merged file has none; `
+                + `\`validate\` will report "has no matching definition", as it does for the original. `
+                + `Recompile the edited source against an SDK that bundles ${key} to add one.`
+            : `node type ${key} is pinned by a merged node but neither the original nor the edited flow `
+                + `carries a definition for that exact pair, so the merged file has none; `
+                + `\`validate\` will report "has no matching definition". `
+                + `Recompile the edited source against an SDK that bundles ${key}, or align the node's typeVersion `
+                + `with a definition one of the inputs does carry.`);
     }
     return [...out.values()].map((d) => jsonClone(d));
 }
+/**
+ * The original's rows, then each edited row that binds something the original
+ * does not (a resource of a node the user added, or one an edit re-pointed).
+ *
+ * Original wins on the same identity: its rows are the tenant-resolved
+ * authority, and a canvas row can carry values (a `default`, a folder) the
+ * compile does not. An added row keeps its id unless an original row already
+ * holds it, in which case it gets a fresh one — ids are unreferenced labels, but
+ * two rows with one id are not a valid file.
+ *
+ * Rows no surviving node uses are NOT pruned. The file has no uniform
+ * node-to-row reference to decide "unused" by: an in-solution Flow is named by
+ * the node TYPE's suffix, a connection by an id in the node's inputs, a published
+ * process by a folder-qualified key that no node field spells. A wrong prune
+ * drops a row a kept node needs, and the run fails to resolve its resource; an
+ * orphan row is accepted by `validate` and ignored at run time.
+ */
 function mergeBindings(orig, edited) {
-    const byId2 = new Map();
-    for (const b of edited ?? [])
-        if (b.id)
-            byId2.set(b.id, b);
-    for (const b of orig ?? [])
-        if (b.id)
-            byId2.set(b.id, b); // original wins
-    return [...byId2.values()].map((b) => jsonClone(b));
+    const out = (orig ?? []).map((b) => jsonClone(b));
+    const identities = new Set(out.map(bindingIdentity));
+    const ids = new Set(out.map((b) => b.id).filter((id) => typeof id === 'string'));
+    for (const b of edited ?? []) {
+        const identity = bindingIdentity(b);
+        if (identities.has(identity))
+            continue;
+        identities.add(identity);
+        const row = jsonClone(b);
+        if (typeof row.id === 'string' && ids.has(row.id)) {
+            let n = 2;
+            while (ids.has(`${row.id}${n}`))
+                n++;
+            row.id = `${row.id}${n}`;
+        }
+        if (typeof row.id === 'string')
+            ids.add(row.id);
+        out.push(row);
+    }
+    return out;
 }

package/dist/node-placement.d.ts

@@ -0,0 +1,93 @@
+/**
+ * node-placement — where compile puts a node it has no position for, and where
+ * merge moves one the edit added.
+ *
+ * Compile gives every node a placeholder from its emission index,
+ * `x = 256 + 288 × index, y = 144` (`+160` inside a container). Merge replaces
+ * that placeholder on each node the edit added:
+ *
+ * - next to a positioned predecessor in the same container: one slot right;
+ * - else, when the incoming edge comes from the node's own container (the first
+ *   node of a loop body): at the body origin, inside the container's padding;
+ * - else, one slot left of a positioned successor in the same container;
+ * - then the nearest free spot around that candidate.
+ *
+ * Example: the edit inserts `auditLog` between `extractInvoice (448,144)` and
+ * `routeInvoice (640,144)`. The candidate `(640,144)` is taken, so `auditLog`
+ * goes to the first free spot, `(640,264)`.
+ *
+ * A child's position is relative to its container, as on the canvas.
+ *
+ * The position goes where the original stores positions: `layout.nodes[id]`
+ * when it has a `layout.nodes` map, otherwise `node.ui`. Positions are read the
+ * way the designer reads them (flow-workbench `flow-schema`
+ * `workflow-format-conversion.ts` `mergeLayout`): a `layout.nodes[id]` entry
+ * wins over `node.ui`, field by field.
+ *
+ * `findFreePosition` is a copy of flow-workbench `flow-core`
+ * `layout/collision-detection.ts` (same 24 px padding, 40 px step, 50 rings,
+ * offset order, 96 px default size, sticky notes excluded), because the SDK may
+ * not import `@uipath/flow-core` (lint FB015).
+ */
+/** A position on the canvas. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * Compile's placeholder for the `index`-th node it emits.
+ *
+ * @param index - The node's emission index in the file.
+ * @param nested - Whether the node sits inside a container.
+ * @returns The placeholder position.
+ */
+export declare function placeholderPosition(index: number, nested: boolean): Point;
+/**
+ * Whether `p` is a compile placeholder rather than a position someone chose.
+ * An author `.layout()` entry that happens to hit the same grid point reads as
+ * a placeholder; that is the one ambiguity.
+ */
+export declare function isPlaceholderPosition(p: Point | undefined): boolean;
+/** A node's `ui` (or its `layout.nodes` entry): the fields placement reads. */
+interface Ui {
+    position?: Point;
+    size?: {
+        width?: number;
+        height?: number;
+    };
+    [k: string]: unknown;
+}
+/** A node as merge holds it; `ui` is untyped in the file model. */
+interface PlacedNode {
+    id: string;
+    type?: string;
+    parentId?: string;
+    ui?: unknown;
+    [k: string]: unknown;
+}
+/**
+ * Give each node the edit added a position next to its predecessor, in place.
+ *
+ * A node is placed when it is not in the original and its position is a
+ * compile placeholder (an author `.layout()` position is kept). Its candidate,
+ * in order: one slot right of the first predecessor in the same container that
+ * already has a position (an original node, or an added node placed before it);
+ * the body origin, when an edge enters it from its own container; one slot left
+ * of a positioned successor in the same container. With none, the node keeps
+ * its placeholder, and placed nodes avoid it.
+ *
+ * Where the result is written follows the file: when the original stores
+ * positions in `layout.nodes` (every canvas-saved file does), the position goes
+ * there and the placeholder `node.ui` is dropped, so the file has one store;
+ * otherwise `node.ui.position` is updated.
+ *
+ * @param nodes - The merged root nodes (mutated).
+ * @param edges - The merged root edges.
+ * @param layoutNodes - The merged file's `layout.nodes`, or undefined when the original has none (mutated).
+ * @param isAdded - Whether a node id is new in this merge.
+ */
+export declare function placeAddedNodes(nodes: PlacedNode[], edges: ReadonlyArray<{
+    sourceNodeId: string;
+    targetNodeId: string;
+}>, layoutNodes: Record<string, Ui> | undefined, isAdded: (id: string) => boolean): void;
+export {};

package/dist/node-placement.js

@@ -0,0 +1,163 @@
+/**
+ * node-placement — where compile puts a node it has no position for, and where
+ * merge moves one the edit added.
+ *
+ * Compile gives every node a placeholder from its emission index,
+ * `x = 256 + 288 × index, y = 144` (`+160` inside a container). Merge replaces
+ * that placeholder on each node the edit added:
+ *
+ * - next to a positioned predecessor in the same container: one slot right;
+ * - else, when the incoming edge comes from the node's own container (the first
+ *   node of a loop body): at the body origin, inside the container's padding;
+ * - else, one slot left of a positioned successor in the same container;
+ * - then the nearest free spot around that candidate.
+ *
+ * Example: the edit inserts `auditLog` between `extractInvoice (448,144)` and
+ * `routeInvoice (640,144)`. The candidate `(640,144)` is taken, so `auditLog`
+ * goes to the first free spot, `(640,264)`.
+ *
+ * A child's position is relative to its container, as on the canvas.
+ *
+ * The position goes where the original stores positions: `layout.nodes[id]`
+ * when it has a `layout.nodes` map, otherwise `node.ui`. Positions are read the
+ * way the designer reads them (flow-workbench `flow-schema`
+ * `workflow-format-conversion.ts` `mergeLayout`): a `layout.nodes[id]` entry
+ * wins over `node.ui`, field by field.
+ *
+ * `findFreePosition` is a copy of flow-workbench `flow-core`
+ * `layout/collision-detection.ts` (same 24 px padding, 40 px step, 50 rings,
+ * offset order, 96 px default size, sticky notes excluded), because the SDK may
+ * not import `@uipath/flow-core` (lint FB015).
+ */
+// Sticky notes may overlap anything (flow-core skips them in collisions).
+import { STICKY_NOTE_TYPE } from './core/definitionless-node-types.js';
+/** Where compile's placeholder row starts, and its spacing. */
+const PLACEHOLDER = { x0: 256, dx: 288, y0: 144, nestedDy: 160 };
+/** The default node box the canvas assumes (flow-core `resolveWidth`/`resolveHeight`). */
+const DEFAULT_SIZE = 96;
+/** One slot to the right of a node: its width plus an equal gap, the spacing of a canvas row. */
+const SLOT_DX = 192;
+/** flow-core `findFreePosition` defaults. */
+const PADDING = 24;
+const STEP = 40;
+const MAX_RINGS = 50;
+/**
+ * Where a container's first body node goes, relative to the container: inside
+ * its left and top padding (flow-core `defaultContainerFit`: 144 left, 96 top).
+ */
+const BODY_ORIGIN = { x: 144, y: 96 };
+/**
+ * Compile's placeholder for the `index`-th node it emits.
+ *
+ * @param index - The node's emission index in the file.
+ * @param nested - Whether the node sits inside a container.
+ * @returns The placeholder position.
+ */
+export function placeholderPosition(index, nested) {
+    return { x: PLACEHOLDER.x0 + index * PLACEHOLDER.dx, y: PLACEHOLDER.y0 + (nested ? PLACEHOLDER.nestedDy : 0) };
+}
+/**
+ * Whether `p` is a compile placeholder rather than a position someone chose.
+ * An author `.layout()` entry that happens to hit the same grid point reads as
+ * a placeholder; that is the one ambiguity.
+ */
+export function isPlaceholderPosition(p) {
+    if (!p)
+        return false;
+    const k = (p.x - PLACEHOLDER.x0) / PLACEHOLDER.dx;
+    return Number.isInteger(k) && k >= 0 && (p.y === PLACEHOLDER.y0 || p.y === PLACEHOLDER.y0 + PLACEHOLDER.nestedDy);
+}
+const overlaps = (a, b) => !(a.x + a.width + PADDING <= b.x || b.x + b.width + PADDING <= a.x
+    || a.y + a.height + PADDING <= b.y || b.y + b.height + PADDING <= a.y);
+/** flow-core `findFreePosition`: the candidate, else the first free spot on rings around it. */
+function findFreePosition(candidate, size, others) {
+    const free = (p) => !others.some((o) => overlaps({ ...p, ...size }, o));
+    if (free(candidate))
+        return candidate;
+    for (let d = STEP; d <= STEP * MAX_RINGS; d += STEP) {
+        for (const [dx, dy] of [[d, 0], [0, d], [d, d], [-d, 0], [0, -d], [-d, -d]]) {
+            const p = { x: candidate.x + dx, y: candidate.y + dy };
+            if (free(p))
+                return p;
+        }
+    }
+    return candidate;
+}
+/**
+ * Give each node the edit added a position next to its predecessor, in place.
+ *
+ * A node is placed when it is not in the original and its position is a
+ * compile placeholder (an author `.layout()` position is kept). Its candidate,
+ * in order: one slot right of the first predecessor in the same container that
+ * already has a position (an original node, or an added node placed before it);
+ * the body origin, when an edge enters it from its own container; one slot left
+ * of a positioned successor in the same container. With none, the node keeps
+ * its placeholder, and placed nodes avoid it.
+ *
+ * Where the result is written follows the file: when the original stores
+ * positions in `layout.nodes` (every canvas-saved file does), the position goes
+ * there and the placeholder `node.ui` is dropped, so the file has one store;
+ * otherwise `node.ui.position` is updated.
+ *
+ * @param nodes - The merged root nodes (mutated).
+ * @param edges - The merged root edges.
+ * @param layoutNodes - The merged file's `layout.nodes`, or undefined when the original has none (mutated).
+ * @param isAdded - Whether a node id is new in this merge.
+ */
+export function placeAddedNodes(nodes, edges, layoutNodes, isAdded) {
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const uiOf = (n) => {
+        const entry = layoutNodes?.[n.id];
+        const own = n.ui;
+        return entry ? { ...own, ...entry } : own;
+    };
+    const sizeOf = (n) => ({
+        width: uiOf(n)?.size?.width ?? DEFAULT_SIZE,
+        height: uiOf(n)?.size?.height ?? DEFAULT_SIZE,
+    });
+    const pending = new Set(nodes.filter((n) => isAdded(n.id) && n.type !== STICKY_NOTE_TYPE && isPlaceholderPosition(uiOf(n)?.position)).map((n) => n.id));
+    const positioned = (id) => {
+        const n = byId.get(id);
+        return n !== undefined && !pending.has(id) && uiOf(n)?.position !== undefined;
+    };
+    // Place in waves, so a run of added nodes chains off the first one placed.
+    for (let progress = true; progress && pending.size > 0;) {
+        progress = false;
+        for (const id of [...pending]) {
+            const n = byId.get(id);
+            const sameScope = (other) => byId.get(other)?.parentId === n.parentId;
+            const pred = edges.find((e) => e.targetNodeId === id && sameScope(e.sourceNodeId) && positioned(e.sourceNodeId));
+            const entersBody = !pred && n.parentId !== undefined && byId.has(n.parentId)
+                && edges.some((e) => e.targetNodeId === id && e.sourceNodeId === n.parentId);
+            const succ = pred || entersBody ? undefined
+                : edges.find((e) => e.sourceNodeId === id && sameScope(e.targetNodeId) && positioned(e.targetNodeId));
+            let candidate;
+            if (pred || succ) {
+                const anchor = uiOf(byId.get(pred?.sourceNodeId ?? succ.targetNodeId)).position;
+                candidate = { x: anchor.x + (pred ? SLOT_DX : -SLOT_DX), y: anchor.y };
+            }
+            else if (entersBody) {
+                candidate = { ...BODY_ORIGIN };
+            }
+            else {
+                continue;
+            }
+            // Still-pending nodes count at their placeholder: one that never finds an
+            // anchor stays there, and nothing may land on it.
+            const others = nodes
+                .filter((o) => o.id !== id && o.parentId === n.parentId && o.type !== STICKY_NOTE_TYPE && uiOf(o)?.position !== undefined)
+                .map((o) => ({ ...uiOf(o).position, ...sizeOf(o) }));
+            const position = findFreePosition(candidate, sizeOf(n), others);
+            const ui = { ...uiOf(n), position };
+            if (layoutNodes) {
+                layoutNodes[id] = ui;
+                delete n.ui;
+            }
+            else {
+                n.ui = ui;
+            }
+            pending.delete(id);
+            progress = true;
+        }
+    }
+}

package/dist/nodes/transform/flow/node-type.js

@@ -7,6 +7,7 @@
  * codes and messages unchanged.
  */
 import { Expr } from '../../../core/expr.js';
+import { wireExprBody } from '../../../core/wire-expr.js';
 import { jsonClone } from '../../../core/json-file.js';
 import { VARIANT_OPERATION } from './spec.js';
 import { checkTransform } from './check.js';
@@ -139,7 +140,7 @@ function liftTransform(node, variant, ctx) {
     return {
         kind: 'transform',
         inputs: {
-            collection: (raw !== undefined ? new Expr(raw.startsWith('=js:') ? raw.slice(4) : raw) : undefined),
+            collection: (raw !== undefined ? new Expr(wireExprBody(raw)) : undefined),
             ...(variant ? { variant } : {}),
             operations: operations,
         },

package/dist/registry/uip/pipeline-front-door.js

@@ -20,7 +20,9 @@
  *      folder and every folder above it, then `PATH`.
  *
  * The block brings its own imports, `existsSync` among them, and defines
- * `run(verb, args)`; the pipeline body uses both. Nothing in it names a path on
+ * `frontDoor` (`{ via: 'uip' | 'sdk', file, prefix }`) and `run(verb, args)`;
+ * the pipeline body uses them. `via` says which door won, because on Windows
+ * `file` is node.exe or a full path, never the bare name. Nothing in it names a path on
  * the machine that generated it, so a pipeline stays relocatable.
  *
  * Example, for `kind = 'flow'` on a machine whose `uip` has the commands:
@@ -61,7 +63,7 @@ function uipFrontDoor() {
     return undefined; // a uip shim that cannot be read: use the SDK instead
   }
   const probe = spawnSync(uip.file, [...uip.args, 'maestro', KIND, 'compile', '--help'], { stdio: 'ignore' });
-  return !probe.error && probe.status === 0 ? { file: uip.file, prefix: [...uip.args, 'maestro', KIND] } : undefined;
+  return !probe.error && probe.status === 0 ? { via: 'uip', file: uip.file, prefix: [...uip.args, 'maestro', KIND] } : undefined;
 }
 
 // 2. The SDK's flow-sdk bin, where \`npx --no-install flow-sdk\` looked for it.
@@ -78,7 +80,7 @@ function sdkFrontDoor() {
     const local = bins.map((bin) => join(bin, 'flow-sdk')).find((p) => existsSync(p));
     sdk = { file: local ?? 'flow-sdk', args: [] };
   }
-  return { file: sdk.file, prefix: [...sdk.args, KIND] };
+  return { via: 'sdk', file: sdk.file, prefix: [...sdk.args, KIND] };
 }
 
 const frontDoor = uipFrontDoor() ?? sdkFrontDoor();