@uipath/maestro-builder-sdk 6.4.0 → 6.5.1

package/dist/registry/prepare/objects.js

@@ -0,0 +1,318 @@
+/**
+ * Match the object a Generic connector action addresses, deterministically.
+ *
+ * `prepare --object Company__C` used to mean EXACTLY `Company__C`: the catalog
+ * is matched by equality, the user's casing is not the API's, and the failure
+ * was a dead end — "object was not found" with no candidates, against a catalog
+ * the command had just fetched.
+ *
+ * THE LADDER, strictest first, stopping at the first rung with EXACTLY one hit:
+ *
+ *   1. exact `Name`;
+ *   2. case-insensitive `Name`;
+ *   3. case-insensitive `DisplayName`.
+ *
+ * A unique case-insensitive match proceeds LOUDLY (the caller prints the
+ * normalization) — casing is presentation, so those rungs cannot pick a thing
+ * the author did not name. SUBSTRING MATCHING NEVER PROCEEDS, unique or not:
+ * "unique among what exists" is not "unique among what the author meant", and
+ * the two diverge exactly when it hurts — `--object Company` on a tenant whose
+ * only Create-capable hit is `DandBCompany` would silently prepare an object
+ * the author never named, and the same source line would prepare DIFFERENT
+ * objects on different tenants. So substring hits are how the REFUSAL finds its
+ * candidates, nothing more.
+ *
+ * Several matches refuse with the candidate table — a wrong field value is one
+ * wrong input, a wrong object is a wrong flow, so nothing here ever picks
+ * first. Zero matches on a multi-word input refuse with the candidates of the
+ * most selective word, because qualifier words are facets, not name material.
+ * Candidates are narrowed to objects whose `Operations` include this action's
+ * verb before any matching.
+ *
+ * Ported from `integrations/scripts/_objects.py`; the refusal text is verbatim.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pyJsonStringify } from "../codecs/pyjson.js";
+import { pyStrip } from "../compat/pystr.js";
+import { Refusal, messageOf } from "../errors.js";
+import { isPlainObject, pyOr, pyRepr, pySplitWhitespace, pyStrAny, pyTruthy, pyTypeName } from "./support.js";
+/**
+ * Enough rows to choose from without dumping a catalog into the error. The
+ * most-selective-token fallback can legitimately produce dozens of rows; past
+ * this many the table stops being a choice and starts being the unfiltered
+ * list the ladder exists to avoid.
+ */
+export const MAX_CANDIDATES = 15;
+/**
+ * No unique object for the requested name, with the candidates a human (or an
+ * agent with the prompt in hand) needs to choose (`_objects.ObjectMatchError`).
+ *
+ * `retriable` marks every outcome that fell PAST the name rungs — zero
+ * matches, and the substring refusals (unique or ambiguous). All of them can be
+ * caused by a stale `uip is resources list` cache hiding a real object:
+ * `--object User` on a catalog that lacks `User` but carries `UserAlias` would
+ * otherwise refuse with a recovery message pointing at the WRONG object, and
+ * the cache never invalidates itself. The caller refreshes the catalog once and
+ * re-runs the whole ladder before believing any of them. Ambiguity WITHIN a
+ * name rung (two objects whose names are case-variants) is not retriable — a
+ * fresh catalog has the same two names in it.
+ */
+export class ObjectMatchRefusal extends Refusal {
+    retriable;
+    constructor(message, code, retriable = false) {
+        super(message, code);
+        this.retriable = retriable;
+        this.name = "ObjectMatchRefusal";
+    }
+}
+/** The ledger file exists but cannot be read back — refuse, don't clobber (`_objects.LedgerError`). */
+export class LedgerRefusal extends Refusal {
+    constructor(message, code) {
+        super(message, code);
+        this.name = "LedgerRefusal";
+    }
+}
+/** `str(row.get("Name") or "")`. */
+export function objectName(row) {
+    return pyStrAny(pyOr(row.Name, ""));
+}
+/** `str(row.get("DisplayName") or "")`. */
+export function objectDisplayName(row) {
+    return pyStrAny(pyOr(row.DisplayName, ""));
+}
+/**
+ * True when the row's `Operations` include `operation`. A catalog that does
+ * not report operations cannot be narrowed by one; keep the row rather than
+ * hiding it on missing data.
+ */
+export function supportsOperation(row, operation) {
+    if (!operation)
+        return true;
+    const operations = row.Operations;
+    if (!Array.isArray(operations))
+        return true;
+    return operations.includes(operation);
+}
+/** `len(s)` in code points, as Python counts. */
+function width(s) {
+    return [...s].length;
+}
+/** `s.ljust(w)`, padding by code-point width. */
+function ljust(s, w) {
+    return s + " ".repeat(Math.max(0, w - width(s)));
+}
+/**
+ * The table an ambiguous match prints: enough columns to choose with.
+ *
+ * `Custom: yes` is how a prompt's "custom" qualifier resolves — it is a facet
+ * column here precisely so nothing upstream has to parse it out of English.
+ */
+export function formatCandidates(rows) {
+    const shown = rows.slice(0, MAX_CANDIDATES);
+    const nameW = Math.max(width("Name"), ...shown.map((r) => width(objectName(r))));
+    const dispW = Math.max(width("DisplayName"), ...shown.map((r) => width(objectDisplayName(r))));
+    const lines = [`  ${ljust("Name", nameW)}  ${ljust("DisplayName", dispW)}  Custom  Operations`];
+    for (const row of shown) {
+        const operations = row.Operations;
+        const ops = Array.isArray(operations) ? operations.map(pyStrAny).join(",") : "?";
+        lines.push(`  ${ljust(objectName(row), nameW)}  ${ljust(objectDisplayName(row), dispW)}  ` +
+            `${ljust(pyStrAny(pyOr(row.Custom, "?")), 6)}  ${ops}`);
+    }
+    if (rows.length > MAX_CANDIDATES) {
+        lines.push(`  … and ${rows.length - MAX_CANDIDATES} more`);
+    }
+    return lines.join("\n");
+}
+function containing(rows, needle) {
+    const lowered = needle.toLowerCase();
+    return rows.filter((row) => objectName(row).toLowerCase().includes(lowered) || objectDisplayName(row).toLowerCase().includes(lowered));
+}
+function ambiguous(wanted, hits, operation) {
+    return (`"${wanted}" matches ${hits.length} objects` +
+        (operation ? ` that support ${operation}` : "") +
+        ". Nothing here picks one for you: a wrong object is a wrong flow." +
+        " Pick by the task's wording (Custom: yes marks a tenant-only object)," +
+        " or present these and let the user choose, then re-run with" +
+        " --object <Name>:\n" +
+        formatCandidates(hits));
+}
+/**
+ * The catalog row for `wanted`, or throw {@link ObjectMatchRefusal}.
+ *
+ * `operation` is the action's verb (`Create`, `Update`, …); rows that do not
+ * support it are dropped before any matching.
+ */
+export function matchObject(rows, wanted, operation) {
+    wanted = pyStrip(wanted ?? "");
+    if (!wanted) {
+        throw new ObjectMatchRefusal("--object needs a name to match.", "OBJECT_NAME_REQUIRED");
+    }
+    const pool = rows.filter((row) => supportsOperation(row, operation));
+    const exact = pool.filter((row) => objectName(row) === wanted);
+    if (exact.length === 1)
+        return { row: exact[0], note: undefined };
+    const lowered = wanted.toLowerCase();
+    const rungs = [
+        ["name", objectName],
+        ["display name", objectDisplayName],
+    ];
+    for (const [rung, key] of rungs) {
+        const hits = pool.filter((row) => key(row).toLowerCase() === lowered);
+        if (hits.length === 1) {
+            return { row: hits[0], note: `matched "${wanted}" -> ${objectName(hits[0])} (by ${rung})` };
+        }
+        if (hits.length > 1) {
+            throw new ObjectMatchRefusal(ambiguous(wanted, hits, operation), "OBJECT_AMBIGUOUS");
+        }
+    }
+    // Substring hits only ever feed the refusal. A unique one is still a guess
+    // — the pool it is unique within is tenant state, not the author's intent —
+    // so it is offered back as the one candidate to confirm, never taken.
+    // Everything from here down is `retriable`: a stale catalog can hide the
+    // real object the author named, and these refusals would then recover
+    // toward the wrong one.
+    let hits = containing(pool, wanted);
+    if (hits.length === 1) {
+        throw new ObjectMatchRefusal(`no object is NAMED "${wanted}"` +
+            (operation ? ` (of those that support ${operation})` : "") +
+            `. One object contains it — if ${pyRepr(objectName(hits[0]))} is the one ` +
+            "the task means, re-run with --object " +
+            `${objectName(hits[0])}:\n` +
+            formatCandidates(hits), "OBJECT_SUBSTRING_ONLY", true);
+    }
+    if (hits.length > 1) {
+        throw new ObjectMatchRefusal(ambiguous(wanted, hits, operation), "OBJECT_SUBSTRING_AMBIGUOUS", true);
+    }
+    // Nothing contains the whole input. A multi-word input usually mixes name
+    // material with qualifiers; the most selective word's candidates are the
+    // smallest non-empty table the author can actually choose from.
+    const tokens = pySplitWhitespace(wanted);
+    if (tokens.length > 1) {
+        const nonempty = tokens.map((t) => [t, containing(pool, t)]).filter(([, h]) => h.length > 0);
+        if (nonempty.length > 0) {
+            // `min(..., key=len)`: the FIRST of the smallest, on ties.
+            let [token, best] = nonempty[0];
+            for (const pair of nonempty)
+                if (pair[1].length < best.length)
+                    [token, best] = pair;
+            hits = best;
+            throw new ObjectMatchRefusal(`no object matches "${wanted}" as one name` +
+                (operation ? ` (of those that support ${operation})` : "") +
+                `. Its word "${token}" matches ${hits.length}` +
+                ' — qualifiers like "custom" are the Custom column below,' +
+                " not part of the name. Pick one and re-run with" +
+                " --object <Name>:\n" +
+                formatCandidates(hits), "OBJECT_WORD_CANDIDATES", true);
+        }
+    }
+    throw new ObjectMatchRefusal(`no object in the connected catalog matches "${wanted}"` +
+        (operation ? ` and supports ${operation}` : "") +
+        ` (${pool.length} object(s) searched by name, display name and` +
+        " substring). Check the value against the words the task used," +
+        " or list the catalog to see what is there.", "OBJECT_NOT_FOUND", true);
+}
+// ---------------------------------------------------------------------------
+// The ledger: `connectors-local/resolutions.json`.
+export const RESOLUTIONS_FILENAME = "resolutions.json";
+/** `<outDir>/resolutions.json`. */
+export function ledgerPath(outDir) {
+    return join(outDir, RESOLUTIONS_FILENAME);
+}
+/**
+ * The whole ledger at `path` as parsed, `{}` when there is no file, or throw
+ * {@link LedgerRefusal}.
+ *
+ * A file that will not parse is REFUSED rather than silently reset to `{}` —
+ * the same rule `bindings.json` follows: a corrupt-but-recoverable audit of
+ * every resolution prepare ever made is worth more than this run finishing,
+ * and overwriting it is the one way to make the corruption permanent.
+ * Parseable-but-not-an-object (a top-level array, a bare string) is corruption
+ * wearing valid JSON; sliding it past the refusal would overwrite whatever it
+ * used to be.
+ */
+export function readLedger(path) {
+    if (!existsSync(path))
+        return {};
+    let ledger;
+    try {
+        ledger = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new LedgerRefusal(`${path} exists but cannot be read back (${messageOf(error)}); refusing to ` +
+            "overwrite it. Fix or remove the file and re-run.", "LEDGER_CORRUPT");
+    }
+    if (!isPlainObject(ledger)) {
+        throw new LedgerRefusal(`${path} exists but is not a JSON object ` +
+            `(found ${pyTypeName(ledger)}); refusing to overwrite it. ` +
+            "Fix or remove the file and re-run.", "LEDGER_NOT_OBJECT");
+    }
+    return ledger;
+}
+/**
+ * `json.dump(ledger, indent=2, sort_keys=True)` + newline: the bytes the
+ * ledger is written in. Keys sort by code point at every level, so the order a
+ * key was inserted in never reaches the file — which is also why integer-like
+ * keys (which `JSON.parse` hoists) are accepted here: sorting puts them where
+ * Python would have.
+ */
+export function formatLedger(ledger) {
+    return `${pyJsonStringify(ledger, { indent: 2, sortKeys: true, allowIntegerKeys: true })}\n`;
+}
+/** Write the ledger at `path`, creating its directory. */
+export function writeLedger(path, ledger) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, formatLedger(ledger), "utf8");
+}
+/** The `objects[nodeType][requested]` row for a decision. */
+export function ledgerObjectOf(decision) {
+    const custom = pyStrip(pyStrAny(pyOr(decision.row.Custom, ""))).toLowerCase();
+    return {
+        value: objectName(decision.row),
+        displayName: objectDisplayName(decision.row),
+        custom: custom === "yes" || custom === "true" || custom === "1",
+        ...(decision.operation ? { operation: decision.operation } : {}),
+    };
+}
+/**
+ * The ledger with the match recorded under `objects[nodeType][requested]`.
+ *
+ * Pure: returns a new ledger and leaves `ledger` untouched. The row lands in a
+ * sibling `objects` section rather than in `resolutions`: an object identity is
+ * not a field lookup, and it should not wear a fake `field` key. Keys NEST
+ * rather than encode a tuple: the lookup rows' tuple-string keys exist to match
+ * a JavaScript `JSON.stringify` that reads them back, and nothing in JavaScript
+ * reads this section.
+ *
+ * Unlike lookup rows, the current match is ALWAYS written, `--refresh` or not.
+ * A lookup row stands because re-resolving costs a network call and can
+ * silently change an artifact; this row costs nothing to recompute and MUST
+ * agree with the overlay written beside it in this same run. The ledger
+ * records the DECISION only; the schema it selected lives in the overlay.
+ */
+export function recordObject(ledger, nodeType, requested, decision) {
+    const objectsIn = pyOr(ledger.objects, {});
+    const objects = isPlainObject(objectsIn) ? { ...objectsIn } : {};
+    const perTypeIn = pyOr(objects[nodeType], {});
+    const perType = isPlainObject(perTypeIn) ? { ...perTypeIn } : {};
+    perType[requested] = ledgerObjectOf(decision);
+    objects[nodeType] = perType;
+    const resolutions = pyOr(ledger.resolutions, {});
+    return {
+        ...ledger,
+        objects: objects,
+        resolutions: (pyTruthy(resolutions) ? resolutions : {}),
+        schemaVersion: "1",
+    };
+}
+/**
+ * Record the match in `<outDir>/resolutions.json` and return that path — the
+ * Python `record_object_resolution`: read (refusing a corrupt file before
+ * anything is created), record, write.
+ */
+export function recordObjectResolution(outDir, nodeType, requested, row, operation) {
+    const path = ledgerPath(outDir);
+    const ledger = recordObject(readLedger(path), nodeType, requested, { row, operation });
+    writeLedger(path, ledger);
+    return path;
+}

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

@@ -0,0 +1,149 @@
+import { type LookupStrategy } from "../lookup-specs.js";
+export declare const INDEX_FILENAME = "index.json";
+export declare 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 declare function variantKey(entry: Record<string, unknown>): string;
+/** `_descriptor_overlay_path`: `<key>/op@1.json` → `descriptors/<key>/op@1.json`; already-rooted paths pass through. */
+export declare function descriptorOverlayPath(path: string): string;
+/**
+ * `_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 declare function migrateLegacyDescriptorRoots(dst: string, entries: readonly unknown[]): void;
+/**
+ * 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 declare function mergeIndexEntries(dstEntries: readonly unknown[], srcEntries: readonly unknown[]): Record<string, unknown>[];
+/**
+ * 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 declare function formatOverlayIndex(index: unknown): string;
+/** Text or bytes for one file of a freshly written single-op library, keyed by POSIX-relative path. */
+export type LibraryFiles = ReadonlyMap<string, string | Uint8Array>;
+/**
+ * `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 declare function mergeFilesInto(files: LibraryFiles, dst: string): void;
+/** `merge_into(src, dst)`: merge a freshly written single-op library directory into the overlay. */
+export declare function mergeInto(src: string, dst: string): void;
+/** `_overlay_has_generic_expanded`: does the overlay hold ANY `GenericExpanded` entry, from any prepare? */
+export declare function overlayHasGenericExpanded(out: string): boolean;
+/**
+ * How the read-back functions reach a JSON file by its index-relative path.
+ * Throws when the file is missing or not JSON — every caller treats a throw as
+ * "unavailable", the way the Python's `except (OSError, ValueError, …)` did.
+ */
+export type JsonReader = (relativePath: string) => unknown;
+/** A reader over a directory on disk. */
+export declare function directoryReader(dir: string): JsonReader;
+/** A reader over an in-memory library (`planLibrary`'s `files`), for the staged half of {@link keepPreparedSchema}. */
+export declare function filesReader(files: LibraryFiles): JsonReader;
+/**
+ * `_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 declare function countInputFieldsFrom(read: JsonReader, nodeType: string, objectName?: string | null): number | undefined;
+/** {@link countInputFieldsFrom} over an overlay directory. */
+export declare function countInputFields(out: string, nodeType: string, objectName?: string | null): number | undefined;
+/**
+ * `_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 declare function parentFieldsFrom(read: JsonReader, nodeType: string, objectName?: string | null): [parents: string[], parentOnly: boolean];
+/** {@link parentFieldsFrom} over an overlay directory. */
+export declare function parentFields(out: string, nodeType: string, objectName?: string | null): [parents: string[], parentOnly: boolean];
+/**
+ * `_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 declare function schemaActionParentsFrom(read: JsonReader, nodeType: string, objectName?: string | null): string[];
+/** {@link schemaActionParentsFrom} over an overlay directory. */
+export declare function schemaActionParents(out: string, nodeType: string, objectName?: string | null): string[];
+type ParentValues = ReadonlyMap<string, string> | Readonly<Record<string, string>>;
+/**
+ * `_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 declare function keepPreparedSchema(out: string, nodeType: string, staged: string | LibraryFiles, parentFieldValues: ParentValues, objectName?: string | null): [kept: number, discarded: number] | undefined;
+/**
+ * One lookup spec as `prepare` needs it: what the generated descriptor carries
+ * plus `filterPattern`, which is a retrieval detail (not an authoring one) that
+ * only the resolver reads. A type literal rather than an interface so it is
+ * assignable to the resolver's loosely typed `ResolveSpec`.
+ */
+export type OverlayLookupSpec = {
+    path: string;
+    by: string[];
+    value: string;
+    aliases: Map<string, string>;
+    strategy: LookupStrategy;
+    objectName?: string;
+    dependsOn?: string[];
+    filterPattern?: string;
+};
+/**
+ * `_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 declare function lookupSpecsFromOverlay(out: string, nodeType: string, objectName?: string | null): Map<string, OverlayLookupSpec>;
+export {};