@uipath/maestro-builder-sdk 6.41.1 → 6.42.0

package/dist/cli/commands/registry.js

@@ -233,4 +233,19 @@ export function registerRegistryCommands(program) {
         addValue(argv, '--limit', options.limit);
         await invoke('registry search', () => import('../../registry/search-cli.js'), argv);
     });
+    family.command('describe')
+        .description("Print one connector operation's page, from the prepared copy first, then the library.")
+        .argument('<node-type>', 'the nodeType that registry search returns')
+        .option('--connector-version <version>', 'the operation version (default: the newest)')
+        .option('--object <name>', 'the object of a generic operation, as registry search names it')
+        .option('--library <dir>', 'extracted library-json directory (default: the cached one)')
+        .option('--connectors-local <dir>', 'the prepared overlay (default: .flow-sdk/connectors-local)')
+        .action(async (nodeType, options) => {
+        const argv = [nodeType];
+        addValue(argv, '--connector-version', options.connectorVersion);
+        addValue(argv, '--object', options.object);
+        addValue(argv, '--library', options.library);
+        addValue(argv, '--connectors-local', options.connectorsLocal);
+        await invoke('registry describe', () => import('../../registry/describe-cli.js'), argv);
+    });
 }

package/dist/core/cli-spelling.d.ts

@@ -49,3 +49,12 @@ export declare function prepareCommand(connectorKey?: string, action?: string, .
  * @returns `channel:profile.email=d@x.com` as is; `'users[*]:profile.real_name=Coder Evals'` quoted.
  */
 export declare function resolveFlagArg(field: string, by: string, value: string): string;
+/**
+ * The command a message tells a person or agent to run when the cache is
+ * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
+ * pull` runs this package's pull and fills the same cache, and it is the one
+ * command the authoring skill teaches. Each message used to spell the command
+ * out by hand, so they kept naming the SDK's own entry point after the skill
+ * moved to `uip`. Name it here once.
+ */
+export declare const PULL_COMMAND = "uip maestro registry pull";

package/dist/core/cli-spelling.js

@@ -88,3 +88,12 @@ export function resolveFlagArg(field, by, value) {
         return arg;
     return `'${arg.replaceAll("'", `'\\''`)}'`;
 }
+/**
+ * The command a message tells a person or agent to run when the cache is
+ * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
+ * pull` runs this package's pull and fills the same cache, and it is the one
+ * command the authoring skill teaches. Each message used to spell the command
+ * out by hand, so they kept naming the SDK's own entry point after the skill
+ * moved to `uip`. Name it here once.
+ */
+export const PULL_COMMAND = 'uip maestro registry pull';

package/dist/core/library-cache.d.ts

@@ -21,15 +21,6 @@
 export declare const LIBRARY_JSON_DIR = "library-json";
 export declare const LIBRARY_MARKDOWN_DIR = "library-md";
 export declare const CURRENT_LINK = "current";
-/**
- * The command a message tells a person or agent to run when the cache is
- * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
- * pull` runs this package's pull and fills the same cache, and it is the one
- * command the authoring skill teaches. Each message used to spell the command
- * out by hand, so they kept naming the SDK's own entry point after the skill
- * moved to `uip`. Name it here once.
- */
-export declare const PULL_COMMAND = "uip maestro registry pull";
 /**
  * Root of the library cache. `UIP_FLOW_SDK_LIBRARY_CACHE` overrides it.
  *

package/dist/core/library-cache.js

@@ -24,15 +24,6 @@ import { join } from "node:path";
 export const LIBRARY_JSON_DIR = "library-json";
 export const LIBRARY_MARKDOWN_DIR = "library-md";
 export const CURRENT_LINK = "current";
-/**
- * The command a message tells a person or agent to run when the cache is
- * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
- * pull` runs this package's pull and fills the same cache, and it is the one
- * command the authoring skill teaches. Each message used to spell the command
- * out by hand, so they kept naming the SDK's own entry point after the skill
- * moved to `uip`. Name it here once.
- */
-export const PULL_COMMAND = "uip maestro registry pull";
 /**
  * Root of the library cache. `UIP_FLOW_SDK_LIBRARY_CACHE` overrides it.
  *

package/dist/core/library.d.ts

@@ -1,3 +1,12 @@
+/**
+ * library — resolve Integration Service connector definitions from the on-disk
+ * connector library cache (the same `library-json` the Flow Code arm uses).
+ *
+ * For a connector action we need two files per action:
+ *   <key>/<action>@<ver>.json        the entry (connector key, HTTP method, endpoint)
+ *   <key>/<action>@<ver>.v1def.json  the Flow `definitions[]` shape (model, ports, …)
+ */
+import { type ReadText } from './read-text.js';
 import { type LookupResolutions, type LookupSpec } from './lookups.js';
 import type { ByoaEventFacts, ByoaLedger } from './byoa.js';
 export interface ResolvedConnector {
@@ -217,8 +226,27 @@ export interface LibraryOpts {
      * library exposed (a thin `describe` response must not shrink what compiles).
      */
     overlayDir?: string;
+    /** Reads each library and overlay file. Defaults to the disk; a host without one passes its own. */
+    readText?: ReadText;
+    /** Receives the library's warnings. Defaults to stderr; a host without `process` passes its own. */
+    warn?: (message: string) => void;
 }
 export { ConnectorResolveError, type ConnectorResolveCode } from './connector-resolve-error.js';
+/** What `registry describe` renders one operation's page from. */
+export interface PageSource {
+    entry: any;
+    /** The Flow definition beside the entry, or `undefined` when there is none. */
+    v1def: any;
+    version: string;
+    /** True when the operation came from the prepared `connectors-local` overlay. */
+    prepared: boolean;
+    /** The folder the operation came from. */
+    dir: string;
+    /** That layer's index rows. The page names the operation's symbol from them. */
+    rows: readonly any[];
+    /** `objectName`s the ledgers declare connector-invariant. */
+    invariant: ReadonlySet<string>;
+}
 export declare class Library {
     private layers;
     /** The LIST-ENVELOPE LEDGER, overlay first so a prepared entry can add a row. */
@@ -239,6 +267,8 @@ export declare class Library {
     readonly byoaVerifications: ByoaLedger;
     /** Collections the ledger declares connector-invariant; overlay unions over baked. */
     private readonly invariantCollections;
+    private readonly read;
+    private readonly warn;
     constructor(dir: string, opts?: LibraryOpts);
     /**
      * Resolve a connector ACTION (`uipath.connector.<key>.<action>`).
@@ -267,6 +297,23 @@ export declare class Library {
      */
     lookupSpecs(key: string, action: string, version?: string, objectName?: string): Record<string, LookupSpec>;
     resolve(key: string, action: string, version?: string, objectName?: string): ResolvedConnector;
+    /**
+     * One operation's page source, for `registry describe`: the entry and definition
+     * of one index row, from the first layer that carries it. That is the prepared
+     * overlay before the library, the order `resolve` reads in. Without a version, the
+     * newest. A generic operation has a row per object, as `registry pull` writes a
+     * page per object: `objectName` picks the row; without it, the object-less row is
+     * used when there is one, else CONNECTOR_OBJECT_REQUIRED lists the objects. Rows are
+     * chosen as `resolveInLayer` chooses them, so a page shows only what `compile` accepts.
+     */
+    pageSource(nodeType: string, version?: string, objectName?: string): PageSource;
+    /**
+     * The row an object the layer does not list reads its page from, as `resolveInLayer`
+     * case 1 accepts it: the one object-less row of an un-expanded generic operation.
+     * A single non-generic operation takes no object at all.
+     */
+    private connectionScopedRow;
+    private pageOf;
     /**
      * Whether a connector step's schema is materialized locally — see
      * {@link SchemaReadiness}. Index rows are enough for the `object` question

package/dist/core/library.js

@@ -6,10 +6,8 @@
  *   <key>/<action>@<ver>.json        the entry (connector key, HTTP method, endpoint)
  *   <key>/<action>@<ver>.v1def.json  the Flow `definitions[]` shape (model, ports, …)
  */
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { prepareCommand } from './cli-spelling.js';
-import { PULL_COMMAND } from './library-cache.js';
+import { cacheFor, libraryPath, readJson, readTextFromDisk } from './read-text.js';
+import { PULL_COMMAND, prepareCommand } from './cli-spelling.js';
 import { editDistance } from './edit-distance.js';
 import { loadListEnvelopes, lookupListEnvelope } from './list-envelope.js';
 import { lookupSpecOf } from './lookups.js';
@@ -37,26 +35,35 @@ export class Library {
     byoaVerifications;
     /** Collections the ledger declares connector-invariant; overlay unions over baked. */
     invariantCollections;
+    read;
+    warn;
     constructor(dir, opts = {}) {
-        this.lookupResolutions = loadLookupResolutions(opts.overlayDir);
-        this.byoaVerifications = loadByoaLedger(opts.overlayDir);
+        const read = (this.read = opts.readText ?? readTextFromDisk);
+        this.warn = opts.warn ?? ((message) => { globalThis.process?.stderr?.write(message); });
+        // A new identity per Library, so the per-reader caches never keep an overlay file: `prepare` rewrites them.
+        const readOverlay = (path) => read(path);
+        this.lookupResolutions = loadLookupResolutions(opts.overlayDir, readOverlay);
+        this.byoaVerifications = loadByoaLedger(opts.overlayDir, readOverlay);
         this.invariantCollections = new Set([
-            ...loadInvariantCollections(dir),
-            ...loadInvariantCollections(opts.overlayDir),
+            ...loadInvariantCollections(dir, read),
+            ...loadInvariantCollections(opts.overlayDir, readOverlay),
         ]);
         // Overlay first (local wins), then the baked library.
         if (opts.overlayDir) {
-            const oidx = join(opts.overlayDir, 'index.json');
-            if (existsSync(oidx))
-                this.layers.push({ dir: opts.overlayDir, entries: JSON.parse(readFileSync(oidx, 'utf8')).entries ?? [], overlay: true });
-            this.envelopeRows.push(...loadListEnvelopes(opts.overlayDir));
+            const overlayIndex = readOverlay(libraryPath(opts.overlayDir, 'index.json'));
+            if (overlayIndex !== undefined)
+                this.layers.push({ dir: opts.overlayDir, entries: JSON.parse(overlayIndex).entries ?? [], overlay: true });
+            this.envelopeRows.push(...loadListEnvelopes(opts.overlayDir, readOverlay));
         }
-        this.envelopeRows.push(...loadListEnvelopes(dir));
-        const idx = join(dir, 'index.json');
-        if (!existsSync(idx))
-            throw new Error(`connector library not found at ${idx}. Build it first (uipath-flow-v2-setup-library) ` +
-                `or point --library / $FLOW_SDK_LIBRARY_JSON at a library-json dir.`);
-        this.layers.push({ dir, entries: JSON.parse(readFileSync(idx, 'utf8')).entries ?? [] });
+        this.envelopeRows.push(...loadListEnvelopes(dir, read));
+        const idx = libraryPath(dir, 'index.json');
+        const entries = libraryEntries(read, idx);
+        if (entries === undefined)
+            throw new Error(`connector library not found at ${idx}. `
+                + (read === readTextFromDisk
+                    ? `Run \`${PULL_COMMAND}\`, or point --library / $FLOW_SDK_LIBRARY_JSON at a library-json dir.`
+                    : 'The reader passed to Library has no such file.'));
+        this.layers.push({ dir, entries });
     }
     /**
      * Resolve a connector ACTION (`uipath.connector.<key>.<action>`).
@@ -102,6 +109,83 @@ export class Library {
     resolve(key, action, version, objectName) {
         return this.resolveType(`uipath.connector.${key}.${action}`, version, objectName);
     }
+    /**
+     * One operation's page source, for `registry describe`: the entry and definition
+     * of one index row, from the first layer that carries it. That is the prepared
+     * overlay before the library, the order `resolve` reads in. Without a version, the
+     * newest. A generic operation has a row per object, as `registry pull` writes a
+     * page per object: `objectName` picks the row; without it, the object-less row is
+     * used when there is one, else CONNECTOR_OBJECT_REQUIRED lists the objects. Rows are
+     * chosen as `resolveInLayer` chooses them, so a page shows only what `compile` accepts.
+     */
+    pageSource(nodeType, version, objectName) {
+        const layers = this.layers.flatMap((layer) => {
+            const matches = layer.entries.filter((e) => e?.nodeType === nodeType && (!version || String(e.version) === version)
+                && typeof e.path === 'string' && e.path.endsWith('.json'));
+            if (!matches.length)
+                return [];
+            const newest = matches.map((e) => String(e.version))
+                .reduce((a, b) => (b.localeCompare(a, undefined, { numeric: true }) > 0 ? b : a));
+            return [{ layer, rows: matches.filter((e) => String(e.version) === newest) }];
+        });
+        if (!layers.length) {
+            throw new ConnectorResolveError('CONNECTOR_NOT_IN_LIBRARY', `connector not in library: ${nodeType}${version ? '@' + version : ''}.`
+                + this.describeMiss(nodeType, version, undefined, false));
+        }
+        const objects = [...new Set(layers.flatMap(({ rows }) => rows.map((e) => e.objectName)
+                .filter((o) => typeof o === 'string' && o !== '')))].sort();
+        // `compile` refuses a missing object when any layer holds several rows with no one template row.
+        if (objectName === undefined && layers.some(({ rows }) => rows.length > 1 && rows.filter((e) => !e.objectName).length !== 1)) {
+            throw new ConnectorResolveError('CONNECTOR_OBJECT_REQUIRED', `connector ${nodeType} is a GENERIC operation covering ${objects.length} objects — `
+                + `say which one with --object, e.g. --object ${objects[0] ?? '<object>'}. ${describeObjects(objects)}`);
+        }
+        for (const { layer, rows } of layers) {
+            const row = objectName === undefined
+                ? (rows.length === 1 ? rows[0] : rows.find((e) => !e.objectName))
+                : rows.find((e) => e.objectName === objectName) ?? this.connectionScopedRow(nodeType, rows, objectName);
+            if (row)
+                return this.pageOf(nodeType, layer, row);
+        }
+        const parts = nodeType.split('.');
+        const eventNs = parts[2] === 'trigger' || parts[2] === 'event';
+        const near = nearest(objectName ?? '', objects);
+        throw new ConnectorResolveError('CONNECTOR_NOT_IN_LIBRARY', `connector ${nodeType} has no page for object "${objectName}"`
+            + `${near ? ` (nearest: "${near}")` : ''}. ${describeObjects(objects)} If it is a connection-scoped object, run `
+            + `\`${prepareCommand(eventNs ? parts[3] : parts[2], (eventNs ? parts.slice(4) : parts.slice(3)).join('.'), '--object', String(objectName))}\` `
+            + 'to prepare it, then describe again.');
+    }
+    /**
+     * The row an object the layer does not list reads its page from, as `resolveInLayer`
+     * case 1 accepts it: the one object-less row of an un-expanded generic operation.
+     * A single non-generic operation takes no object at all.
+     */
+    connectionScopedRow(nodeType, rows, objectName) {
+        if (rows.length !== 1)
+            return undefined;
+        const only = rows[0];
+        if (only.activityType === 'Generic' || only.activityType === 'GenericTrigger' || only.objectFromDiscovery === true) {
+            return only.objectName ? undefined : only;
+        }
+        throw new ConnectorResolveError('CONNECTOR_OBJECT_NOT_GENERIC', `connector ${nodeType} does not have an object "${objectName}": it is a single, `
+            + `non-generic operation addressing ${only.objectName ? `"${only.objectName}"` : 'no object'}. `
+            + 'Drop --object (it is only for generic operations, whose node type covers many objects).');
+    }
+    pageOf(nodeType, layer, row) {
+        const entryPath = libraryPath(layer.dir, row.path);
+        const entry = readLibraryFile(nodeType, entryPath, () => readJson(this.read, entryPath));
+        const sidecarPath = v1defPathOf(entryPath);
+        const sidecar = this.read(sidecarPath);
+        const raw = sidecar === undefined ? undefined : readLibraryFile(nodeType, sidecarPath, () => JSON.parse(sidecar));
+        return {
+            entry,
+            v1def: Array.isArray(raw) ? raw[0] : raw,
+            version: String(row.version),
+            prepared: layer.overlay === true,
+            dir: layer.dir,
+            rows: layer.entries,
+            invariant: this.invariantCollections,
+        };
+    }
     /**
      * Whether a connector step's schema is materialized locally — see
      * {@link SchemaReadiness}. Index rows are enough for the `object` question
@@ -158,7 +242,7 @@ export class Library {
         let entry;
         try {
             const source = rows.find(({ overlay }) => !overlay) ?? rows[0];
-            entry = JSON.parse(readFileSync(join(source.dir, source.row.path), 'utf8'));
+            entry = readJson(this.read, libraryPath(source.dir, source.row.path));
         }
         catch {
             return undefined;
@@ -191,7 +275,7 @@ export class Library {
                     continue;
                 if (wire.version && indexed.version !== wire.version)
                     continue;
-                const entry = JSON.parse(readFileSync(join(layer.dir, indexed.path), 'utf8'));
+                const entry = readJson(this.read, libraryPath(layer.dir, indexed.path));
                 const operation = entry.operation ?? {};
                 if (wire.httpMethod && String(operation.httpMethod ?? '').toUpperCase() !== wire.httpMethod.toUpperCase())
                     continue;
@@ -289,8 +373,9 @@ export class Library {
                     continue;
                 if (wire.version && indexed.version !== wire.version)
                     continue;
-                const entry = JSON.parse(readFileSync(join(layer.dir, indexed.path), 'utf8'));
-                const operation = normalizeEventOperation({ entry, v1def: readV1def(join(layer.dir, indexed.path)) }).entry.operation ?? {};
+                const entryPath = libraryPath(layer.dir, indexed.path);
+                const entry = readJson(this.read, entryPath);
+                const operation = normalizeEventOperation({ entry, v1def: readV1def(this.read, entryPath) }).entry.operation ?? {};
                 // A GENERIC event's entry names no object — the wire's object is the
                 // author's choice, so it identifies nothing here and comes back as `object`.
                 const generic = operation.activityType === 'GenericTrigger';
@@ -600,7 +685,7 @@ export class Library {
      * `connector not in library: …send-mail-v2.` said nothing that would reveal
      * that. It resorted to grepping the library's JSON out of `node_modules`.
      */
-    describeMiss(nodeType, version, objectName) {
+    describeMiss(nodeType, version, objectName, searched = true) {
         // `uipath.connector.<key>.<op>`, or `uipath.connector.(trigger|event).<key>.<ev>`
         // for the two event namespaces. No connector key contains a dot.
         const parts = nodeType.split('.');
@@ -609,7 +694,8 @@ export class Library {
         const asked = (eventNs ? parts.slice(4) : parts.slice(3)).join('.');
         if (!key)
             return '';
-        const where = ` Searched: ${this.layers.map((l) => l.dir).join(', ')}.`;
+        // `describe` names no folder: on a browser host it is a store the agent cannot open.
+        const where = searched ? ` Searched: ${this.layers.map((l) => l.dir).join(', ')}.` : '';
         if (eventNs)
             return this.describeEventMiss(parts[2], key, asked, where, version, objectName);
         const ops = this.opsUnder(`uipath.connector.${key}.`);
@@ -753,7 +839,7 @@ export class Library {
                     return this.build(layer.dir, { ...only, objectName }, nodeType, { objectNameUnverified: true });
                 }
                 if (only.activityType === 'Generic' || only.objectFromDiscovery === true) {
-                    process.stderr.write(`  warn:  connector ${nodeType}: the library carries this operation un-expanded `
+                    this.warn(`  warn:  connector ${nodeType}: the library carries this operation un-expanded `
                         + `(one object-less entry). Object "${objectName}" is accepted as a connection-scoped `
                         + `object — the schema comes from the generic entry and the tenant resolves the name at `
                         + `dispatch. If it is a typo, compile will not catch it.\n`);
@@ -784,7 +870,7 @@ export class Library {
         // sibling whose path template is exactly `/<its object>` — the only shape a
         // substitution can re-point cleanly.
         const near = nearest(objectName, objects);
-        process.stderr.write(`  warn:  connector ${nodeType}: object "${objectName}" is not one of the `
+        this.warn(`  warn:  connector ${nodeType}: object "${objectName}" is not one of the `
             + `${objects.length} the library lists for it${near ? ` (nearest: "${near}")` : ''}. `
             + `Accepted as a connection-scoped object — the schema comes from a sibling entry and the `
             + `tenant resolves the name at dispatch. If it is a typo, compile will not catch it.\n`);
@@ -800,7 +886,7 @@ export class Library {
     pickDerivationSibling(dir, matches) {
         const templateOf = (e) => {
             try {
-                const entry = JSON.parse(readFileSync(join(dir, e.path), 'utf8'));
+                const entry = readJson(this.read, libraryPath(dir, e.path));
                 return entry.operation?.pathTemplate ?? entry.operation?.path ?? '';
             }
             catch {
@@ -814,14 +900,14 @@ export class Library {
         return substitutable ?? matches[0];
     }
     build(dir, e, nodeType, opts = {}) {
-        const entryPath = join(dir, e.path);
+        const entryPath = libraryPath(dir, e.path);
         // The two files the index row promises. A missing or corrupt one is a fault in
         // the library on disk, not in the author's source, but compile cannot go on
         // without it, so it is a typed refusal like the others: `check` reports it with
         // the same code and text instead of passing a step compile then dies on with a
         // bare ENOENT (#1015).
-        const entry = readLibraryFile(nodeType, entryPath, () => JSON.parse(readFileSync(entryPath, 'utf8')));
-        const v1def = readLibraryFile(nodeType, v1defPathOf(entryPath), () => readV1def(entryPath));
+        const entry = readLibraryFile(nodeType, entryPath, () => readJson(this.read, entryPath));
+        const v1def = readLibraryFile(nodeType, v1defPathOf(entryPath), () => readV1def(this.read, entryPath));
         // A stamped object (case 4) reaches here with the index entry's `objectName`
         // replaced but the sibling's FILE on disk — so restate the object and derive
         // the endpoint from the sibling's own template, rather than shipping a node
@@ -846,7 +932,7 @@ export class Library {
             && entry.operation.objectName !== e.objectName) {
             const stale = entry.operation.objectName;
             const derived = deriveObjectPath(entry.operation, e.objectName);
-            process.stderr.write(`  warn:  connector ${nodeType}: the library index says objectName "${e.objectName}" but its `
+            this.warn(`  warn:  connector ${nodeType}: the library index says objectName "${e.objectName}" but its `
                 + `definition file says "${stale}". Using the index and deriving the endpoint`
                 + (derived.path ? ` (${entry.operation.path} -> ${derived.path})` : '')
                 + `; the definition is the stale side when these disagree.\n`);
@@ -950,13 +1036,28 @@ function v1defPathOf(entryPath) {
  * damaged after it was built: an interrupted pull, a hand-edited overlay. The
  * remedy is the same either way: rebuild the layer the file belongs to.
  */
+/** Each host reader's parsed library index. A library build does not change; the disk default still reads afresh. */
+const INDEX_CACHE = new WeakMap();
+/** The `entries` of the index at `path`, or `undefined` when there is none. */
+function libraryEntries(read, path) {
+    const cache = read === readTextFromDisk ? undefined : cacheFor(INDEX_CACHE, read);
+    const cached = cache?.get(path);
+    if (cached)
+        return cached;
+    const text = read(path);
+    if (text === undefined)
+        return undefined;
+    const entries = JSON.parse(text).entries ?? [];
+    cache?.set(path, entries);
+    return entries;
+}
 function readLibraryFile(nodeType, path, read) {
     try {
         return read();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        // ENOENT already names the path; a JSON SyntaxError does not.
+        // A read error already names the path; a JSON SyntaxError does not.
         const reason = message.includes(path) ? message : `${path}: ${message}`;
         throw new ConnectorResolveError('CONNECTOR_LIBRARY_ENTRY_UNREADABLE', `connector library entry for ${nodeType} is unreadable: ${reason}. The library index lists `
             + `this operation, but the file is missing or not valid JSON, so the library on disk is incomplete. `
@@ -980,8 +1081,8 @@ function readLibraryFile(nodeType, path, read) {
  * reported both its connection and `FolderKey` as "not configured" (UV-16774) while
  * validate and debug — which fold the case — passed.
  */
-function readV1def(entryPath) {
-    const raw = JSON.parse(readFileSync(v1defPathOf(entryPath), 'utf8'));
+function readV1def(read, entryPath) {
+    const raw = readJson(read, v1defPathOf(entryPath));
     const v1def = Array.isArray(raw) ? raw[0] : raw;
     const bindings = v1def?.model?.bindings;
     if (typeof bindings?.resource === 'string' && bindings.resource.toLowerCase() === 'connection') {

package/dist/core/list-envelope.d.ts

@@ -1,3 +1,38 @@
+/**
+ * list-envelope — read the LIST-ENVELOPE LEDGER that sits beside the connector
+ * library's `index.json`.
+ *
+ * ## What the ledger answers
+ *
+ * A connector LIST operation's node output is either the array itself (**bare**,
+ * `envelope: null`) or that array inside a one-field wrapper object
+ * (`envelope: "records"` ⇒ `{records: […]}`). **Nothing in the library declares
+ * which**: `outputSchema.fields` describes ONE record either way, and the two
+ * operations that declare no fields at all sit on opposite sides of what the
+ * corpus guessed ([#156](https://github.com/UiPath/flow-builder-sdk/issues/156)).
+ * It cannot be derived, so it is measured and written down — one row per
+ * operation, each carrying the evidence that put it there.
+ *
+ * ## The rule this file exists to enforce
+ *
+ * **An operation with no row is UNDECLARED, and undeclared means every reader
+ * behaves exactly as it did before the ledger existed.** The emitter declares no
+ * container, and a reader must go on treating an unknown name on a list output as
+ * a possible wrapper. 2,149 of the shipped library's 7,029 entries are List
+ * operations and the ledger holds eight — that ratio is the design, not a gap.
+ * It grows on demand, one measurement at a time.
+ *
+ * Measured 2026-08-02 (card G13, eight `flow debug` / product-runtime readings):
+ * every operation measured so far is **bare**, including both the corpus called
+ * wrappers. The ledger's own `$comment` carries the mechanism and the evidence
+ * tiers; this module only reads it.
+ *
+ * If a second reader is ever needed outside this package, copy this one rather
+ * than sharing it through a new package boundary: a 40-line JSON reader is the
+ * cheaper half. The LEDGER is the single source of truth — the readers are
+ * interchangeable.
+ */
+import { type ReadText } from './read-text.js';
 /** One measured operation. `envelope: null` is the BARE array. */
 export interface ListEnvelopeRow {
     nodeType: string;
@@ -21,7 +56,7 @@ export interface ListEnvelopeRow {
  * an empty ledger — every operation undeclared — which is what a library built
  * before this card, or a bare fixture library, looks like.
  */
-export declare function loadListEnvelopes(libraryDir: string | undefined): ListEnvelopeRow[];
+export declare function loadListEnvelopes(libraryDir: string | undefined, read?: ReadText): ListEnvelopeRow[];
 /**
  * The row for one operation, or `undefined` when it is undeclared.
  *

package/dist/core/list-envelope.js

@@ -32,36 +32,41 @@
  * cheaper half. The LEDGER is the single source of truth — the readers are
  * interchangeable.
  */
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-const CACHE = new Map();
+import { cacheFor, libraryPath, readTextFromDisk } from './read-text.js';
+const CACHE = new WeakMap();
 /**
  * Every declared row, from `<libraryDir>/list-envelopes.json`. An absent file is
  * an empty ledger — every operation undeclared — which is what a library built
  * before this card, or a bare fixture library, looks like.
  */
-export function loadListEnvelopes(libraryDir) {
+export function loadListEnvelopes(libraryDir, read = readTextFromDisk) {
     if (!libraryDir)
         return [];
-    const cached = CACHE.get(libraryDir);
+    const cache = cacheFor(CACHE, read);
+    const cached = cache.get(libraryDir);
     if (cached)
         return cached;
+    let text;
+    try {
+        text = read(libraryPath(libraryDir, 'list-envelopes.json'));
+    }
+    catch {
+        // Not cached: the reader may serve the file on a later call.
+        return [];
+    }
     let rows = [];
-    const file = join(libraryDir, 'list-envelopes.json');
-    if (existsSync(file)) {
-        try {
-            const parsed = JSON.parse(readFileSync(file, 'utf8'));
-            if (Array.isArray(parsed.operations))
-                rows = parsed.operations;
-        }
-        catch {
-            // A malformed ledger reads as an EMPTY one rather than throwing: the
-            // permissive path is the pre-ledger behaviour, so the worst case of a bad
-            // edit is losing the exactness, never breaking a compile.
-            rows = [];
-        }
+    try {
+        const parsed = JSON.parse(text ?? '{}');
+        if (Array.isArray(parsed.operations))
+            rows = parsed.operations;
+    }
+    catch {
+        // A malformed ledger reads as an EMPTY one rather than throwing: the
+        // permissive path is the pre-ledger behaviour, so the worst case of a bad
+        // edit is losing the exactness, never breaking a compile.
+        rows = [];
     }
-    CACHE.set(libraryDir, rows);
+    cache.set(libraryDir, rows);
     return rows;
 }
 /**

package/dist/core/lookup-store.d.ts

@@ -1,3 +1,4 @@
+import { type ReadText } from './read-text.js';
 import type { ByoaLedger } from './byoa.js';
 import type { LookupResolutions } from './lookups.js';
 /**
@@ -8,7 +9,7 @@ import type { LookupResolutions } from './lookups.js';
  * — it is a compile error naming the `prepare` command to run, which is the
  * behaviour an author wants from a missing resolution anyway.
  */
-export declare function loadLookupResolutions(overlayDir: string | undefined): LookupResolutions;
+export declare function loadLookupResolutions(overlayDir: string | undefined, read?: ReadText): LookupResolutions;
 /**
  * Load the `byoa` section of `<overlayDir>/resolutions.json` — the BYOA checks
  * `registry prepare` recorded (see `core/byoa.ts`) — or an empty map.
@@ -19,7 +20,7 @@ export declare function loadLookupResolutions(overlayDir: string | undefined): L
  * call rather than cached: `prepare` rewrites this file, and a stale "never
  * checked" answer would refuse a flow that was just verified.
  */
-export declare function loadByoaLedger(overlayDir: string | undefined): ByoaLedger;
+export declare function loadByoaLedger(overlayDir: string | undefined, read?: ReadText): ByoaLedger;
 /**
  * The invariant-collection ledger's `objectName` set, from a library dir.
  *
@@ -31,4 +32,4 @@ export declare function loadByoaLedger(overlayDir: string | undefined): ByoaLedg
  * @param libraryDir - A `library-json` directory, or the local overlay.
  * @returns Every `objectName` declared connector-invariant.
  */
-export declare function loadInvariantCollections(libraryDir: string | undefined): Set<string>;
+export declare function loadInvariantCollections(libraryDir: string | undefined, read?: ReadText): Set<string>;

package/dist/core/lookup-store.js

@@ -1,5 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { cacheFor, libraryPath, readTextFromDisk } from './read-text.js';
 /**
  * core/lookup-store — the two on-disk side-tables the lookup surface reads.
  *
@@ -14,7 +13,7 @@ import { join } from 'node:path';
  * the CLIs need to read files. Keeping the split makes that structural rather
  * than a thing to remember.
  */
-const RESOLUTION_CACHE = new Map();
+const RESOLUTION_CACHE = new WeakMap();
 /**
  * Load `<overlayDir>/resolutions.json`, or an empty map.
  *
@@ -23,26 +22,32 @@ const RESOLUTION_CACHE = new Map();
  * — it is a compile error naming the `prepare` command to run, which is the
  * behaviour an author wants from a missing resolution anyway.
  */
-export function loadLookupResolutions(overlayDir) {
+export function loadLookupResolutions(overlayDir, read = readTextFromDisk) {
     if (!overlayDir)
         return {};
-    const cached = RESOLUTION_CACHE.get(overlayDir);
+    const cache = cacheFor(RESOLUTION_CACHE, read);
+    const cached = cache.get(overlayDir);
     if (cached)
         return cached;
+    let text;
+    try {
+        text = read(libraryPath(overlayDir, 'resolutions.json'));
+    }
+    catch {
+        // Not cached: the reader may serve the file on a later call.
+        return {};
+    }
     let rows = {};
-    const file = join(overlayDir, 'resolutions.json');
-    if (existsSync(file)) {
-        try {
-            const parsed = JSON.parse(readFileSync(file, 'utf8'));
-            if (parsed.resolutions && typeof parsed.resolutions === 'object') {
-                rows = parsed.resolutions;
-            }
-        }
-        catch {
-            rows = {};
+    try {
+        const parsed = JSON.parse(text ?? '{}');
+        if (parsed.resolutions && typeof parsed.resolutions === 'object') {
+            rows = parsed.resolutions;
         }
     }
-    RESOLUTION_CACHE.set(overlayDir, rows);
+    catch {
+        rows = {};
+    }
+    cache.set(overlayDir, rows);
     return rows;
 }
 /**
@@ -55,14 +60,11 @@ export function loadLookupResolutions(overlayDir) {
  * call rather than cached: `prepare` rewrites this file, and a stale "never
  * checked" answer would refuse a flow that was just verified.
  */
-export function loadByoaLedger(overlayDir) {
+export function loadByoaLedger(overlayDir, read = readTextFromDisk) {
     if (!overlayDir)
         return {};
-    const file = join(overlayDir, 'resolutions.json');
-    if (!existsSync(file))
-        return {};
     try {
-        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        const parsed = JSON.parse(read(libraryPath(overlayDir, 'resolutions.json')) ?? '{}');
         const byoa = parsed?.byoa;
         return byoa && typeof byoa === 'object' && !Array.isArray(byoa) ? byoa : {};
     }
@@ -81,30 +83,36 @@ export function loadByoaLedger(overlayDir) {
  * @param libraryDir - A `library-json` directory, or the local overlay.
  * @returns Every `objectName` declared connector-invariant.
  */
-export function loadInvariantCollections(libraryDir) {
+export function loadInvariantCollections(libraryDir, read = readTextFromDisk) {
     if (!libraryDir)
         return new Set();
-    const cached = INVARIANT_CACHE.get(libraryDir);
+    const cache = cacheFor(INVARIANT_CACHE, read);
+    const cached = cache.get(libraryDir);
     if (cached)
         return cached;
+    let text;
+    try {
+        text = read(libraryPath(libraryDir, 'invariant-collections.json'));
+    }
+    catch {
+        // Not cached: the reader may serve the file on a later call.
+        return new Set();
+    }
     const out = new Set();
-    const file = join(libraryDir, 'invariant-collections.json');
-    if (existsSync(file)) {
-        try {
-            const parsed = JSON.parse(readFileSync(file, 'utf8'));
-            if (Array.isArray(parsed.collections)) {
-                for (const row of parsed.collections) {
-                    const name = row?.objectName;
-                    if (typeof name === 'string')
-                        out.add(name);
-                }
+    try {
+        const parsed = JSON.parse(text ?? '{}');
+        if (Array.isArray(parsed.collections)) {
+            for (const row of parsed.collections) {
+                const name = row?.objectName;
+                if (typeof name === 'string')
+                    out.add(name);
             }
         }
-        catch {
-            /* an empty ledger — see above */
-        }
     }
-    INVARIANT_CACHE.set(libraryDir, out);
+    catch {
+        /* an empty ledger — see above */
+    }
+    cache.set(libraryDir, out);
     return out;
 }
-const INVARIANT_CACHE = new Map();
+const INVARIANT_CACHE = new WeakMap();

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

@@ -0,0 +1,26 @@
+/**
+ * core/read-text — how the connector library reads its files.
+ *
+ * `Library` and `loadLibrary` read every library and overlay file through a
+ * `ReadText`, so a host without a disk can serve them: Studio Web keeps the library
+ * zip in memory and answers each read from it. A read is synchronous because QuickJS
+ * cannot wait on one while it compiles.
+ *
+ * `Library` keeps what a host reader returns for library files (the index and the
+ * ledgers) for as long as the reader lives, because a library build does not change:
+ * pass a new reader for a new build. Overlay files are read afresh each time, because
+ * `prepare` rewrites them.
+ *
+ * The default reads the disk. `node:fs` comes from `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 file's text, or `undefined` when there is none. */
+export type ReadText = (path: string) => string | undefined;
+export declare function readTextFromDisk(path: string): string | undefined;
+/** `dir/rel`. Index paths are relative and `/`-separated. */
+export declare function libraryPath(dir: string, rel: string): string;
+/** The parsed file. A missing one throws an error that names the path. */
+export declare function readJson(read: ReadText, path: string): unknown;
+/** One reader's cache. Two readers can serve different files at the same path. */
+export declare function cacheFor<T>(caches: WeakMap<ReadText, Map<string, T>>, read: ReadText): Map<string, T>;

package/dist/core/read-text.js

@@ -0,0 +1,43 @@
+/**
+ * core/read-text — how the connector library reads its files.
+ *
+ * `Library` and `loadLibrary` read every library and overlay file through a
+ * `ReadText`, so a host without a disk can serve them: Studio Web keeps the library
+ * zip in memory and answers each read from it. A read is synchronous because QuickJS
+ * cannot wait on one while it compiles.
+ *
+ * `Library` keeps what a host reader returns for library files (the index and the
+ * ledgers) for as long as the reader lives, because a library build does not change:
+ * pass a new reader for a new build. Overlay files are read afresh each time, because
+ * `prepare` rewrites them.
+ *
+ * The default reads the disk. `node:fs` comes from `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`.
+ */
+export function readTextFromDisk(path) {
+    const getBuiltinModule = globalThis.process?.getBuiltinModule;
+    if (getBuiltinModule === undefined) {
+        throw new Error(`cannot read ${path}: outside Node, pass a readText function to the connector library`);
+    }
+    const fs = getBuiltinModule('node:fs');
+    return fs.existsSync(path) ? fs.readFileSync(path, 'utf8') : undefined;
+}
+/** `dir/rel`. Index paths are relative and `/`-separated. */
+export function libraryPath(dir, rel) {
+    return dir.endsWith('/') ? `${dir}${rel}` : `${dir}/${rel}`;
+}
+/** The parsed file. A missing one throws an error that names the path. */
+export function readJson(read, path) {
+    const text = read(path);
+    if (text === undefined)
+        throw new Error(`no such file: ${path}`);
+    return JSON.parse(text);
+}
+/** One reader's cache. Two readers can serve different files at the same path. */
+export function cacheFor(caches, read) {
+    let cache = caches.get(read);
+    if (cache === undefined)
+        caches.set(read, (cache = new Map()));
+    return cache;
+}

package/dist/merge-variables.d.ts

@@ -1,4 +1,5 @@
 type Json = unknown;
+type Obj = Record<string, Json>;
 /** JSON with object keys sorted, so key order is not a difference. */
 export declare function stableJson(v: Json): string;
 /**
@@ -16,4 +17,10 @@ export declare function isDeltaSpelling(variables: Json): boolean;
 export declare function mergeVariables(original: Json, edited: Json, baseline: {
     variables?: Json;
 } | undefined, goneNodeIds: Set<string>): Json;
+/**
+ * `o` with the author's changes in `e` applied key by key under the delta rule,
+ * keys in the original's order; `inner` merges a value all three have and the
+ * author changed. Built from entries, so an own `__proto__` key stays a key.
+ */
+export declare function mergeObject(o: Obj, b: Obj, e: Obj, inner: (o: Json, b: Json, e: Json) => Json): Obj;
 export {};

package/dist/merge-variables.js

@@ -75,7 +75,7 @@ export function mergeVariables(original, edited, baseline, goneNodeIds) {
         return copy(edited);
     const orig = isObj(original) ? original : {};
     const baseObj = isObj(base) ? base : {};
-    const out = {};
+    const entries = [];
     for (const key of keysInOrder(orig, edited)) {
         const updates = key === 'variableUpdates';
         const inner = updates
@@ -83,16 +83,16 @@ export function mergeVariables(original, edited, baseline, goneNodeIds) {
             : (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 absent = !has(orig, key) && has(baseObj, key) && has(edited, key) && !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);
+            : mergeKey(own(orig, key), own(baseObj, key), own(edited, key), has(orig, key), has(baseObj, key), has(edited, key), inner);
         if (value !== undefined)
-            out[key] = value;
+            entries.push([key, value]);
     }
-    if (original === undefined && Object.keys(out).length === 0)
+    if (original === undefined && entries.length === 0)
         return undefined;
-    return withoutGoneUpdates(out, goneNodeIds);
+    return withoutGoneUpdates(Object.fromEntries(entries), goneNodeIds);
 }
 /** `undefined` for an empty list or map, so an absent section stays absent. */
 function nonEmpty(v) {
@@ -113,9 +113,29 @@ function withoutGoneUpdates(variables, goneNodeIds) {
         return variables;
     return { ...variables, variableUpdates: Object.fromEntries(Object.entries(updates).filter(([k]) => !goneNodeIds.has(k))) };
 }
+/**
+ * Own keys only, so a key named like an `Object.prototype` member
+ * (`constructor`, `toString`) is not taken as present everywhere.
+ */
+const has = (v, k) => Object.hasOwn(v, k);
+const own = (v, k) => (has(v, k) ? v[k] : undefined);
 /** 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))];
+    return [...Object.keys(original), ...Object.keys(edited).filter((k) => !has(original, k))];
+}
+/**
+ * `o` with the author's changes in `e` applied key by key under the delta rule,
+ * keys in the original's order; `inner` merges a value all three have and the
+ * author changed. Built from entries, so an own `__proto__` key stays a key.
+ */
+export function mergeObject(o, b, e, inner) {
+    const entries = [];
+    for (const key of keysInOrder(o, e)) {
+        const v = mergeKey(own(o, key), own(b, key), own(e, key), has(o, key), has(b, key), has(e, key), inner);
+        if (v !== undefined)
+            entries.push([key, v]);
+    }
+    return Object.fromEntries(entries);
 }
 /**
  * One key's value under the delta rule; `undefined` = leave the key out.
@@ -173,14 +193,7 @@ function insertAt(out, edited, i) {
  * 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;
+    return mergeObject(o, b ?? {}, e, (_o, _b, ev) => copy(ev));
 }
 function idList(v) {
     return Array.isArray(v) && v.every((x) => isObj(x) && typeof x.id === 'string');

package/dist/merge.d.ts

@@ -19,7 +19,8 @@
  *     `edited` is byte-equal to its `baseline` counterpart, the user did NOT
  *     touch it, so the merge keeps the ORIGINAL node verbatim (its real type,
  *     inputs, layout — even for a placeholder). Only nodes the user actually
- *     changed (or added) are taken from `edited`.
+ *     changed (or added) are taken from `edited`, and a changed node takes only
+ *     the fields that differ from the baseline (see withEdits).
  *   - Without a `baseline`, the merge is two-way: it takes `edited`'s graph and
  *     re-attaches the original layout by node-id match. This is correct as long
  *     as decompile was faithful for every node (the common case).

package/dist/merge.js

@@ -19,7 +19,8 @@
  *     `edited` is byte-equal to its `baseline` counterpart, the user did NOT
  *     touch it, so the merge keeps the ORIGINAL node verbatim (its real type,
  *     inputs, layout — even for a placeholder). Only nodes the user actually
- *     changed (or added) are taken from `edited`.
+ *     changed (or added) are taken from `edited`, and a changed node takes only
+ *     the fields that differ from the baseline (see withEdits).
  *   - Without a `baseline`, the merge is two-way: it takes `edited`'s graph and
  *     re-attaches the original layout by node-id match. This is correct as long
  *     as decompile was faithful for every node (the common case).
@@ -85,12 +86,13 @@
  */
 import { bindingIdentity } from './core/binding-identity.js';
 import { jsonClone } from './core/json-clone.js';
+import { isRecord } from './core/node-envelope.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';
 import { mergeAgentSidecars } from './merge-sidecars.js';
 import { embeddedAgentFindings, isEmbeddedAgent, mergeEmbeddedAgentNode } from './merge-embedded-agent.js';
-import { mergeVariables } from './merge-variables.js';
+import { mergeObject, mergeVariables, stableJson } from './merge-variables.js';
 export { MergeRefusedError } from './merge-roundtrip.js';
 function byId(nodes) {
     return new Map((nodes ?? []).map((n) => [n.id, n]));
@@ -163,6 +165,65 @@ function withOriginalLayout(edited, orig, originalLayout) {
     }
     return edited;
 }
+/**
+ * Give `node` the original's `display` with the author's display edits applied,
+ * key by key: a key whose edited value differs from the baseline's is the
+ * author's (a relabel); every other key stays as the original has it. Compile
+ * writes only a label and the type's default icon, so the edited display taken
+ * whole drops a canvas file's `subLabel`, `iconBackground` and custom icon, and
+ * the original's taken whole drops the relabel.
+ */
+function withDisplayEdits(node, orig, e, base) {
+    const o = isRecord(orig.display) ? orig.display : {};
+    const ed = isRecord(e.display) ? e.display : {};
+    const b = isRecord(base.display) ? base.display : {};
+    const display = {};
+    for (const k of new Set([...Object.keys(o), ...Object.keys(ed)])) {
+        const v = sortedJson(ed[k]) === sortedJson(b[k]) ? o[k] : ed[k];
+        if (v !== undefined)
+            display[k] = jsonClone(v);
+    }
+    const next = sortedJson(display) === sortedJson(orig.display ?? {}) ? orig.display : display;
+    if (JSON.stringify(next) === JSON.stringify(node.display))
+        return node;
+    // In place, so the node keeps its key order.
+    const out = { ...node, display: undefined };
+    if (next === undefined)
+        delete out.display;
+    else
+        out.display = jsonClone(next);
+    return out;
+}
+/**
+ * The original with the author's edits applied, by the delta rule of
+ * merge-variables.ts: where `e` equals the baseline `b` the original's value
+ * stays (absent stays absent), and inside objects all three have, the rule
+ * recurses key by key. Lists are taken whole, and so is a changed expression
+ * value, whose `type` says how to read its `expression`: decompile turns a
+ * legacy `{ type: 'literal', expression: '{{ $vars.x }}' }` agent input into a
+ * `jsExpression`, so an edited reference merged key by key would keep
+ * `literal` and hand the agent the text. Applied to an edited node, a
+ * one-input edit to a connector keeps the rest of its `detail` as written, and
+ * compile's `model`, derived `outputs` and other spellings stay out of it.
+ */
+function withEdits(o, b, e) {
+    if (stableJson(e) === stableJson(b))
+        return o === undefined ? o : jsonClone(o);
+    if (!isRecord(o) || !isRecord(b) || !isRecord(e) || isExpressionValue(o) || isExpressionValue(e)) {
+        return e === undefined ? e : jsonClone(e);
+    }
+    return mergeObject(o, b, e, withEdits);
+}
+const isExpressionValue = (v) => typeof v.type === 'string' && Object.hasOwn(v, 'expression');
+/**
+ * Whether an edited node can merge field by field onto its original: all three
+ * have one type and one `typeVersion`. A node whose version the edit or the
+ * round trip moved is taken from `edited` whole, so it never mixes two
+ * versions' inputs.
+ */
+function mergesByField(orig, base, e) {
+    return orig.type === e.type && base.type === e.type && orig.typeVersion === e.typeVersion && base.typeVersion === e.typeVersion;
+}
 /**
  * Give an edited node the original's `inputs.source` when only the round trip
  * changed it (the baseline's equals the edited one's).
@@ -243,18 +304,23 @@ function mergeFlowFindings(original, edited, options) {
     const editedIds = new Set();
     for (const e of edited.nodes ?? []) {
         const orig = origNodes.get(e.id);
+        const base = baseNodes.get(e.id);
         if (isKept(e, origNodes, baseNodes, options.baseline) && orig) {
             // Untouched by the user (equal to the faithful baseline) → keep the
-            // original node exactly, placeholder-safe.
-            finalNodes.push(jsonClone(orig));
+            // original node exactly, placeholder-safe, plus any relabel.
+            finalNodes.push(base ? withDisplayEdits(jsonClone(orig), orig, e, base) : jsonClone(orig));
             keptFromOriginal.add(e.id);
         }
         else {
-            // Added or edited → take the edited node, re-attaching original layout.
+            // Added or edited → the original plus the author's changes, field by
+            // field (withEdits), else the edited node; then re-attach original layout.
             // An EMBEDDED agent stays embedded: the original plus the author's change
             // to the node, never the edited shell whole (#1220, merge-embedded-agent.ts).
-            const node = keepsEmbeddedAgent(orig, e) ? mergeEmbeddedAgentNode(orig, e, baseNodes.get(e.id)) : jsonClone(e);
-            const placed = withOriginalSource(withOriginalLayout(node, orig, layoutNodesOf(original)), orig, baseNodes.get(e.id));
+            const taken = keepsEmbeddedAgent(orig, e) ? mergeEmbeddedAgentNode(orig, e, base)
+                : orig && base && mergesByField(orig, base, e) ? withEdits(orig, base, e)
+                    : jsonClone(e);
+            const node = orig && base ? withDisplayEdits(taken, orig, e, base) : taken;
+            const placed = withOriginalSource(withOriginalLayout(node, orig, layoutNodesOf(original)), orig, base);
             finalNodes.push(placed);
             // Without a baseline every node lands here; count one as edited only
             // when the merged node differs from the original.
@@ -289,6 +355,10 @@ function mergeFlowFindings(original, edited, options) {
         ...(original.nodes ?? []),
         ...Object.values(original.subflows ?? {}).flatMap((sf) => sf?.nodes ?? []),
     ].map((n) => n.id).filter((id) => !mergedNodeIds.has(id)));
+    const layoutNodes = layoutNodesOf(result);
+    if (layoutNodes)
+        for (const id of goneNodeIds)
+            delete layoutNodes[id];
     const variables = mergeVariables(original.variables, edited.variables, options.baseline, goneNodeIds);
     if (variables === undefined)
         delete result.variables;

package/dist/registry/describe-cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Print one connector operation's page: its inputs, outputs, lookups and the code to
+ * write.
+ *
+ * The page comes from where `check` and `compile` read: the flow's prepared
+ * `connectors-local` overlay first, then the library. So after `registry prepare`
+ * it shows the connection's real fields. It is rendered from the entry on each call,
+ * so it needs no `library-md` tree and no file the agent must keep a path to.
+ */
+export declare function run(argv: string[]): Promise<number>;

package/dist/registry/describe-cli.js

@@ -0,0 +1,41 @@
+import { printResult, reportResult } from '../cli-result.js';
+import { flagValue } from '../cli-run.js';
+import { openCliLibrary } from '../core/cli-library.js';
+import { PULL_COMMAND } from '../core/cli-spelling.js';
+import { renderMarkdownPage } from './generators/markdown/index.js';
+import { symbolIndex } from './naming.js';
+/**
+ * Print one connector operation's page: its inputs, outputs, lookups and the code to
+ * write.
+ *
+ * The page comes from where `check` and `compile` read: the flow's prepared
+ * `connectors-local` overlay first, then the library. So after `registry prepare`
+ * it shows the connection's real fields. It is rendered from the entry on each call,
+ * so it needs no `library-md` tree and no file the agent must keep a path to.
+ */
+export async function run(argv) {
+    const nodeType = argv[0];
+    const library = openCliLibrary(argv);
+    if (!library) {
+        console.error(`No connector library is cached. Run \`${PULL_COMMAND}\`, or pass --library <dir>.`);
+        return 2;
+    }
+    let source;
+    try {
+        source = library.pageSource(nodeType, flagValue(argv, '--connector-version'), flagValue(argv, '--object'));
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    // The symbol names `prepare`'s module exports: it counts GenericExpanded entries only when the overlay has one.
+    const expanded = source.prepared && source.rows.some((e) => e?.activityType === 'GenericExpanded');
+    const body = renderMarkdownPage(source.entry, source.v1def, { symbols: symbolIndex(source.rows, expanded), invariant: source.invariant });
+    // No path: on a browser host it names a store the agent cannot open.
+    const origin = source.prepared ? 'the prepared copy from `registry prepare`' : 'the connector library';
+    const page = `> Source: ${origin}\n\n${body.replace(/\n$/, '')}`;
+    // The page alone, so `uip … --output plain` prints just the Markdown.
+    reportResult({ page });
+    printResult(page);
+    return 0;
+}

package/dist/registry/library-reader.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Reading an extracted `library-json/` tree.
+ *
+ * Every generator walks the same index and opens the same two files per
+ * operation. This is that walk, once, with the path rules the Python spelled in
+ * three places: the entry is `index.json`'s `path`, the sidecar is the same path
+ * with `.json` swapped for `.v1def.json`, and a sidecar that is a one-element
+ * list is unwrapped.
+ */
+import { type ReadText } from "../core/read-text.js";
 import type { IndexRow, LibraryEntry, LibraryIndex, V1Definition } from "./model/library.js";
 export interface LoadedLibrary {
     /** The `library-json` directory. */
@@ -14,7 +24,7 @@ export interface LoadedLibrary {
 }
 /** `<path minus .json>.v1def.json`, the sidecar beside an entry. */
 export declare function sidecarPath(entryRelativePath: string): string;
-export declare function readJsonFile(path: string): unknown;
 /** A sidecar may be `[definition]` in some snapshots; the definition is what callers want. */
 export declare function unwrapV1Def(raw: unknown): V1Definition | undefined;
-export declare function loadLibrary(dir: string): LoadedLibrary;
+/** `read` defaults to the disk; a host without one passes its own (`core/read-text.ts`). */
+export declare function loadLibrary(dir: string, read?: ReadText): LoadedLibrary;

package/dist/registry/library-reader.js

@@ -7,16 +7,12 @@
  * with `.json` swapped for `.v1def.json`, and a sidecar that is a one-element
  * list is unwrapped.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { libraryPath, readTextFromDisk } from "../core/read-text.js";
 import { loadInvariantCollections } from "./lookup-specs.js";
 /** `<path minus .json>.v1def.json`, the sidecar beside an entry. */
 export function sidecarPath(entryRelativePath) {
     return `${entryRelativePath.slice(0, -".json".length)}.v1def.json`;
 }
-export function readJsonFile(path) {
-    return JSON.parse(readFileSync(path, "utf8"));
-}
 /** A sidecar may be `[definition]` in some snapshots; the definition is what callers want. */
 export function unwrapV1Def(raw) {
     if (Array.isArray(raw))
@@ -25,26 +21,31 @@ export function unwrapV1Def(raw) {
         return raw;
     return undefined;
 }
-export function loadLibrary(dir) {
-    const indexPath = join(dir, "index.json");
-    if (!existsSync(indexPath)) {
+/** `read` defaults to the disk; a host without one passes its own (`core/read-text.ts`). */
+export function loadLibrary(dir, read = readTextFromDisk) {
+    const indexPath = libraryPath(dir, "index.json");
+    const indexText = read(indexPath);
+    if (indexText === undefined) {
         throw new Error(`library missing index.json: ${indexPath}`);
     }
-    const index = readJsonFile(indexPath);
-    const invariant = loadInvariantCollections(dir);
+    const index = JSON.parse(indexText);
+    const invariant = loadInvariantCollections(dir, read);
+    const readIfPresent = (path) => {
+        const text = read(path);
+        return text === undefined ? undefined : JSON.parse(text);
+    };
     return {
         dir,
         index,
         invariant,
-        entryPath: (row) => join(dir, row.path),
-        v1defPath: (row) => join(dir, sidecarPath(row.path)),
+        entryPath: (row) => libraryPath(dir, row.path),
+        v1defPath: (row) => libraryPath(dir, sidecarPath(row.path)),
         readEntry(row) {
-            const path = join(dir, row.path);
-            return existsSync(path) ? readJsonFile(path) : undefined;
+            return readIfPresent(libraryPath(dir, row.path));
         },
         readV1Def(row) {
-            const path = join(dir, sidecarPath(row.path));
-            return existsSync(path) ? unwrapV1Def(readJsonFile(path)) : undefined;
+            const raw = readIfPresent(libraryPath(dir, sidecarPath(row.path)));
+            return raw === undefined ? undefined : unwrapV1Def(raw);
         },
     };
 }

package/dist/registry/lookup-specs.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Which connector input fields earn a `.by*` helper, and what the helper needs.
+ *
+ * A `reference` with a `lookupValue` says a field's value is an opaque id to be
+ * resolved against a live connection. Two classes are excluded: IDENTITY
+ * lookups, where `lookupValue` is the only `lookupNames` entry so resolving
+ * returns what it was given, and INVARIANT collections, whose ids are a property
+ * of the connector's API rather than of a connection (a country list), read from
+ * the curated `invariant-collections.json` ledger. Everything else is a lookup;
+ * the fallback direction is the safe one.
+ *
+ * Ported from `integrations/scripts/_lookups.py` and the `lookup_specs` half of
+ * `generate_connectors_ts.py`. `core/lookups.ts` keeps `check` and `compile`
+ * agreeing with this by importing it.
+ */
+import { type ReadText } from "../core/read-text.js";
 import type { FieldReference, LibraryField } from "./model/library.js";
 export declare const LEDGER_FILENAME = "invariant-collections.json";
 /**
@@ -5,7 +21,7 @@ export declare const LEDGER_FILENAME = "invariant-collections.json";
  * ledger reads as empty rather than raising: the permissive path is the
  * pre-ledger behaviour, so a bad edit loses exactness, never a build.
  */
-export declare function loadInvariantCollections(libraryDir: string | undefined): Set<string>;
+export declare function loadInvariantCollections(libraryDir: string | undefined, read?: ReadText): Set<string>;
 /** The field's `reference` block when it declares a resolvable value. */
 export declare function referenceOf(field: {
     reference?: unknown;

package/dist/registry/lookup-specs.js

@@ -13,8 +13,7 @@
  * `generate_connectors_ts.py`. `core/lookups.ts` keeps `check` and `compile`
  * agreeing with this by importing it.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { libraryPath, readTextFromDisk } from "../core/read-text.js";
 import { pyTruthy } from "./generators/type-tree.js";
 import { byAliases } from "./naming.js";
 export const LEDGER_FILENAME = "invariant-collections.json";
@@ -23,15 +22,12 @@ export const LEDGER_FILENAME = "invariant-collections.json";
  * ledger reads as empty rather than raising: the permissive path is the
  * pre-ledger behaviour, so a bad edit loses exactness, never a build.
  */
-export function loadInvariantCollections(libraryDir) {
+export function loadInvariantCollections(libraryDir, read = readTextFromDisk) {
     if (!libraryDir)
         return new Set();
-    const path = join(libraryDir, LEDGER_FILENAME);
-    if (!existsSync(path))
-        return new Set();
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(path, "utf8"));
+        parsed = JSON.parse(read(libraryPath(libraryDir, LEDGER_FILENAME)) ?? "{}");
     }
     catch {
         return new Set();

package/dist/registry/path-cli.js

@@ -1,6 +1,7 @@
 import { printResult, reportResult } from '../cli-result.js';
 import { join } from "node:path";
-import { CURRENT_LINK, PULL_COMMAND, currentEntrySha, libraryCacheRoot, resolveCachedLibrary, resolveCachedMarkdown, } from "../core/library-cache.js";
+import { PULL_COMMAND } from "../core/cli-spelling.js";
+import { CURRENT_LINK, currentEntrySha, libraryCacheRoot, resolveCachedLibrary, resolveCachedMarkdown, } from "../core/library-cache.js";
 /**
  * Say where the connector library is.
  *

package/dist/registry/search-cli.js

@@ -1,6 +1,7 @@
 import { printResult, reportResult } from '../cli-result.js';
 import { readFile, stat } from "node:fs/promises";
-import { PULL_COMMAND, resolveLibraryDir } from "../core/library-cache.js";
+import { PULL_COMMAND } from "../core/cli-spelling.js";
+import { resolveLibraryDir } from "../core/library-cache.js";
 import { dirname, join } from "node:path";
 export const DEFAULT_SEARCH_LIMIT = 20;
 const USAGE = "Usage: flow-sdk registry search [query] [--library <dir>] [--library-md <dir>] [--connector <key>] [--limit <n>]";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.41.1",
+  "version": "6.42.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": "33d3681001ebbd858c7f3f2ec8a121cce7d56bbb"
+  "gitref": "167eb5f8f1c8f3f5d039cf72e7c901e3b4737cb6"
 }