@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

package/dist/registry/prepare/overlay.js

@@ -0,0 +1,487 @@
+/**
+ * The `./connectors-local/` overlay: how one prepared operation is merged into
+ * it, and what `prepare` reads back out of it afterwards.
+ *
+ * Calls ACCUMULATE — each prepared op merges into the overlay rather than
+ * replacing it — and Generic object variants intentionally share a nodeType,
+ * so the identity of an entry is `(nodeType, version, objectName)`, never the
+ * nodeType alone. Descriptors live under `descriptors/<key>/…`; an overlay
+ * written before that rule is migrated on the next merge.
+ *
+ * Everything the summary and the notes need afterwards — field counts, the
+ * parent declarations, the lookup vocabulary — is read back from the overlay
+ * just written rather than recomputed, so a resolution is made against the
+ * SAME schema the descriptors were generated from, including any
+ * connection-resolved field that only exists because this `prepare` ran.
+ *
+ * Ported from `merge_into`, `_descriptor_overlay_path`,
+ * `_migrate_legacy_descriptor_roots`, `_overlay_has_generic_expanded`,
+ * `_count_input_fields`, `_parent_fields`, `_schema_action_parents`,
+ * `_keep_prepared_schema` and `_lookup_specs_from_overlay` in
+ * `prepare_connector.py`.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { pyJsonDocument } from "../codecs/pyjson.js";
+import { sortedByKeys, sortedStrings } from "../compat/compare.js";
+import { toPosix } from "../compat/paths.js";
+import { lookupSpecs } from "../generators/fields.js";
+import { SCHEMA_VERSION } from "../library-build/canonical.js";
+import { sidecarPath, unwrapV1Def } from "../library-reader.js";
+import { catalogReferences, loadInvariantCollections, specsFromFields } from "../lookup-specs.js";
+import { isEventNodeType } from "../model/library.js";
+import { isPlainObject, pyGet, pyOr, pyStrAny, pyTruthy, pyTypeName } from "./support.js";
+export const INDEX_FILENAME = "index.json";
+export const DESCRIPTORS_ROOT = "descriptors";
+/**
+ * `_variant_key`: identity for one resolvable activity schema variant. Keying
+ * only by nodeType made the last prepared object overwrite every earlier one.
+ */
+export function variantKey(entry) {
+    return JSON.stringify([pyGet(entry, "nodeType", ""), pyGet(entry, "version", ""), pyGet(entry, "objectName", "")]);
+}
+/** `Path(p).parts` for a relative POSIX path: empties and `.` collapse, `..` is kept. */
+function pathParts(p) {
+    return toPosix(p)
+        .split("/")
+        .filter((part) => part !== "" && part !== ".");
+}
+/** `_descriptor_overlay_path`: `<key>/op@1.json` → `descriptors/<key>/op@1.json`; already-rooted paths pass through. */
+export function descriptorOverlayPath(path) {
+    const parts = pathParts(path);
+    if (parts.length > 0 && parts[0] === DESCRIPTORS_ROOT)
+        return parts.join("/");
+    return [DESCRIPTORS_ROOT, ...parts].join("/");
+}
+/**
+ * `_migrate_legacy_descriptor_roots`: move `<dst>/<key>/**` written by an
+ * earlier `prepare` under `<dst>/descriptors/<key>/**`, bottom-up, leaving no
+ * empty directory behind. Only roots the index still names are touched.
+ */
+export function migrateLegacyDescriptorRoots(dst, entries) {
+    const legacyRoots = new Set();
+    for (const entry of entries) {
+        if (!isPlainObject(entry))
+            continue;
+        const path = pyGet(entry, "path", null);
+        if (!pyTruthy(path))
+            continue;
+        const parts = pathParts(pyStrAny(path));
+        if (parts.length > 0 && parts[0] !== DESCRIPTORS_ROOT)
+            legacyRoots.add(parts[0]);
+    }
+    for (const legacyRoot of sortedStrings(legacyRoots)) {
+        const sourceRoot = join(dst, legacyRoot);
+        if (!existsSync(sourceRoot) || !statSync(sourceRoot).isDirectory())
+            continue;
+        const destinationRoot = join(dst, DESCRIPTORS_ROOT, legacyRoot);
+        const walk = (dir) => {
+            const children = readdirSync(dir, { withFileTypes: true });
+            const subdirs = children.filter((c) => c.isDirectory()).map((c) => c.name);
+            // `os.walk(topdown=False)`: the children are handled before their parent.
+            for (const name of subdirs)
+                walk(join(dir, name));
+            const destination = join(destinationRoot, toPosix(dir.slice(sourceRoot.length)).replace(/^\//, ""));
+            mkdirSync(destination, { recursive: true });
+            for (const child of children) {
+                if (child.isFile())
+                    renameSync(join(dir, child.name), join(destination, child.name));
+            }
+            for (const name of subdirs)
+                rmdirSync(join(dir, name));
+        };
+        walk(sourceRoot);
+        rmdirSync(sourceRoot);
+    }
+}
+function sortKey(entry, key) {
+    return pyStrAny(pyGet(entry, key, ""));
+}
+/**
+ * The overlay index rows after merging `srcEntries` over `dstEntries`: every
+ * row's `path` under `descriptors/`, a same-variant row refreshed, a new
+ * variant added, and the whole list sorted by
+ * `(connectorKey, nodeType, version, objectName, path)`. Pure — the inputs
+ * are copied, not rewritten.
+ */
+export function mergeIndexEntries(dstEntries, srcEntries) {
+    const byVariant = new Map();
+    const place = (raw) => {
+        if (!isPlainObject(raw))
+            throw new TypeError("index entry is not an object"); // Python: `entry["path"]` on a non-dict
+        if (!Object.prototype.hasOwnProperty.call(raw, "path"))
+            throw new Error("KeyError: 'path'");
+        const entry = { ...raw, path: descriptorOverlayPath(pyStrAny(raw.path)) };
+        byVariant.set(variantKey(entry), entry);
+    };
+    for (const entry of dstEntries)
+        place(entry);
+    // Re-preparing the same object refreshes it; preparing a different object
+    // accumulates a sibling variant under the shared generic nodeType.
+    for (const entry of srcEntries)
+        place(entry);
+    return sortedByKeys([...byVariant.values()], (e) => sortKey(e, "connectorKey"), (e) => sortKey(e, "nodeType"), (e) => sortKey(e, "version"), (e) => sortKey(e, "objectName"), (e) => sortKey(e, "path"));
+}
+/**
+ * The bytes `connectors-local/index.json` is written in.
+ *
+ * INTENTIONAL DIVERGENCE from the Python, which wrote `json.dump(idx, indent=2)`
+ * with no trailing newline — the one file in the overlay without one, since
+ * `write_library` and the ledger both appended it. Every other JSON document
+ * the registry writes ends in a newline, and the overlay index now does too,
+ * so a diff of a re-prepared overlay stops showing a "\ No newline at end of
+ * file" marker on the index alone.
+ */
+export function formatOverlayIndex(index) {
+    return pyJsonDocument(index);
+}
+/** `<dir>/index.json` parsed, or `undefined` when there is no file (a broken file throws, as `json.load` did). */
+function readIndex(dir) {
+    const path = join(dir, INDEX_FILENAME);
+    if (!existsSync(path))
+        return undefined;
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+/**
+ * `merge_into` over an in-memory library: the shape `planLibrary` produces.
+ * `files` must carry `index.json`; every other file is copied under
+ * `descriptors/` (a nested `index.json` is skipped, as the Python's walk did).
+ */
+export function mergeFilesInto(files, dst) {
+    mkdirSync(dst, { recursive: true });
+    const srcIndexText = files.get(INDEX_FILENAME);
+    if (srcIndexText === undefined)
+        throw new Error(`merge_into: ${INDEX_FILENAME} missing from the prepared library`);
+    const srcIdx = JSON.parse(typeof srcIndexText === "string" ? srcIndexText : Buffer.from(srcIndexText).toString("utf8"));
+    const dstIdxRaw = readIndex(dst);
+    // A parseable index that is not an object is REFUSED, not replaced. The
+    // Python's `dst_idx.get("entries", [])` raised on a list, a string or a null
+    // and wrote nothing, so an overlay some other tool has mangled stays the
+    // author's to fix; silently starting a fresh index would discard every
+    // descriptor it still names. Only a MISSING file starts one.
+    if (dstIdxRaw !== undefined && !isPlainObject(dstIdxRaw)) {
+        throw new TypeError(`${join(dst, INDEX_FILENAME)}: expected a JSON object, found ${pyTypeName(dstIdxRaw)}`);
+    }
+    const dstIdx = dstIdxRaw === undefined ? { schemaVersion: SCHEMA_VERSION, entries: [] } : { ...dstIdxRaw };
+    const dstEntries = pyGet(dstIdx, "entries", []);
+    if (!Array.isArray(dstEntries))
+        throw new TypeError("index.json: \"entries\" is not a list");
+    migrateLegacyDescriptorRoots(dst, dstEntries);
+    const srcEntries = isPlainObject(srcIdx) ? pyGet(srcIdx, "entries", []) : [];
+    dstIdx.entries = mergeIndexEntries(dstEntries, Array.isArray(srcEntries) ? srcEntries : []);
+    writeFileSync(join(dst, INDEX_FILENAME), formatOverlayIndex(dstIdx), "utf8");
+    for (const [rel, content] of files) {
+        if (basename(rel) === INDEX_FILENAME)
+            continue;
+        const out = join(dst, ...descriptorOverlayPath(rel).split("/"));
+        mkdirSync(dirname(out), { recursive: true });
+        writeFileSync(out, content);
+    }
+}
+/** Every file under `root`, as `POSIX-relative path → bytes`. */
+function readTree(root) {
+    const files = new Map();
+    const walk = (dir, prefix) => {
+        for (const child of readdirSync(dir, { withFileTypes: true })) {
+            const rel = prefix ? `${prefix}/${child.name}` : child.name;
+            if (child.isDirectory())
+                walk(join(dir, child.name), rel);
+            else if (child.isFile())
+                files.set(rel, new Uint8Array(readFileSync(join(dir, child.name))));
+        }
+    };
+    walk(root, "");
+    return files;
+}
+/** `merge_into(src, dst)`: merge a freshly written single-op library directory into the overlay. */
+export function mergeInto(src, dst) {
+    mergeFilesInto(readTree(src), dst);
+}
+/** `_overlay_has_generic_expanded`: does the overlay hold ANY `GenericExpanded` entry, from any prepare? */
+export function overlayHasGenericExpanded(out) {
+    let index;
+    try {
+        index = readIndex(out);
+    }
+    catch {
+        return false;
+    }
+    if (!isPlainObject(index))
+        return false;
+    const entries = pyOr(pyGet(index, "entries", null), []);
+    if (!Array.isArray(entries))
+        return false;
+    return entries.some((e) => isPlainObject(e) && e.activityType === "GenericExpanded");
+}
+/** A reader over a directory on disk. */
+export function directoryReader(dir) {
+    return (rel) => JSON.parse(readFileSync(join(dir, ...rel.split("/")), "utf8"));
+}
+/** A reader over an in-memory library (`planLibrary`'s `files`), for the staged half of {@link keepPreparedSchema}. */
+export function filesReader(files) {
+    return (rel) => {
+        const text = files.get(rel);
+        if (text === undefined)
+            throw new Error(`ENOENT: ${rel}`);
+        return JSON.parse(typeof text === "string" ? text : Buffer.from(text).toString("utf8"));
+    };
+}
+function requireKey(record, key) {
+    if (!isPlainObject(record))
+        throw new TypeError(`'${record === null ? "NoneType" : typeof record}' object is not subscriptable`);
+    if (!Object.prototype.hasOwnProperty.call(record, key))
+        throw new Error(`KeyError: ${JSON.stringify(key)}`);
+    return record[key];
+}
+/**
+ * The index rows for `nodeType`, narrowed to `objectName` when one is given
+ * (`object_name is not None` in the Python: an empty string IS a filter).
+ * Throws on any shape the Python's `except` clauses would have turned into
+ * the caller's "unavailable" answer.
+ */
+function matchingRows(read, nodeType, objectName) {
+    const entries = requireKey(read(INDEX_FILENAME), "entries");
+    if (!Array.isArray(entries))
+        throw new TypeError("entries is not a list");
+    const rows = [];
+    for (const row of entries) {
+        if (requireKey(row, "nodeType") !== nodeType)
+            continue;
+        if (objectName !== undefined && objectName !== null && pyGet(row, "objectName", null) !== objectName)
+            continue;
+        rows.push(row);
+    }
+    return rows;
+}
+/**
+ * `_count_input_fields`: input-field count across the matching overlay
+ * variants, or `undefined` when nothing matched or a file could not be read
+ * — never `0` for "unavailable", which the summary line would print as a
+ * plausible success.
+ */
+export function countInputFieldsFrom(read, nodeType, objectName) {
+    try {
+        const rows = matchingRows(read, nodeType, objectName);
+        if (rows.length === 0)
+            return undefined;
+        let total = 0;
+        for (const row of rows) {
+            const descriptor = read(pyStrAny(requireKey(row, "path")));
+            if (!isPlainObject(descriptor))
+                return undefined;
+            const inputSchema = pyGet(descriptor, "inputSchema", null);
+            if (!isPlainObject(inputSchema))
+                return undefined;
+            const fields = pyGet(inputSchema, "fields", null);
+            if (!Array.isArray(fields))
+                return undefined;
+            total += fields.length;
+        }
+        return total;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** {@link countInputFieldsFrom} over an overlay directory. */
+export function countInputFields(out, nodeType, objectName) {
+    return countInputFieldsFrom(directoryReader(out), nodeType, objectName);
+}
+const PLACEHOLDER = /\{([^{}]+)\}/g;
+/**
+ * `_parent_fields`: `[parent field names, whether the prepared schema is parent-ONLY]`.
+ *
+ * A reference `path` carrying a `{placeholder}` is the declaration that an
+ * operation is parent-driven: `/project/{fields.project.key}/issuetypes` on
+ * `fields.issuetype.id` names the field whose value must be resolved first.
+ * The parent set is both halves of that relation — the placeholder names AND
+ * the fields that declare them — because both must be passed as `-f`.
+ * "Parent-only" then means every prepared field is a parent: the expected
+ * shape with no `-f`, and a silent failure WITH `-f`.
+ */
+export function parentFieldsFrom(read, nodeType, objectName) {
+    const names = [];
+    const placeholders = new Set();
+    const declaring = new Set();
+    try {
+        for (const row of matchingRows(read, nodeType, objectName)) {
+            const descriptor = read(pyStrAny(requireKey(row, "path")));
+            if (!isPlainObject(descriptor))
+                throw new TypeError("descriptor is not a dict");
+            const inputSchema = pyGet(descriptor, "inputSchema", {});
+            if (!isPlainObject(inputSchema))
+                throw new TypeError("inputSchema is not a dict");
+            const fields = pyOr(pyGet(inputSchema, "fields", []), []);
+            if (!Array.isArray(fields))
+                throw new TypeError("fields is not a list");
+            for (const field of fields) {
+                if (!isPlainObject(field))
+                    throw new TypeError("field is not a dict");
+                const name = pyGet(field, "name", null);
+                if (pyTruthy(name) && !names.includes(name))
+                    names.push(name);
+                const reference = pyOr(pyGet(field, "reference", null), {});
+                if (!isPlainObject(reference))
+                    throw new TypeError("reference is not a dict");
+                const path = pyOr(pyGet(reference, "path", null), "");
+                if (typeof path !== "string")
+                    throw new TypeError("path is not a str");
+                const found = [...path.matchAll(PLACEHOLDER)].map((m) => m[1]);
+                if (found.length > 0) {
+                    for (const p of found)
+                        placeholders.add(p);
+                    if (pyTruthy(name))
+                        declaring.add(name);
+                }
+            }
+        }
+    }
+    catch {
+        return [[], false];
+    }
+    const parents = new Set([...placeholders, ...declaring]);
+    if (parents.size === 0)
+        return [[], false];
+    const ordered = names.filter((name) => parents.has(name));
+    ordered.push(...sortedStrings([...parents].filter((p) => !ordered.includes(p))));
+    return [ordered, names.every((name) => parents.has(name))];
+}
+/** {@link parentFieldsFrom} over an overlay directory. */
+export function parentFields(out, nodeType, objectName) {
+    return parentFieldsFrom(directoryReader(out), nodeType, objectName);
+}
+/**
+ * `_schema_action_parents`: the parent inputs the PREPARED operation's own
+ * `operation.schemaAction.parents` names — the one declaration that is a
+ * PRECONDITION rather than a symptom: with any of these missing from `-f` the
+ * action cannot have run, whatever the describe returned. Declaration order,
+ * which is also the resolution order.
+ */
+export function schemaActionParentsFrom(read, nodeType, objectName) {
+    const names = [];
+    try {
+        for (const row of matchingRows(read, nodeType, objectName)) {
+            const descriptor = read(pyStrAny(requireKey(row, "path")));
+            if (!isPlainObject(descriptor))
+                throw new TypeError("descriptor is not a dict");
+            const operation = pyOr(pyGet(descriptor, "operation", null), {});
+            if (!isPlainObject(operation))
+                throw new TypeError("operation is not a dict");
+            const action = pyOr(pyGet(operation, "schemaAction", null), {});
+            if (!isPlainObject(action))
+                throw new TypeError("schemaAction is not a dict");
+            const parents = pyOr(pyGet(action, "parents", null), []);
+            if (!Array.isArray(parents))
+                throw new TypeError("parents is not a list");
+            for (const name of parents) {
+                if (pyTruthy(name) && !names.includes(name))
+                    names.push(name);
+            }
+        }
+    }
+    catch {
+        return [];
+    }
+    return names;
+}
+/** {@link schemaActionParentsFrom} over an overlay directory. */
+export function schemaActionParents(out, nodeType, objectName) {
+    return schemaActionParentsFrom(directoryReader(out), nodeType, objectName);
+}
+function hasParent(parentFieldValues, name) {
+    return parentFieldValues instanceof Map ? parentFieldValues.has(name) : Object.prototype.hasOwnProperty.call(parentFieldValues, name);
+}
+/**
+ * `_keep_prepared_schema`: `[kept, discarded]` when this run must NOT
+ * overwrite the overlay, else `undefined`.
+ *
+ * `--resolve` records a lookup; `-f` supplies the value a schema action reads.
+ * A run carrying only the former cannot have run the action, so what it has
+ * to write is the UNRESOLVED entry — and the merge replaces by variant key, so
+ * it lands on top of a schema an earlier `-f` run resolved (Jira
+ * `create-issue`: 21 fields down to 3, #666). Three conditions, all necessary:
+ * the EXISTING overlay declares `schemaAction.parents`; none of them arrived
+ * as `-f`; and the staged entry has STRICTLY fewer input fields than the one
+ * on disk — equal or richer still merges, so a fresher entry is never pinned
+ * by a stale overlay, and a first prepare (no overlay) writes normally.
+ *
+ * `staged` is the freshly built library: a directory, or `planLibrary`'s
+ * in-memory files.
+ */
+export function keepPreparedSchema(out, nodeType, staged, parentFieldValues, objectName) {
+    const parents = schemaActionParents(out, nodeType, objectName);
+    if (parents.length === 0 || parents.some((name) => hasParent(parentFieldValues, name)))
+        return undefined;
+    const existing = countInputFields(out, nodeType, objectName);
+    const incoming = countInputFieldsFrom(typeof staged === "string" ? directoryReader(staged) : filesReader(staged), nodeType, objectName);
+    if (existing === undefined || incoming === undefined || existing <= incoming)
+        return undefined;
+    return [existing, incoming];
+}
+function withFilterPatterns(specs, catalogFields) {
+    const references = catalogReferences({ inputSchema: { fields: [...catalogFields] } });
+    const out = new Map();
+    for (const [field, spec] of specs) {
+        const copy = { ...spec };
+        const filterPattern = references.get(field)?.filterPattern;
+        if (pyTruthy(filterPattern))
+            copy.filterPattern = pyStrAny(filterPattern);
+        out.set(field, copy);
+    }
+    return out;
+}
+/**
+ * `_lookup_specs_from_overlay`: the prepared operation's lookup specs, read
+ * back from the overlay just written. Generic object variants share a
+ * nodeType, so `objectName` narrows to the one just prepared (a variant with
+ * no object name still answers, as the Python's `not in ("", None, name)` did);
+ * the FIRST matching entry answers.
+ *
+ * An EVENT's resolvable fields are its subscription parameters, and
+ * `v1def.eventParameters.fields` is the ONE authority for those — the same
+ * list the SDK, `check` and the descriptor generator read.
+ *
+ * INTENTIONAL DIVERGENCE from the Python. It selected `eventParameters` as the
+ * `fields_source` but then handed that source to `lookup_specs`, which reads
+ * `v1def.inputDefinition.fields` FIRST and falls back to the source only when
+ * the sidecar's input list is empty AND the source has a required field. On a
+ * prepared event whose trigger definition carries message-body inputs, the
+ * specs therefore came from the BODY fields — the exact wrong list — and an
+ * optional event parameter produced no spec at all. Here an event's specs are
+ * built from `eventParameters.fields` directly, which is what the descriptor
+ * generator emits `lookups` from (`descriptorInputFields`), so `--resolve`,
+ * the vocabulary print and the generated `.by*` helpers agree.
+ */
+export function lookupSpecsFromOverlay(out, nodeType, objectName) {
+    const indexPath = join(out, INDEX_FILENAME);
+    if (!existsSync(indexPath))
+        return new Map();
+    const index = JSON.parse(readFileSync(indexPath, "utf8"));
+    const entries = isPlainObject(index) ? pyGet(index, "entries", []) : [];
+    if (!Array.isArray(entries))
+        return new Map();
+    const invariant = loadInvariantCollections(out);
+    for (const row of entries) {
+        if (!isPlainObject(row) || row.nodeType !== nodeType)
+            continue;
+        if (pyTruthy(objectName)) {
+            const rowObject = pyGet(row, "objectName", null);
+            if (rowObject !== "" && rowObject !== null && rowObject !== objectName)
+                continue;
+        }
+        const rel = pyStrAny(requireKey(row, "path"));
+        const entryPath = join(out, ...rel.split("/"));
+        if (!existsSync(entryPath))
+            continue;
+        const canonical = JSON.parse(readFileSync(entryPath, "utf8"));
+        const v1Path = join(out, ...sidecarPath(rel).split("/"));
+        const v1def = (existsSync(v1Path) ? unwrapV1Def(JSON.parse(readFileSync(v1Path, "utf8"))) : undefined) ?? {};
+        if (isEventNodeType(nodeType)) {
+            const parameters = v1def.eventParameters?.fields ?? [];
+            const fields = Array.isArray(parameters) ? parameters : [];
+            return withFilterPatterns(specsFromFields(fields, invariant, catalogReferences({ inputSchema: { fields } })), fields);
+        }
+        return withFilterPatterns(lookupSpecs(canonical, v1def, invariant), canonical.inputSchema?.fields ?? []);
+    }
+    return new Map();
+}

package/dist/registry/prepare/parents.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `['a=1', 'b=2']` → `{a: '1', b: '2'}`, refusing a missing `=`.
+ *
+ * Values may themselves contain `=` (a Salesforce SOQL body token), so the
+ * split is on the FIRST separator only. Insertion order is the `-f` order on
+ * the command line, which is also the order the describe is issued with.
+ */
+export declare function parseFields(pairs: readonly string[]): Map<string, string>;
+/** One api-type ObjectAction: its name and the parent-field names its rules read, in rule order. */
+export type ObjectActionSpec = readonly [actionName: string, parentFields: string[]];
+/**
+ * `_object_action_specs`: each api-type ObjectAction the registry node
+ * declares and its ordered parent-field names. `payload` is the raw
+ * `{"Data": {"Node": …}}` document; anything not shaped that way answers `[]`,
+ * as the Python's `except (KeyError, TypeError)` did.
+ */
+export declare function objectActionSpecs(payload: unknown): ObjectActionSpec[];
+/** The design-time schema replay request `customFieldsRequestDetails` carries. */
+export interface ObjectActionRequest {
+    objectActionName: string;
+    parameterValues: Array<[name: string, value: string]>;
+}
+type ParentFields = ReadonlyMap<string, string> | Readonly<Record<string, string>>;
+/**
+ * `_object_action_request`: the replay request for the ObjectAction whose
+ * parent set is EXACTLY the `-f` names given, or `undefined` when none
+ * matches (a partial set is not a match). Parameter names are spelled the way
+ * the platform stores nested paths: `fields.project.key` → `fields_sub_project_sub_key`.
+ */
+export declare function objectActionRequest(payload: unknown, parentFields: ParentFields): ObjectActionRequest | undefined;
+/**
+ * `_declared_parents`: parent-input names the registry declares through
+ * api-type ObjectActions, flattened in declaration order and deduplicated.
+ *
+ * The second way an operation says "my fields depend on a value": not a
+ * `{placeholder}` in a reference path (Jira), but a design-time action whose
+ * rules name the inputs it reads (Data Fabric `create-entity-record` declares
+ * `GenerateSchema` over `entityName`).
+ */
+export declare function declaredParents(payload: unknown): string[];
+export {};

package/dist/registry/prepare/parents.js

@@ -0,0 +1,122 @@
+/**
+ * Parent fields: the `-f NAME=VALUE` inputs a schema-dynamic operation resolves
+ * its real field set from, and the registry's own declaration of them.
+ *
+ * Schema-dynamic ops resolve their fields from the VALUES of a few parent
+ * fields, not from the connection alone (Jira `create-issue`: 2 fields with no
+ * `-f`, 19 with project + issue type). Studio Web persists the ObjectAction and
+ * the parent values that produced a field list so it can replay the same
+ * schema; the registry owns the action name and rule order, `-f` owns the
+ * values. This module reads both halves.
+ *
+ * Ported from `_parse_fields`, `_object_action_specs`, `_object_action_request`
+ * and `_declared_parents` in `prepare_connector.py`. Every function here is
+ * pure over the PARSED `flow registry get` payload — the Python re-read the
+ * cached file each time; the port takes the object the cache already holds.
+ */
+import { pyStrip } from "../compat/pystr.js";
+import { PrepareRefusal, fieldFlagMessage } from "./messages.js";
+import { isPlainObject, pyOr, pyTruthy } from "./support.js";
+/**
+ * `['a=1', 'b=2']` → `{a: '1', b: '2'}`, refusing a missing `=`.
+ *
+ * Values may themselves contain `=` (a Salesforce SOQL body token), so the
+ * split is on the FIRST separator only. Insertion order is the `-f` order on
+ * the command line, which is also the order the describe is issued with.
+ */
+export function parseFields(pairs) {
+    const parsed = new Map();
+    for (const pair of pairs) {
+        const at = pair.indexOf("=");
+        const name = at < 0 ? pair : pair.slice(0, at);
+        if (at < 0 || !pyStrip(name)) {
+            throw new PrepareRefusal(fieldFlagMessage(pair), "FIELD_FLAG_MALFORMED");
+        }
+        parsed.set(pyStrip(name), pair.slice(at + 1));
+    }
+    return parsed;
+}
+/**
+ * `_object_action_specs`: each api-type ObjectAction the registry node
+ * declares and its ordered parent-field names. `payload` is the raw
+ * `{"Data": {"Node": …}}` document; anything not shaped that way answers `[]`,
+ * as the Python's `except (KeyError, TypeError)` did.
+ */
+export function objectActionSpecs(payload) {
+    if (!isPlainObject(payload) || !isPlainObject(payload.Data) || !isPlainObject(payload.Data.Node))
+        return [];
+    const node = payload.Data.Node;
+    const methodInfo = pyOr(node.connectorMethodInfo, {});
+    const design = isPlainObject(methodInfo) ? pyOr(methodInfo.design, {}) : {};
+    const actions = isPlainObject(design) ? pyOr(design.actions, []) : [];
+    if (!Array.isArray(actions))
+        return [];
+    const specs = [];
+    for (const action of actions) {
+        if (!isPlainObject(action) || action.actionType !== "api")
+            continue;
+        const actionName = action.name;
+        if (typeof actionName !== "string" || !actionName)
+            continue;
+        const rules = pyOr(action.rules, []);
+        if (!Array.isArray(rules))
+            return []; // Python: iterating a non-list raises TypeError → []
+        const refs = [];
+        for (const rule of rules) {
+            if (!isPlainObject(rule))
+                return [];
+            if (pyTruthy(rule.isCleared) || !pyTruthy(rule.refFieldName))
+                continue;
+            refs.push(String(rule.refFieldName));
+        }
+        if (refs.length > 0)
+            specs.push([actionName, refs]);
+    }
+    return specs;
+}
+function parentEntries(parentFields) {
+    return parentFields instanceof Map ? [...parentFields.entries()] : Object.entries(parentFields);
+}
+/**
+ * `_object_action_request`: the replay request for the ObjectAction whose
+ * parent set is EXACTLY the `-f` names given, or `undefined` when none
+ * matches (a partial set is not a match). Parameter names are spelled the way
+ * the platform stores nested paths: `fields.project.key` → `fields_sub_project_sub_key`.
+ */
+export function objectActionRequest(payload, parentFields) {
+    const entries = parentEntries(parentFields);
+    if (entries.length === 0)
+        return undefined;
+    const given = new Set(entries.map(([name]) => name));
+    const values = new Map(entries);
+    for (const [actionName, refs] of objectActionSpecs(payload)) {
+        if (refs.length === 0)
+            continue;
+        const declared = new Set(refs);
+        if (declared.size !== given.size || [...declared].some((ref) => !given.has(ref)))
+            continue;
+        return {
+            objectActionName: actionName,
+            parameterValues: refs.map((name) => [name.replaceAll(".", "_sub_"), values.get(name)]),
+        };
+    }
+    return undefined;
+}
+/**
+ * `_declared_parents`: parent-input names the registry declares through
+ * api-type ObjectActions, flattened in declaration order and deduplicated.
+ *
+ * The second way an operation says "my fields depend on a value": not a
+ * `{placeholder}` in a reference path (Jira), but a design-time action whose
+ * rules name the inputs it reads (Data Fabric `create-entity-record` declares
+ * `GenerateSchema` over `entityName`).
+ */
+export function declaredParents(payload) {
+    const names = [];
+    for (const [, refs] of objectActionSpecs(payload)) {
+        for (const ref of refs)
+            if (!names.includes(ref))
+                names.push(ref);
+    }
+    return names;
+}