@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

package/dist/registry/prepare/ledger.js

@@ -0,0 +1,216 @@
+/**
+ * `connectors-local/resolutions.json`, the lookup half: recording what
+ * `--resolve` answered and reading it back for the paste-ready re-run.
+ *
+ * A SEPARATE FILE from the schema overlay, deliberately. A prepared schema is a
+ * fact about the connector; a resolution is a fact about one tenant's data, so
+ * it ages differently and most consumers will want to gitignore it. Existing
+ * entries STAND rather than being re-resolved: a resolved id is a snapshot
+ * either way, and re-resolving on every call would make an unrelated `prepare`
+ * silently change an artifact. Re-resolving is `--refresh-lookups`, a
+ * deliberate act with a visible diff.
+ *
+ * The object half of the ledger (`objects[nodeType][requested]`) lives in
+ * `objects.ts`; this module reads and rewrites the WHOLE file so neither
+ * section drops the other.
+ *
+ * Ported from `_write_resolutions` and `_resolved_parent_values` in
+ * `prepare_connector.py`.
+ */
+import { lookupKey } from "../../core/lookups.js";
+import { pyJsonStringify } from "../codecs/pyjson.js";
+import { sortedStrings } from "../compat/compare.js";
+import { PrepareRefusal, resolutionLine, unknownLookupMessage, wroteResolutionsLine } from "./messages.js";
+import { LedgerRefusal, RESOLUTIONS_FILENAME, ledgerPath, readLedger, writeLedger } from "./objects.js";
+import { lookupSpecsFromOverlay } from "./overlay.js";
+import { LookupExhausted, orderResolutions, parseResolveFlag, resolveOne } from "./resolve.js";
+import { isPlainObject, pyGet, pyPathJoin, pyStrAny } from "./support.js";
+/**
+ * The key a resolution is recorded under: `JSON.stringify([nodeType, field,
+ * by, value])`, the same bytes `core/lookups.ts`'s `lookupKey` computes when
+ * `compile` looks one up.
+ *
+ * INTENTIONAL DIVERGENCE from the Python, which built the key with
+ * `json.dumps(..., separators=(",", ":"))` — compact like JavaScript, but with
+ * `ensure_ascii` left on, so a value with any character outside ASCII was
+ * written as `\uXXXX` INSIDE the key string. `JSON.stringify` writes the
+ * character itself. The two spellings of the same tuple are different strings,
+ * so every such resolution `prepare` recorded was invisible to the `compile`
+ * that had asked for it. Written raw here to match the reader;
+ * {@link findResolution} still reads the escaped spelling so a ledger the
+ * Python wrote keeps loading.
+ */
+export function resolutionKey(nodeType, field, by, value) {
+    return lookupKey(nodeType, field, by, value);
+}
+/** The Python's spelling of the same key: compact separators, `ensure_ascii=True`. */
+export function escapedResolutionKey(nodeType, field, by, value) {
+    return pyJsonStringify([nodeType, field, by, value], { separators: [",", ":"] });
+}
+/** `[nodeType, field, by, match]` out of a recorded key, in either spelling, or `undefined`. */
+export function parseResolutionKey(key) {
+    let parsed;
+    try {
+        parsed = JSON.parse(key);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(parsed) || parsed.length !== 4)
+        return undefined;
+    return parsed.map(pyStrAny);
+}
+/**
+ * The recorded row for `(nodeType, field, by, value)`, whichever spelling it
+ * was written under — raw first, then the Python's escaped form. For a pure
+ * ASCII tuple the two are the same string.
+ */
+export function findResolution(existing, nodeType, field, by, value) {
+    for (const key of new Set([resolutionKey(nodeType, field, by, value), escapedResolutionKey(nodeType, field, by, value)])) {
+        if (Object.prototype.hasOwnProperty.call(existing, key)) {
+            const row = existing[key];
+            if (isPlainObject(row))
+                return { key, row };
+        }
+    }
+    return undefined;
+}
+/**
+ * A {@link LookupExhausted} as {@link writeResolutions} surfaces it: the
+ * exhausted lookup plus the plan it belonged to. Same message, same facts,
+ * still a `LookupExhausted` — the pipeline catches this one class and has
+ * everything the retry needs, whichever path (action or event) was running.
+ *
+ * Raised ONLY for a scan that reached the collection's end. A capped scan is
+ * a `LookupExhausted` too and is deliberately NOT wrapped; see the throw site.
+ */
+export class ResolutionsExhausted extends LookupExhausted {
+    first;
+    plan;
+    constructor(first, plan) {
+        super(first.message, first);
+        this.first = first;
+        this.plan = plan;
+        this.name = "ResolutionsExhausted";
+    }
+}
+/**
+ * `_write_resolutions`: resolve every `--resolve` and merge the answers into
+ * the ledger. Reads and rewrites the WHOLE ledger, not just `resolutions` —
+ * the file also carries the `objects` section, and rewriting one section used
+ * to silently drop the other. A file that will not parse is REFUSED rather
+ * than reset (`readLedger`), the same rule `bindings.json` follows.
+ *
+ * `specs` defaults to the overlay's, read back from what was just written;
+ * a caller that already holds them passes them in.
+ */
+export async function writeResolutions(run, specs) {
+    const table = specs ?? lookupSpecsFromOverlay(run.out, run.nodeType, run.objectName);
+    const requested = run.resolve.map(parseResolveFlag);
+    const unknown = requested.map(([field]) => field).filter((field) => !table.has(field));
+    if (unknown.length > 0) {
+        throw new PrepareRefusal(unknownLookupMessage(unknown, run.nodeType, sortedStrings(table.keys())), "RESOLVE_UNKNOWN_FIELD");
+    }
+    const ordered = orderResolutions(requested, table);
+    const path = ledgerPath(run.out);
+    const ledger = readLedger(path);
+    const recorded = pyGet(ledger, "resolutions", null);
+    const existing = isPlainObject(recorded) ? { ...recorded } : {};
+    const resolved = new Map();
+    for (const [field, by, value] of ordered) {
+        const key = resolutionKey(run.nodeType, field, by, value);
+        const found = findResolution(existing, run.nodeType, field, by, value);
+        if (found && !run.refreshLookups) {
+            const kept = pyStrAny(pyGet(found.row, "value", null));
+            resolved.set(field, kept);
+            run.reporter.info(resolutionLine(field, by, value, kept, true));
+            continue;
+        }
+        let got;
+        try {
+            got = await resolveOne(run.client, run.connectorKey, table.get(field), field, by, value, run.connectionId, resolved);
+        }
+        catch (error) {
+            // The collection was read to the END on this connection and the value
+            // is not in it. That is evidence about the CONNECTION, not only about
+            // the value — so before failing, the pipeline tries the other enabled
+            // connections for this connector, and needs the plan this lookup was
+            // part of to probe them. A transport failure is the parent class and
+            // passes through untouched: retrying it would dress a broken call up as
+            // "no connection has it".
+            //
+            // `capped` is the fourth row of #746's table and the reason the flag
+            // exists: a scan the record cap stopped did NOT reach the end, so it is
+            // not evidence of absence and "must not demote anything"
+            // (`LookupExhausted`'s own docstring, ported verbatim). DELIBERATE
+            // DIVERGENCE FROM THE PYTHON'S CODE, in favour of the Python's stated
+            // contract: `prepare_connector.py` never reads `capped` anywhere, so
+            // upstream `_write_resolutions` hands a capped miss to `_retry_or_exit`
+            // like any other and spends a full probe of every other connection on a
+            // scan that proved nothing — then reports "every candidate was read to
+            // the end", which is exactly false. Here a capped miss keeps its own
+            // refusal, whose text already names the remedy ("the value may be
+            // further in"). Upstream's own tests never covered the row, which is
+            // how it shipped unimplemented.
+            if (error instanceof LookupExhausted && !error.capped)
+                throw new ResolutionsExhausted(error, { specs: table, ordered });
+            throw error;
+        }
+        resolved.set(field, got);
+        // A refresh of a row the Python recorded under the escaped key replaces
+        // it under the raw one, so the tuple does not end up recorded twice.
+        if (found && found.key !== key)
+            delete existing[found.key];
+        existing[key] = { nodeType: run.nodeType, field, by, match: value, value: got };
+        run.reporter.info(resolutionLine(field, by, value, got));
+    }
+    const written = { ...ledger, schemaVersion: "1", resolutions: existing };
+    writeLedger(path, written);
+    const count = Object.keys(existing).length;
+    // Printed as the author spelled `--out` (`os.path.join(args.out, …)`), not
+    // as the resolved path the file was written to.
+    run.reporter.info(wroteResolutionsLine(count, pyPathJoin(run.outShown ?? run.out, RESOLUTIONS_FILENAME)));
+    return { path, count, resolved };
+}
+/**
+ * `_resolved_parent_values`: `{parent → resolved id}` for every parent with a
+ * recorded resolution on `nodeType`, read from the ledger just written so the
+ * paste-ready `-f` re-run carries the ids THIS invocation resolved — never
+ * guessed, never retyped. A ledger that will not load answers nothing; the
+ * refusal for that belongs to the write that found it.
+ */
+export function resolvedParentValues(out, nodeType, parents) {
+    let ledger;
+    try {
+        ledger = readLedger(ledgerPath(out));
+    }
+    catch (error) {
+        if (error instanceof LedgerRefusal)
+            return new Map();
+        throw error;
+    }
+    const wanted = new Set(parents);
+    const out_ = new Map();
+    const rows = pyGet(ledger, "resolutions", null);
+    if (!isPlainObject(rows))
+        return new Map();
+    for (const [key, row] of Object.entries(rows)) {
+        const parsed = parseResolutionKey(key);
+        if (parsed === undefined)
+            continue;
+        const [keyNode, field] = parsed;
+        if (keyNode === nodeType && wanted.has(field) && isPlainObject(row))
+            out_.set(field, pyGet(row, "value", null));
+    }
+    const values = new Map();
+    for (const [field, value] of out_) {
+        if (value !== null && value !== undefined && value !== "")
+            values.set(field, pyStrAny(value));
+    }
+    return values;
+}
+/** `set(resolved_parents) == set(action_parents)`: every schema parent has a recorded resolution, the paste-ready re-run condition. */
+export function allParentsResolved(actionParents, resolvedParents) {
+    const wanted = new Set(actionParents);
+    return wanted.size === resolvedParents.size && [...wanted].every((name) => resolvedParents.has(name));
+}

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

@@ -0,0 +1,190 @@
+/**
+ * Every line `prepare_connector.py` printed, as functions that RETURN the text.
+ *
+ * The messages are the product. An agent reads "prepare-connector: …" and does
+ * what it says, so each string here is kept verbatim from the Python — the
+ * same words, the same arrows, the same `…` — and the only thing that changed
+ * is that nothing in this module writes to a stream. The orchestration decides
+ * where a line goes (stdout for progress, stderr for `WARN:` and `note:`), and a
+ * test asserts on the text without capturing anything.
+ *
+ * Two conventions the Python had are made explicit:
+ *
+ *   - `sys.exit("prepare-connector: …")` texts carry their prefix INSIDE the
+ *     string, while a helper's exception was prefixed at the exit site
+ *     (`sys.exit(f"prepare-connector: {error}")`). {@link PrepareRefusal} is a
+ *     refusal whose message is already the full text; {@link exitText} spells
+ *     both kinds the way the terminal saw them.
+ *   - the pasteable `npx flow-sdk registry prepare` spelling is a parameter with
+ *     the Python's literal as its default, so a caller driven from `uip` can
+ *     spell the command for the binary in the reader's hand (see
+ *     `core/cli-spelling.ts`) without this module reading the environment.
+ */
+import { Refusal } from "../errors.js";
+export declare const PREFIX = "prepare-connector: ";
+/** The spelling the Python hard-coded into every pasteable re-run. */
+export declare const PREPARE_COMMAND = "npx flow-sdk registry prepare";
+/** `prepare-connector: <text>`. */
+export declare function prefixed(text: string): string;
+/** `prepare-connector: next: <text>` — the last lines of a run, each one a call the reader can paste. */
+export declare function nextLine(text: string): string;
+/**
+ * A refusal whose message is the COMPLETE text the Python passed to
+ * `sys.exit`, prefix included. Every other {@link Refusal} reaching the exit
+ * boundary is a helper's and gets the prefix there, as the Python's
+ * `sys.exit(f"prepare-connector: {error}")` did.
+ */
+export declare class PrepareRefusal extends Refusal {
+    constructor(message: string, code: string);
+}
+/** What the terminal showed for a thrown value: the Python's `sys.exit` text. */
+export declare function exitText(error: unknown): string;
+/** `  connection: <Name> (<id>)` — `found.get('Name')` renders `None` when the row has none, as Python did. */
+export declare function connectionLine(row: Record<string, unknown>, connectionId: string): string;
+/** `  bindings: <symbolic name> -> <bindings.json>`, once per row this run changed. */
+export declare function bindingsLine(symbolicName: string, bindingsPath: string): string;
+/** `_missing_generic_schema_message`: a Generic action that expanded to nothing. */
+export declare function missingGenericSchemaMessage(operation: string, objectName?: string | null): string;
+/**
+ * `_unresolved_action_message`: what to do when the action id is not a
+ * registry key. `actions` is what `registry search <key>` served (see
+ * `actions.ts`); the message is pure over it.
+ *
+ * NOT auto-substituted, deliberately: the baked action id and the registry key
+ * are different namespaces, and guessing between them would emit a node both
+ * offline validators accept and the runtime dispatches to the wrong operation.
+ */
+export declare function unresolvedActionMessage(connectorKey: string, action: string, nodeType: string, actions: readonly string[]): string;
+export declare function noCanonicalEntryMessage(nodeType: string): string;
+/** The `-f` names do not match any api-type ObjectAction; `specs` are the actions' parent lists. */
+export declare function parentFieldNamesMismatchMessage(given: readonly string[], specs: ReadonlyArray<readonly [string, readonly string[]]>): string;
+export declare function genericActionNeedsObjectMessage(): string;
+export declare function objectFlagsOnlyForGenericMessage(): string;
+/** `_parse_fields`'s refusal of a `-f` without `=`. */
+export declare function fieldFlagMessage(pair: string): string;
+/**
+ * `_rejected_parent_fields_message`: the CLI's own rejection is the actionable
+ * half and the pipeline otherwise swallows it, so quote the service.
+ * `failures` are `(connector, object, operation, message)` tuples; the first
+ * non-empty message is the one quoted.
+ */
+export declare function rejectedParentFieldsMessage(pairs: readonly string[], failures?: ReadonlyArray<readonly unknown[]>): string;
+/** `  object: <note>` — the ladder's normalization sentence. */
+export declare function objectNoteLine(note: string): string;
+/** `  object: <requested> -> <matched> recorded in <ledger>`. */
+export declare function objectRecordedLine(requested: string, matched: string, ledgerPath: string): string;
+/** `_input_field_note`: `N input field(s)`, or the unavailable marker when the count could not be read. */
+export declare function inputFieldNote(count: number | undefined | null): string;
+/** `JSON overlay only` or `overlay + <key>.ts`. */
+export declare function tsNote(jsonOnly: boolean, connectorKey: string): string;
+/** The action path's success line. */
+export declare function preparedSummaryLine(nodeType: string, out: string, ts: string, variants: number, fieldNote: string): string;
+/** Why this run did not overwrite the overlay (`_keep_prepared_schema`). */
+export declare function keptSchemaMessage(action: string, kept: number, discarded: number): string;
+/** The set was SHAPED right but resolved to nothing new: a VALUE is wrong for this connection. */
+export declare function parentOnlyMessage(parents: readonly string[], fieldPairs: readonly string[]): string;
+type Values = ReadonlyMap<string, string> | Readonly<Record<string, string>>;
+/**
+ * The paste-ready re-run when every schema parent already has a recorded
+ * resolution: the ids `--resolve` just wrote ARE the `-f` values.
+ */
+export declare function resolvedParentsNote(connectorKey: string, action: string, actionParents: readonly string[], resolvedParents: Values, command?: string): string;
+/** The note when some schema parent did not arrive as `-f`, with the example re-run. */
+export declare function missingParentsNote(connectorKey: string, action: string, actionParents: readonly string[], missing: readonly string[], parentFields: Values, command?: string): string;
+/** The parts of a lookup spec the vocabulary print reads. */
+export interface VocabularySpec {
+    by?: readonly string[];
+    objectName?: string;
+    path?: string;
+    value?: string;
+    [key: string]: unknown;
+}
+/**
+ * `_print_lookup_vocabulary`: the lookup table for the operation just
+ * prepared, or no lines at all when it has no lookups. The markdown catalog
+ * renders this for BAKED schemas; a schema that only exists because `prepare`
+ * ran has no page, so the command is where the vocabulary first becomes
+ * knowable.
+ */
+export declare function lookupVocabularyLines(connectorKey: string, action: string, objectName: string | undefined | null, specs: ReadonlyMap<string, VocabularySpec>, command?: string): string[];
+/** A `--resolve` names a field with no lookup; `known` are the fields that have one, sorted. */
+export declare function unknownLookupMessage(unknown: readonly string[], nodeType: string, known: readonly string[]): string;
+/** `  <field>: <by>=<value> -> <id>`, with ` (already resolved)` when the ledger answered. */
+export declare function resolutionLine(field: string, by: string, value: string, got: unknown, alreadyResolved?: boolean): string;
+export declare function wroteResolutionsLine(count: number, ledgerPath: string): string;
+/**
+ * `generated N connector module(s) → <out>` — the descriptor generator's own
+ * last line (`generate_connectors_ts.py`), which `prepare` spawned between
+ * the resolution lines and its summary. `outDir` is `str(Path(args.output))`.
+ */
+export declare function generatedModulesLine(count: number, outDir: string): string;
+/** `<Name> (<Folder>)` for a per-candidate report line (`_candidate_label`). */
+export declare function candidateLabel(row: Record<string, unknown>): string;
+/** `  <field>: not on this connection; trying N other <key> connection(s)`. */
+export declare function tryingOtherConnectionsLine(field: string, count: number, connectorKey: string): string;
+/** `  connection: <label> resolves <field>; re-running against it (--connection-id <id>)`. */
+export declare function rerunAgainstLine(label: string, field: string, connectionId: string): string;
+/** The terminal report's line for a candidate that resolved every requested lookup. */
+export declare function candidateResolvesAllLine(label: string, lookups: number): string;
+/** The terminal report's line for a candidate whose collection was read to the end. */
+export declare function candidateExhaustedLine(label: string, field: string, scanned: number): string;
+/** The terminal report's line for a candidate whose lookup failed for another reason: the error, verbatim. */
+export declare function candidateErrorLine(label: string, error: unknown): string;
+/**
+ * An explicit `--connection-id` / `--connection` is the author's decision and
+ * is not overridden. The alternatives are still named, because the whole cost
+ * of this bug was not knowing they existed. `first` is the exhausted lookup's
+ * own message; `others` the pasteable listing of the other candidates.
+ */
+export declare function pinnedConnectionExhaustedMessage(first: string, connectorKey: string, othersCount: number, othersListing: string): string;
+/** The listing of other connections itself failed; the original lookup failure is what the author asked about. */
+export declare function candidateListingFailedMessage(first: string, error: unknown): string;
+export declare function onlyConnectionMessage(first: string, connectorKey: string): string;
+/** Two or more candidates resolve everything: reported, never chosen between. */
+export declare function severalConnectionsResolveMessage(count: number, connectorKey: string, listing: string): string;
+/**
+ * Nothing resolved anywhere: every candidate and what it held, one per line.
+ * HERE is where the collection listing finally belongs — every connection has
+ * been tried, so seeing what the collection actually holds is the next step
+ * rather than the detour it is while a retry is still available.
+ */
+export declare function noConnectionResolvesMessage(connectorKey: string, first: {
+    field: string;
+    by: string;
+    value: string;
+    collection: string;
+}, lines: readonly string[], connectionId: string): string;
+export declare function eventParentFieldsMessage(): string;
+export declare function eventAllObjectsMessage(): string;
+/** A Generic event fires for ONE object; name it. `rows` is the `triggers objects` catalog. */
+export declare function genericEventNeedsObjectMessage(action: string, rows: ReadonlyArray<Record<string, unknown>>): string;
+export declare function objectOnCuratedEventMessage(action: string, builtInObject: unknown): string;
+/** `  WARN: <error>` — a listing failure a curated event survives. */
+export declare function warnLine(error: unknown): string;
+/** The describe could not answer for a curated event; the definition's own sections stand in. */
+export declare function describeFallbackWarning(error: unknown, bakedObject: string): string;
+export declare function byoaListingFailedMessage(connectionId: string, error: unknown): string;
+export declare function byoaRequiredMessage(connectionId: string, connectorKey: string, listing: string): string;
+export declare function eventSummaryLine(eventNodeType: string, out: string, operation: string, mode: string, whereParameters: number, filterFields: number): string;
+/** The first eight filterable field names, or nothing when the event has none. */
+export declare function filterableFieldsLine(filterFields: ReadonlyArray<Record<string, unknown>>): string | undefined;
+/**
+ * The webhook note and the connector's own registration text, or nothing for a
+ * polling event. Registration is an act on the external service — the one step
+ * the loop cannot make deterministic — so the connector's words are handed over
+ * instead of leaving `uip is webhooks config` to be discovered.
+ */
+export declare function webhookNoteLines(mode: string, textBlocks: readonly string[]): string[];
+/** `{ connector: '…', event: '…'[, object: '…'], connection: '…', folder: '…' }`. */
+export declare function eventSubscription(connectorKey: string, action: string, objectName: string | undefined | null, connectionName: string, folderName: string): string;
+export declare function eventNextLine(subscription: string): string;
+export declare function sourceNotAFileLine(source: string): string;
+export declare function severalSourcesLine(names: readonly string[]): string;
+export declare function repointedLine(sourceRelative: string, specifier: string): string;
+/** The two-line fallback when the module could not be read or exports several descriptors. */
+export declare function descriptorUsageFallbackLines(sourcePosix: string): string[];
+/** The module has one descriptor but its inputs interface could not be parsed. */
+export declare function descriptorUsageUnparsedLines(sourcePosix: string, descriptorName: string): string[];
+/** The ready-to-paste handoff for a module with exactly one descriptor. */
+export declare function descriptorUsageLines(descriptorName: string, importPath: string, requiredFields: ReadonlyArray<readonly [name: string, type: string]>, boundConnection: string, boundFolder: string): string[];
+export {};