@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

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

@@ -0,0 +1,91 @@
+import { type BuildCaches, type BuildContext } from "../library-build/context.js";
+import type { Reporter } from "../reporter.js";
+import type { UipClient } from "../uip/client.js";
+import { type CatalogueRow } from "./objects.js";
+/** The command line, as `argparse` parsed it. Defaults are the Python's. */
+export interface PrepareOptions {
+    connectorKey: string;
+    action: string;
+    /** Omit to discover the connection from `uip is connections list`. */
+    connectionId?: string;
+    /** `--connection <name>`: pick the connection by name when several match. */
+    connection?: string;
+    /** `--bindings` (default `./bindings.json`). */
+    bindings?: string;
+    /** `--bind-connection` (default: the connector's last dash-segment). */
+    bindConnection?: string;
+    /** `--bind-folder` (default `shared`). */
+    bindFolder?: string;
+    noBindings?: boolean;
+    /** `--object`; mutually exclusive with `allObjects`. */
+    objectName?: string;
+    allObjects?: boolean;
+    /** `-f NAME=VALUE`, repeatable, in the order given. */
+    fields?: readonly string[];
+    /** `--out` (default `./connectors-local`). */
+    out?: string;
+    /** `--source`: the `.flow.ts` whose import is repointed. */
+    source?: string;
+    noSourceRewrite?: boolean;
+    /** `--version`: pin an op version. */
+    version?: string;
+    /** `--import`: the module specifier the emitted `.ts` imports from (default {@link PACKAGE_NAME}). */
+    importSpecifier?: string;
+    /** `--resolve FIELD:BY=VALUE`, repeatable. */
+    resolve?: readonly string[];
+    refreshLookups?: boolean;
+    jsonOnly?: boolean;
+}
+export interface PreparePorts {
+    client: UipClient;
+    reporter: Reporter;
+    /** Response caches for this run; in-memory ones by default (the Python used a temp dir). */
+    caches?: BuildCaches;
+    /** The project root the Python read as `Path.cwd()`. Defaults to the process's. */
+    cwd?: string;
+    timeoutMs?: number;
+    /** How the pasteable `registry prepare` is spelled in the notes. */
+    prepareCommand?: string;
+}
+export interface PrepareReport {
+    kind: "action" | "event";
+    /** The node type the overlay entry is stored under (the WAIT form for an event). */
+    nodeType: string;
+    connectionId: string;
+    /** The symbolic names written to `bindings.json`, when bindings were touched. */
+    bound?: {
+        connection: string;
+        folder: string;
+    };
+    /** Action path only. */
+    variants?: number;
+    inputFields?: number;
+    kept?: [kept: number, discarded: number];
+    objectName?: string;
+}
+/**
+ * `_match_catalog_object`: the catalog row `--object` names, or `undefined`
+ * when the catalog itself is unavailable — that failure belongs to expansion,
+ * whose message already covers it. Every refusal past the name rungs is
+ * retried once against a refreshed catalog before it is believed: the
+ * `uip is resources list` cache never invalidates itself (measured: 18
+ * objects stale vs 864 fresh on uipath-salesforce-sfdc). Ambiguity WITHIN a
+ * name rung is not retriable — the refusal's call, not this loop's.
+ */
+export declare function matchCatalogObject(ctx: BuildContext, connectorKey: string, wanted: string, verb: string | undefined): Promise<CatalogueRow | undefined>;
+/**
+ * The whole command. Throws a {@link Refusal} for every path the Python
+ * `sys.exit`ed on; the report is what a caller wanting more than the printed
+ * lines can read.
+ *
+ * When a `--resolve` reads a collection to the end on the connection this
+ * command PICKED and finds nothing, the other enabled connections for the
+ * connector are probed, and the run starts over pinned to the one that
+ * resolves everything (flow-builder-sdk#744). The Python re-exec'd itself for
+ * that; here the bindings snapshot is restored and `prepareConnector` is
+ * re-entered with `--connection-id <winner> --refresh-lookups`. The refresh is
+ * NOT optional: the ledger keys a resolution by `[nodeType, field, by, value]`
+ * and not by connection, so an id recorded against the connection just
+ * abandoned would come back as "already resolved" on the re-run.
+ */
+export declare function prepareConnector(options: PrepareOptions, ports: PreparePorts): Promise<PrepareReport>;

package/dist/registry/prepare/pipeline.js

@@ -0,0 +1,376 @@
+/**
+ * `main()` of `prepare_connector.py`, as a function of its options and ports.
+ *
+ * Fetch ONE connector op's FULL, connection-resolved schema into the
+ * `./connectors-local/` overlay plus a typed `.ts`. The baked library is
+ * tenant-agnostic, so schema-dynamic ops ship only their connection-independent
+ * fields; this closes that at author time with a live connection, writing the
+ * same artifacts the bulk generator produces into an overlay the compile CLIs
+ * auto-detect. Calls ACCUMULATE — each prepared op merges into `--out`.
+ *
+ * The stages, in the Python's order: the connection (discovered or checked)
+ * and `bindings.json`; the registry definition, or the event twin; the schema
+ * (Generic expansion or a describe); the overlay merge, guarded by the
+ * keep-prepared-schema rule; the object decision and the lookup resolutions
+ * in the ledger; the descriptors; then the summary and every note, and finally
+ * the repointed import and the handoff.
+ *
+ * Every `uip` call goes through the {@link BuildContext} built from the ports,
+ * so a test drives the whole pipeline from a fake client; every `sys.exit` is a
+ * thrown {@link Refusal} carrying the same text (see `messages.ts`'s
+ * `exitText` for how the boundary spells them).
+ *
+ * Every path is printed as the author typed it — `--out` and `--bindings` go
+ * into the lines verbatim, as `args.out` and `args.bindings` did — while the
+ * file system is reached through paths resolved against `cwd`.
+ */
+import { resolve } from "node:path";
+import { PACKAGE_NAME } from "../../package-name.js";
+import { afterLast } from "../compat/pystr.js";
+import { extractCanonical, isHttpPassthrough, nodeOf } from "../library-build/canonical.js";
+import { createBuildContext, isResourcesList, registryGet } from "../library-build/context.js";
+import { enrichEntry } from "../library-build/enrich.js";
+import { expandGenericForConnector, genericTemplatesByOp } from "../library-build/generic-expand.js";
+import { planLibrary } from "../library-build/plan.js";
+import { MemoryResponseCache } from "../uip/response-cache.js";
+import { registryActions } from "./actions.js";
+import { discoverConnection, lookupConnection, mergeBindings, restoreBindings, snapshotBindings, } from "./connections.js";
+import { prepareEvent } from "./event.js";
+import { descriptorUsage } from "./handoff.js";
+import { ResolutionsExhausted, allParentsResolved, resolvedParentValues, writeResolutions } from "./ledger.js";
+import { PREPARE_COMMAND, PrepareRefusal, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, keptSchemaMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, tsNote, unresolvedActionMessage, } from "./messages.js";
+import { ObjectMatchRefusal, RESOLUTIONS_FILENAME, matchObject, recordObjectResolution } from "./objects.js";
+import { countInputFields, keepPreparedSchema, lookupSpecsFromOverlay, mergeFilesInto, parentFields as overlayParentFields, schemaActionParents, } from "./overlay.js";
+import { declaredParents, objectActionRequest, objectActionSpecs, parseFields } from "./parents.js";
+import { regenerateDescriptors } from "./regenerate.js";
+import { retryOtherConnections } from "./retry.js";
+import { repointSource } from "./source-import.js";
+import { isPlainObject, pyGet, pyOr, pyPathJoin, pyPathlibStr, pyStrAny, pyTruthy } from "./support.js";
+function memoryCaches() {
+    return { registry: new MemoryResponseCache(), is: new MemoryResponseCache(), connectors: new MemoryResponseCache() };
+}
+/**
+ * `_match_catalog_object`: the catalog row `--object` names, or `undefined`
+ * when the catalog itself is unavailable — that failure belongs to expansion,
+ * whose message already covers it. Every refusal past the name rungs is
+ * retried once against a refreshed catalog before it is believed: the
+ * `uip is resources list` cache never invalidates itself (measured: 18
+ * objects stale vs 864 fresh on uipath-salesforce-sfdc). Ambiguity WITHIN a
+ * name rung is not retriable — the refusal's call, not this loop's.
+ */
+export async function matchCatalogObject(ctx, connectorKey, wanted, verb) {
+    let rows = ((await isResourcesList(ctx, connectorKey, { operation: verb })) ?? []).filter(isPlainObject);
+    if (rows.length === 0)
+        return undefined;
+    for (const attempt of ["cached", "refreshed"]) {
+        try {
+            const { row, note } = matchObject(rows, wanted, verb);
+            if (note)
+                ctx.reporter.info(objectNoteLine(note));
+            return row;
+        }
+        catch (error) {
+            if (!(error instanceof ObjectMatchRefusal))
+                throw error;
+            if (attempt === "cached" && error.retriable) {
+                const refreshed = ((await isResourcesList(ctx, connectorKey, { operation: verb, refresh: true })) ?? []).filter(isPlainObject);
+                if (refreshed.length > 0)
+                    rows = refreshed;
+                continue;
+            }
+            throw error;
+        }
+    }
+    return undefined;
+}
+/** Stage 0: the connection, discovered or checked, and its row in `bindings.json`. */
+async function connect(options, ports) {
+    const info = (line) => ports.reporter.info(line);
+    let row;
+    let connectionId;
+    if (!options.connectionId) {
+        // Discover the connection when the caller did not name one, and record it
+        // in bindings.json so the author never has to look up either key — the
+        // step that removes 4-7 tool calls per task.
+        row = await discoverConnection(ports.client, options.connectorKey, options.connection);
+        connectionId = pyStrAny(row.Id);
+    }
+    else {
+        // An explicit id gets the same gate discovery applies: a `State: Failed`
+        // connection answers field discovery with an EMPTY schema.
+        connectionId = options.connectionId;
+        row = await lookupConnection(ports.client, options.connectorKey, connectionId);
+    }
+    info(connectionLine(row, connectionId));
+    if (options.noBindings)
+        return { connectionId, row };
+    // Recorded on BOTH routes. Until 3.30.5 only discovery wrote it, and the
+    // explicit-id route left the author hand-writing the id and folder key.
+    const bindingsShown = options.bindings ?? "./bindings.json";
+    const bindingsPath = resolve(ports.cwd ?? process.cwd(), bindingsShown);
+    // Taken before the first write so a later refusal can undo exactly this
+    // command's changes, and only them.
+    const rollback = { path: bindingsPath, snapshot: snapshotBindings(bindingsPath), shown: bindingsShown };
+    // `args.bind_connection or args.key.rsplit("-", 1)[-1]`: an empty
+    // --bind-connection falls back, as Python's `or` did. --bind-folder is an
+    // argparse default, so an empty one STANDS, as it did there.
+    const symbolic = pyOr(options.bindConnection, afterLast(options.connectorKey, "-"));
+    const folder = options.bindFolder ?? "shared";
+    const [wroteConnection, wroteFolder] = mergeBindings(bindingsPath, symbolic, folder, row);
+    if (wroteConnection)
+        info(bindingsLine(symbolic, bindingsShown));
+    if (wroteFolder)
+        info(bindingsLine(folder, bindingsShown));
+    return { connectionId, row, bound: { connection: symbolic, folder }, rollback };
+}
+/**
+ * The whole command. Throws a {@link Refusal} for every path the Python
+ * `sys.exit`ed on; the report is what a caller wanting more than the printed
+ * lines can read.
+ *
+ * When a `--resolve` reads a collection to the end on the connection this
+ * command PICKED and finds nothing, the other enabled connections for the
+ * connector are probed, and the run starts over pinned to the one that
+ * resolves everything (flow-builder-sdk#744). The Python re-exec'd itself for
+ * that; here the bindings snapshot is restored and `prepareConnector` is
+ * re-entered with `--connection-id <winner> --refresh-lookups`. The refresh is
+ * NOT optional: the ledger keys a resolution by `[nodeType, field, by, value]`
+ * and not by connection, so an id recorded against the connection just
+ * abandoned would come back as "already resolved" on the re-run.
+ */
+export async function prepareConnector(options, ports) {
+    const info = (line) => ports.reporter.info(line);
+    const warn = (line) => ports.reporter.warn(line);
+    // Whether the CALLER chose the connection, recorded before discovery answers
+    // with its own. An explicit choice is never second-guessed: the retry below
+    // is for a connection this command picked, not for one the author named.
+    const pinned = pyTruthy(options.connectionId) || pyTruthy(options.connection);
+    const connected = await connect(options, ports);
+    try {
+        return await prepareOnConnection(options, ports, connected);
+    }
+    catch (error) {
+        if (!(error instanceof ResolutionsExhausted))
+            throw 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, try the other enabled connections. A
+        // transport failure is the parent refusal and never reaches here.
+        const chosen = await retryOtherConnections({
+            client: ports.client,
+            reporter: ports.reporter,
+            connectorKey: options.connectorKey,
+            connectionId: connected.connectionId,
+            connection: options.connection,
+            pinned,
+        }, error.plan, error.first);
+        // Undo the bindings this run wrote for the connection that cannot serve
+        // the lookups, then start over pinned to the one that can. Re-running
+        // rather than switching in place is deliberate: the overlay and its
+        // lookup specs are described THROUGH a connection
+        // (`lookupSpecsFromOverlay`), so adopting a different connection after the
+        // describe would leave the overlay describing one connection while
+        // bindings.json names another.
+        if (connected.rollback)
+            restoreBindings(connected.rollback.path, connected.rollback.snapshot, warn, connected.rollback.shown);
+        const chosenId = pyStrAny(pyGet(chosen, "Id", null));
+        info(rerunAgainstLine(candidateLabel(chosen), error.field, chosenId));
+        // THE LOOP GUARD, and it is this line rather than a counter: the re-entry
+        // carries `connectionId`, so its own `pinned` is true and a second
+        // exhaustion takes the pinned branch — a refusal naming the alternatives —
+        // instead of probing again. The Python got the same guard from the same
+        // place, since the re-exec'd process recomputed
+        // `args._connection_pinned = bool(args.connection_id or args.connection)`
+        // from the `--connection-id` it had just been handed. One probing round
+        // per command is the whole contract: the probe has already proved this
+        // connection resolves every lookup, so a re-run that still cannot is a
+        // changed tenant, not another connection to go looking through.
+        return prepareConnector({ ...options, connectionId: chosenId, refreshLookups: true }, ports);
+    }
+}
+/** Everything after stage 0, against one settled connection. */
+async function prepareOnConnection(options, ports, connected) {
+    const cwd = ports.cwd ?? process.cwd();
+    const info = (line) => ports.reporter.info(line);
+    const warn = (line) => ports.reporter.warn(line);
+    const command = ports.prepareCommand ?? PREPARE_COMMAND;
+    const { connectorKey, action } = options;
+    const fieldPairs = options.fields ?? [];
+    const parentFields = parseFields(fieldPairs);
+    const outShown = options.out ?? "./connectors-local";
+    const out = resolve(cwd, outShown);
+    const importSpecifier = options.importSpecifier ?? PACKAGE_NAME;
+    const jsonOnly = options.jsonOnly ?? false;
+    const { connectionId, bound, rollback } = connected;
+    const ctx = createBuildContext({ client: ports.client, caches: ports.caches ?? memoryCaches(), reporter: ports.reporter, concurrency: 1, timeoutMs: ports.timeoutMs }, { connectionId, parentFields });
+    const nodeType = `uipath.connector.${connectorKey}.${action}`;
+    const cacheName = await registryGet(ctx, nodeType, true);
+    if (cacheName === undefined) {
+        // Not an activity. Connector EVENTS live one namespace over, and their
+        // registry definition only answers with a connection, which this command
+        // has by now. Same loop, different twin pair.
+        const event = await prepareEvent(ctx, {
+            connectorKey,
+            action,
+            connectionId,
+            objectName: options.objectName,
+            allObjects: options.allObjects,
+            fields: fieldPairs,
+            resolve: options.resolve,
+            refreshLookups: options.refreshLookups,
+            out,
+            outShown,
+            importSpecifier,
+            jsonOnly,
+            boundConnection: bound?.connection,
+            boundFolder: bound?.folder,
+            bindings: rollback,
+            prepareCommand: command,
+        });
+        if (event !== undefined) {
+            return { kind: "event", nodeType: event.eventNodeType, connectionId, bound, objectName: event.objectName };
+        }
+        const actions = await registryActions(ports.client, connectorKey, ports.timeoutMs);
+        throw new PrepareRefusal(unresolvedActionMessage(connectorKey, action, nodeType, actions), "ACTION_UNKNOWN");
+    }
+    const payload = ctx.caches.registry.read(cacheName);
+    // The registry's own declaration of parent inputs, read from the same reply.
+    const declared = declaredParents(payload);
+    let entry = extractCanonical(nodeOf(payload));
+    if (entry === undefined)
+        throw new PrepareRefusal(noCanonicalEntryMessage(nodeType), "NO_CANONICAL_ENTRY");
+    if (options.version)
+        entry.version = options.version;
+    if (parentFields.size > 0) {
+        const request = objectActionRequest(payload, parentFields);
+        if (request === undefined) {
+            throw new PrepareRefusal(parentFieldNamesMismatchMessage([...parentFields.keys()], objectActionSpecs(payload)), "PARENT_FIELDS_MISMATCH");
+        }
+        entry.operation.customFieldsRequestDetails = request;
+    }
+    let objectName = options.objectName;
+    let objectDecision;
+    let preparedEntries;
+    const isExpandableGeneric = entry.operation.activityType === "Generic" && !isHttpPassthrough(entry);
+    if (isExpandableGeneric) {
+        if (!objectName && !options.allObjects)
+            throw new PrepareRefusal(genericActionNeedsObjectMessage(), "OBJECT_REQUIRED");
+        const templates = genericTemplatesByOp([entry]).get(connectorKey) ?? new Map();
+        if (objectName) {
+            // The author's name, not necessarily the API's: matched deterministically
+            // BEFORE expansion — expansion re-reads the same cached catalog, so the
+            // match costs no extra network.
+            const verb = templates.size === 1 ? [...templates.keys()][0] : undefined;
+            const requested = objectName;
+            const row = await matchCatalogObject(ctx, connectorKey, objectName, verb);
+            if (row !== undefined) {
+                objectName = pyStrAny(pyOr(pyGet(row, "Name", null), objectName));
+                objectDecision = { requested, row, verb };
+            }
+        }
+        const selected = options.allObjects ? undefined : [objectName];
+        preparedEntries = await expandGenericForConnector(ctx, connectorKey, templates, selected);
+        if (preparedEntries.length === 0) {
+            const operation = pyStrAny(pyOr(pyGet(entry.operation, "name", null), action));
+            throw new PrepareRefusal(missingGenericSchemaMessage(operation, options.allObjects ? undefined : objectName), "GENERIC_SCHEMA_MISSING");
+        }
+    }
+    else {
+        if (objectName || options.allObjects)
+            throw new PrepareRefusal(objectFlagsOnlyForGenericMessage(), "OBJECT_NOT_GENERIC");
+        entry = await enrichEntry(ctx, entry); // full schema via --connection-id
+        preparedEntries = [entry];
+    }
+    const entryNodeType = entry.nodeType;
+    const plan = planLibrary(preparedEntries, (requestedNodeType) => (requestedNodeType === entryNodeType ? nodeOf(payload) : undefined));
+    for (const line of plan.warnings)
+        warn(line);
+    const kept = keepPreparedSchema(out, entryNodeType, plan.files, parentFields, objectName);
+    if (kept === undefined)
+        mergeFilesInto(plan.files, out);
+    // The object decision is the FIRST resolution — recorded before any lookup
+    // rows, because it is their prerequisite.
+    if (objectDecision !== undefined) {
+        recordObjectResolution(out, nodeType, objectDecision.requested, objectDecision.row, objectDecision.verb);
+        // Named as the author spelled `--out` (`os.path.join(args.out, …)`).
+        info(objectRecordedLine(objectDecision.requested, objectName, pyPathJoin(outShown, RESOLUTIONS_FILENAME)));
+    }
+    if (pyTruthy(options.resolve)) {
+        // A `ResolutionsExhausted` propagates to `prepareConnector`, which owns
+        // the retry: re-running pinned means starting the whole command over.
+        await writeResolutions({
+            client: ports.client,
+            connectorKey,
+            connectionId,
+            out,
+            outShown,
+            nodeType,
+            objectName,
+            resolve: options.resolve,
+            refreshLookups: options.refreshLookups,
+            reporter: ports.reporter,
+        });
+    }
+    const modules = regenerateDescriptors(out, importSpecifier, jsonOnly);
+    // The generator's own last line, which the Python spawned and so printed
+    // between the resolution lines and the summary; under --json-only it never
+    // ran and said nothing.
+    if (!jsonOnly)
+        info(generatedModulesLine(modules.length, pyPathlibStr(outShown)));
+    const inputFields = countInputFields(out, entryNodeType, objectName);
+    const variants = preparedEntries.length;
+    // The describe is the evidence, not the finished field count: a rejected
+    // parent set leaves the registry-DECLARED fields in the overlay, so surface
+    // the CLI's own message instead of that quiet success.
+    const failures = ctx.failedFieldDescribes;
+    if (fieldPairs.length > 0 && (failures.length > 0 || inputFields === 0)) {
+        throw new PrepareRefusal(rejectedParentFieldsMessage(fieldPairs, failures), "PARENT_FIELDS_REJECTED");
+    }
+    info(preparedSummaryLine(nodeType, outShown, tsNote(jsonOnly, connectorKey), variants, inputFieldNote(inputFields)));
+    if (kept !== undefined)
+        info(keptSchemaMessage(action, kept[0], kept[1]));
+    for (const line of lookupVocabularyLines(connectorKey, action, objectName, lookupSpecsFromOverlay(out, nodeType, objectName), command)) {
+        info(line);
+    }
+    // Whether this operation has parent fields is answered by what was just
+    // prepared, not by a catalog flag.
+    const [parents, parentOnly] = overlayParentFields(out, entryNodeType, objectName);
+    if (parentOnly && fieldPairs.length > 0) {
+        throw new PrepareRefusal(parentOnlyMessage(parents, fieldPairs), "PARENT_VALUES_UNRESOLVED");
+    }
+    // Whether the schema action RAN is decided by its inputs, not by its output:
+    // every parent it names must have arrived as `-f`. Union of both declaration
+    // sites so an overlay that omits `schemaAction` still gets the registry's.
+    const actionParents = schemaActionParents(out, entryNodeType, objectName);
+    for (const name of declared)
+        if (!actionParents.includes(name))
+            actionParents.push(name);
+    const missing = actionParents.filter((name) => !parentFields.has(name));
+    // Silent when the schema was KEPT: the note's premise is that the overlay
+    // carries only the unresolved entry, and it does not.
+    if (missing.length > 0 && kept === undefined) {
+        const resolvedParents = resolvedParentValues(out, nodeType, actionParents);
+        if (allParentsResolved(actionParents, resolvedParents)) {
+            warn(resolvedParentsNote(connectorKey, action, actionParents, resolvedParents, command));
+        }
+        else {
+            warn(missingParentsNote(connectorKey, action, actionParents, missing, parentFields, command));
+        }
+    }
+    if (!jsonOnly) {
+        // Print what was bound, so the last line of output is a call the reader
+        // can paste rather than `<binding-name>` placeholders. `or`, not `??`: an
+        // empty symbolic name is a placeholder in Python's eyes too.
+        let usage = descriptorUsage(outShown, connectorKey, pyOr(bound?.connection, "<binding-name>"), pyOr(bound?.folder, "<folder-binding-name>"), cwd);
+        const repointed = repointSource({ out: outShown, connectorKey, cwd, source: options.source, noSourceRewrite: options.noSourceRewrite });
+        if (repointed.length > 0 && repointed[0].startsWith("repointed ")) {
+            // The edit is DONE, so telling the author to make it is now false.
+            usage = usage.filter((line) => !line.startsWith("import {"));
+        }
+        for (const line of repointed)
+            info(prefixed(line));
+        for (const line of usage)
+            info(nextLine(line));
+    }
+    return { kind: "action", nodeType, connectionId, bound, variants, inputFields, kept, objectName };
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Write `<out>/<connectorKey>.ts` for every connector in the overlay and
+ * return the module names written; nothing at all under `--json-only`.
+ *
+ * The generator wrote every module and only then exited 1 on a required-input
+ * gap; the files are on disk here too, and the failure is as loud and as late
+ * (a {@link Refusal} carrying the generator's own text).
+ */
+export declare function regenerateDescriptors(out: string, importSpecifier: string, jsonOnly?: boolean): string[];

package/dist/registry/prepare/regenerate.js

@@ -0,0 +1,50 @@
+/**
+ * Rewrite the overlay's typed descriptors from the overlay's own JSON.
+ *
+ * Both prepare paths end here. The EVENT path used not to: it wrote the JSON
+ * overlay and returned, so a project whose only prepare was an event got no
+ * `.ts` at all, and one that had prepared an action earlier kept that older
+ * run's module — generated before the event's parameters were in the overlay,
+ * so `where` was `Record<string, string>` and the trigger carried no
+ * `lookups`. That is the module `prepare` tells the author to import, and
+ * `--refresh-lookups` could not repair it.
+ *
+ * `includeGenericExpanded` is decided from the WHOLE overlay index rather than
+ * the entries of this run: the generator rewrites every module under the
+ * output, so reading one run would drop the descriptors an earlier
+ * `GenericExpanded` prepare had written.
+ *
+ * Ported from `_regenerate_descriptors`, which spawned
+ * `generate_connectors_ts.py --library <out> --output <out>`; the generator is
+ * now `renderDescriptorModules`, called in-process.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Refusal } from "../errors.js";
+import { formatRequiredInputGaps, renderDescriptorModules } from "../generators/descriptors.js";
+import { loadLibrary } from "../library-reader.js";
+import { overlayHasGenericExpanded } from "./overlay.js";
+/**
+ * Write `<out>/<connectorKey>.ts` for every connector in the overlay and
+ * return the module names written; nothing at all under `--json-only`.
+ *
+ * The generator wrote every module and only then exited 1 on a required-input
+ * gap; the files are on disk here too, and the failure is as loud and as late
+ * (a {@link Refusal} carrying the generator's own text).
+ */
+export function regenerateDescriptors(out, importSpecifier, jsonOnly = false) {
+    if (jsonOnly)
+        return [];
+    const library = loadLibrary(out);
+    const output = renderDescriptorModules(library, {
+        importSpecifier,
+        includeGenericExpanded: overlayHasGenericExpanded(out),
+    });
+    mkdirSync(out, { recursive: true });
+    for (const [name, text] of output.modules)
+        writeFileSync(join(out, name), text, "utf8");
+    if (output.requiredInputGaps.length > 0) {
+        throw new Refusal(formatRequiredInputGaps(output.requiredInputGaps), "REQUIRED_INPUT_GAP");
+    }
+    return [...output.modules.keys()];
+}