@uipath/maestro-builder-sdk 6.3.0 → 6.5.0

package/dist/registry/files.js

@@ -0,0 +1,160 @@
+/**
+ * The filesystem moves the registry makes, in one place.
+ *
+ * Generators return strings and maps; these helpers put them on disk. The
+ * stage-and-swap dance exists because two `registry pull`s can race on the
+ * shared cache when a coding agent issues tool calls in parallel, and a
+ * converter that wipes and rewrites its output directory in place left one of
+ * them mid-write.
+ */
+import { mkdirSync, renameSync, rmSync, writeFileSync, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { messageOf } from "./errors.js";
+export function ensureDir(path) {
+    mkdirSync(path, { recursive: true });
+}
+export function writeText(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text, "utf8");
+}
+export function writeBytes(path, bytes) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, bytes);
+}
+export function readText(path) {
+    return readFileSync(path, "utf8");
+}
+export function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+export function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Every file under `root`, as paths relative to it with `/` separators, sorted. */
+export function listFiles(root, filter) {
+    const out = [];
+    const walk = (dir, prefix) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                walk(join(dir, entry.name), rel);
+            else if (entry.isFile() && (!filter || filter(rel)))
+                out.push(rel);
+        }
+    };
+    if (existsSync(root))
+        walk(root, "");
+    return out.sort();
+}
+/**
+ * Build a directory beside its final name, then swap it into place.
+ *
+ * `fill` writes into `<target>.tmp-<pid>`. When it returns, any existing
+ * `target` is renamed to `<target>.old-<pid>`, the staging directory takes the
+ * final name, and the old tree is removed. A failure inside `fill` leaves the
+ * previous `target` untouched and cleans up the staging directory; a failure
+ * of the final rename puts the parked tree back, so the previous output
+ * survives as it did when Python's `Path.rename` raised.
+ *
+ * On overlayfs — every Docker RUN after the first — a directory written by an
+ * earlier layer cannot be renamed, so the parking step falls back to deleting
+ * it. See the comment on that branch for what the fallback gives up.
+ */
+export function stageAndSwap(target, fill) {
+    const staging = `${target}.tmp-${process.pid}`;
+    const previous = `${target}.old-${process.pid}`;
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(staging, { recursive: true });
+    try {
+        fill(staging);
+    }
+    catch (error) {
+        rmSync(staging, { recursive: true, force: true });
+        throw error;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    // Which of the three states the target is in when the final rename runs, so
+    // a failure there can say honestly what is and is not still on disk.
+    let parked = "nothing-was-there";
+    if (existsSync(target)) {
+        try {
+            renameSync(target, previous);
+            parked = "parked";
+        }
+        catch (error) {
+            // EXDEV on a rename INSIDE one directory looks impossible, and on
+            // overlayfs it is routine: a directory that came from a lower layer
+            // cannot be renamed at all, because the kernel would have to copy the
+            // whole tree up first, so it answers "cross-device link not permitted".
+            // The e2e image hits this exactly — `registry pull` writes library-md in
+            // one RUN and `registry materialize` swaps it in the next.
+            //
+            // So: delete instead of parking. Be clear about what that costs. From
+            // here until the rename below succeeds, `target` does not exist, and if
+            // that rename fails there is no parked copy to put back — the PREVIOUS
+            // tree is gone for good. The NEW tree is not: it is complete in
+            // `staging`, which is left in place on that failure and named in the
+            // error, so an operator can finish the move by hand. The alternative
+            // that keeps the old tree, copying it aside first, costs a second pass
+            // over 7,000 files inside a Docker build where nothing races the swap;
+            // the window is accepted there and only there. The atomic path stays the
+            // default everywhere a rename works.
+            if (error?.code !== "EXDEV")
+                throw error;
+            rmSync(target, { recursive: true, force: true });
+            parked = "deleted";
+        }
+    }
+    try {
+        renameSync(staging, target);
+    }
+    catch (error) {
+        // The new tree is deliberately NOT cleaned up here: it is the only copy
+        // when the overlayfs branch ran, and finishing the move by hand is the
+        // recovery. It is not ALWAYS there, though — the rename can fail because
+        // the staging tree itself went missing, which is what a second run sharing
+        // this output with the same pid does, the race the `.tmp-<pid>` naming
+        // already admits. Sending an operator after a directory that is not there
+        // costs them the time it takes to distrust the message.
+        let outcome;
+        if (parked === "parked") {
+            try {
+                renameSync(previous, target);
+                outcome = `the previous tree was put back at ${target}`;
+            }
+            catch {
+                outcome = `the previous tree could not be put back and is still parked at ${previous}`;
+            }
+        }
+        else if (parked === "deleted") {
+            outcome = "the previous tree was already deleted by the overlayfs fallback and is gone";
+        }
+        else {
+            outcome = "there was no previous tree";
+        }
+        const remains = existsSync(staging)
+            ? `the complete new tree is at ${staging}`
+            : `the new tree is NOT at ${staging} either, so this output has to be built again`;
+        throw new Error(`stageAndSwap: could not move ${staging} to ${target}: ${messageOf(error)}; ${outcome}, and ${remains}`, { cause: error });
+    }
+    if (parked === "parked")
+        rmSync(previous, { recursive: true, force: true });
+}
+/** Remove a directory tree if it exists, then create it empty. */
+export function resetDir(path) {
+    rmSync(path, { recursive: true, force: true });
+    mkdirSync(path, { recursive: true });
+}

package/dist/registry/generators/descriptors.d.ts

@@ -0,0 +1,81 @@
+import type { LoadedLibrary } from "../library-reader.js";
+import { type LookupSpecData, type LookupStrategy } from "../lookup-specs.js";
+import { type LibraryEntry, type LibraryField, type V1Definition } from "../model/library.js";
+import { NamedTypeRegistry } from "./type-registry.js";
+import { type TreeField, type TypeNode, type TypeTree } from "./type-tree.js";
+/** A field name is a valid identifier only if it has no dots, brackets, etc.; otherwise it is quoted. */
+export declare function keyLiteral(name: string): string;
+/** One sentence for a lookup field's own doc comment: what it sends, how to get one. */
+export declare function lookupFieldNote(declared: TreeField): string;
+/**
+ * One property line.
+ *
+ * An INPUT property is wrapped so it also accepts an expression, and a
+ * resolvable lookup additionally accepts an unresolved token. The wrapper goes
+ * here rather than on the leaf type so that `tags: input('tags')` — the whole
+ * collection as one expression — is legal alongside `tags: ['a', out(…)]`.
+ * An OUTPUT property is never wrapped: it came back from the connector.
+ */
+export declare function emitNestedProperty(name: string, node: TypeNode, indent: string, namedTypes: NamedTypeRegistry, allOptional: boolean, isInput?: boolean): string[];
+/** `export interface <name> { … }` over the roots of one tree. */
+export declare function emitInterface(name: string, allOptional: boolean, namedTypes: NamedTypeRegistry, fieldTree: TypeTree, isInput?: boolean): string[];
+export declare const STRATEGY_PROSE: Readonly<Record<LookupStrategy, string>>;
+/**
+ * The grep-able header: the lookups stated in prose beside the data, for agents
+ * that read source with Grep and have no language server. Bare ` * ` body
+ * lines, to be spliced inside a `/** … *\/` block.
+ */
+export declare function emitLookupComment(specs: ReadonlyMap<string, LookupSpecData>, symbol?: string): string[];
+/**
+ * The descriptor's `lookups:` literal — a RUNTIME value, not a type. `lookup()`
+ * reads `aliases` from it to build the `.byName()` family.
+ */
+export declare function emitLookupsBlock(specs: ReadonlyMap<string, LookupSpecData>): string[];
+/**
+ * A connector EVENT as a `triggerDescriptor()`, the shape `onEvent()` takes.
+ *
+ * The payload type comes from `outputSchema`, and `where` from the entry's
+ * event parameters. An entry that declares none keeps a loose
+ * `Record<string, string>`: that is either an event which genuinely takes no
+ * parameters (HTTP Webhook) or one nothing has described yet, and an empty
+ * interface would refuse every key in both cases.
+ */
+export declare function emitEvent(entry: LibraryEntry, inFields: readonly LibraryField[], inputTree: TypeTree, outputTree: TypeTree, name: string, inputTypes: NamedTypeRegistry, outputTypes: NamedTypeRegistry, invariant?: ReadonlySet<string>): string[];
+/** One operation: its `Inputs`/`Outputs` interfaces, doc comment and `descriptor()` const. */
+export declare function emitOp(entry: LibraryEntry, v1def: V1Definition, inputTree: TypeTree, outputTree: TypeTree, name: string, inputTypes: NamedTypeRegistry, outputTypes: NamedTypeRegistry, invariant?: ReadonlySet<string>): string[];
+/**
+ * The catalog names required inputs but the generated `Inputs` interface is
+ * empty: the descriptor would type-check a call the platform rejects. One line
+ * naming the operation and the fields, or `undefined` when there is no gap.
+ */
+export declare function requiredInputGap(entry: LibraryEntry, inputTree: TypeTree): string | undefined;
+export interface DescriptorOptions {
+    /** Module specifier for `import { descriptor }`; {@link PACKAGE_NAME} by default. */
+    importSpecifier?: string;
+    /** Connector keys to emit; every connector when omitted or empty. */
+    connectors?: readonly string[];
+    /**
+     * Emit typed descriptors for `GenericExpanded` entries (and every per-object
+     * variant of a generic event). Off for the bulk library; on for the small
+     * connection-resolved overlays `prepare` writes.
+     */
+    includeGenericExpanded?: boolean;
+}
+export interface DescriptorOutput {
+    /** `"<connector-key>.ts"` → module text, in emit order (connector keys sorted by code point). */
+    modules: Map<string, string>;
+    /** nodeType → exported const name, from `naming.symbolIndex`, for the whole index. */
+    symbols: Map<string, string>;
+    /** One line per operation whose catalog requires inputs its interface cannot carry. */
+    requiredInputGaps: string[];
+}
+/**
+ * Render every connector module of the library.
+ *
+ * The Python `main()` wrote every module and only then exited 1 on
+ * {@link DescriptorOutput.requiredInputGaps}; this returns both and the caller
+ * decides. A missing entry or sidecar throws, as the Python did.
+ */
+export declare function renderDescriptorModules(library: LoadedLibrary, options?: DescriptorOptions): DescriptorOutput;
+/** The text the Python printed before exiting 1 on gaps; call only with a non-empty list. */
+export declare function formatRequiredInputGaps(gaps: readonly string[]): string;

package/dist/registry/generators/descriptors.js

@@ -0,0 +1,405 @@
+/**
+ * Statically-typed connector descriptor modules from the canonical JSON library.
+ *
+ * For every Curated and HTTP-request operation, one `descriptor<Inputs,
+ * Outputs>()` const plus its `Inputs`/`Outputs` interfaces; for every connector
+ * EVENT, a `triggerDescriptor<Where, Outputs>()` const. Grouped one module per
+ * connector, `connectors/<connector-key>.ts`. Authored flows import the exported
+ * consts by name, so the module text is an API contract: it is byte-for-byte
+ * what `generate_connectors_ts.py` wrote. The differential that proved that
+ * ran while the Python was in the tree and was deleted with it, so
+ * `tests/registry-descriptors.test.ts` is now the description of the text.
+ *
+ * Inputs are the union of the sidecar's body fields and the entry's query/path/
+ * file-multipart parameters (see `fields.ts`); dotted and wildcard names are
+ * rebuilt as nested objects and arrays (`type-tree.ts`) and named once per
+ * connector (`type-registry.ts`). Outputs come from `outputSchema.fields`.
+ * `GenericExpanded` operations are skipped unless asked for, and a generic
+ * event's per-object variants are skipped because they share their template's
+ * node type and so would emit the same const twice.
+ */
+import { PACKAGE_NAME } from "../../package-name.js";
+import { pyJsonString, pyJsonStringify } from "../codecs/pyjson.js";
+import { sortedByCodePoint, sortedStrings } from "../compat/compare.js";
+import { afterLast, pyRstrip, pyStr, pyStrip, splitOnce } from "../compat/pystr.js";
+import { referenceOf, specsFromFields } from "../lookup-specs.js";
+import { isEventNodeType, } from "../model/library.js";
+import { symbolIndex } from "../naming.js";
+import { descriptorInputFields, lookupSpecs, markLookupFields } from "./fields.js";
+import { NamedTypeRegistry } from "./type-registry.js";
+import { buildTypeTree, pyTruthy, subtreeRequired } from "./type-tree.js";
+/** `str(value or "")`. */
+function strOrEmpty(value) {
+    return pyTruthy(value) ? pyStr(value) : "";
+}
+/** A field name is a valid identifier only if it has no dots, brackets, etc.; otherwise it is quoted. */
+export function keyLiteral(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : pyJsonString(name);
+}
+/** One sentence for a lookup field's own doc comment: what it sends, how to get one. */
+export function lookupFieldNote(declared) {
+    const reference = referenceOf(declared) ?? {};
+    const target = pyStr(pyTruthy(reference.objectName) ? reference.objectName : splitOnce(strOrEmpty(reference.path), "?")[0]);
+    const value = pyStr(pyTruthy(reference.lookupValue) ? reference.lookupValue : "id");
+    const field = strOrEmpty(declared.name);
+    return (`LOOKUP — sends a \`${target}.${value}\`, never a name or e-mail: ` +
+        `lookup(<Descriptor>, '${field}') (helpers in the LOOKUP lines above the descriptor).`);
+}
+/**
+ * One property line.
+ *
+ * An INPUT property is wrapped so it also accepts an expression, and a
+ * resolvable lookup additionally accepts an unresolved token. The wrapper goes
+ * here rather than on the leaf type so that `tags: input('tags')` — the whole
+ * collection as one expression — is legal alongside `tags: ['a', out(…)]`.
+ * An OUTPUT property is never wrapped: it came back from the connector.
+ */
+export function emitNestedProperty(name, node, indent, namedTypes, allOptional, isInput = false) {
+    const lines = [];
+    const declared = node.declared ?? {};
+    let desc = pyStrip(strOrEmpty(declared.description)).replaceAll("\n", " ");
+    if (isInput && pyTruthy(declared.__lookup)) {
+        // The identity goes ON the field, not only in the LOOKUP block above the
+        // descriptor: "The reporter of the issue" beside `ConnectorLookupValue<string>`
+        // read as "any string", and an e-mail went into `fields.reporter.id`.
+        desc = pyStrip(`${desc} ${lookupFieldNote(declared)}`);
+    }
+    if (desc)
+        lines.push(`${indent}/** ${desc} */`);
+    const optional = allOptional || !subtreeRequired(node) ? "?" : "";
+    let rendered = namedTypes.typeFor(name, node);
+    if (isInput) {
+        const wrapper = pyTruthy(declared.__lookup) ? "ConnectorLookupValue" : "ConnectorValue";
+        rendered = `${wrapper}<${rendered}>`;
+    }
+    lines.push(`${indent}${keyLiteral(name)}${optional}: ${rendered};`);
+    return lines;
+}
+/** `export interface <name> { … }` over the roots of one tree. */
+export function emitInterface(name, allOptional, namedTypes, fieldTree, isInput = false) {
+    const out = [`export interface ${name} {`];
+    for (const [fieldName, node] of fieldTree) {
+        out.push(...emitNestedProperty(fieldName, node, "  ", namedTypes, allOptional, isInput));
+    }
+    out.push("}");
+    return out;
+}
+export const STRATEGY_PROSE = {
+    filter: "one request (the operation declares a server-side filter)",
+    scan: "paged scan (this operation declares no filterPattern)",
+    tree: "hierarchical walk (the collection is a tree)",
+    dependent: "dependent — another field must resolve first",
+};
+/**
+ * The grep-able header: the lookups stated in prose beside the data, for agents
+ * that read source with Grep and have no language server. Bare ` * ` body
+ * lines, to be spliced inside a `/** … *\/` block.
+ */
+export function emitLookupComment(specs, symbol = "<Descriptor>") {
+    const lines = [];
+    for (const [field, spec] of specs) {
+        const target = splitOnce(pyStr(pyTruthy(spec.objectName) ? spec.objectName : spec.path), "?")[0];
+        lines.push(` * LOOKUP: \`${field}\` -> ${target}.${spec.value}`);
+        const aliases = spec.aliases;
+        const offered = aliases.size > 0 ? [...aliases.values()].map((a) => `${a}()`) : [];
+        const byList = spec.by.map((n) => `\`${n}\``).join(", ");
+        lines.push(` *   by: ${byList}`);
+        // THE WHOLE CALL, not just the method names: naming `.byEmail` without the
+        // `lookup(Descriptor, 'field')` wrapper says helpers exist but not how to
+        // reach one.
+        const first = aliases.size > 0 ? [...aliases.values()][0] : undefined;
+        const call = first
+            ? `lookup(${symbol}, '${field}').${first}(value)`
+            : spec.by.length > 0
+                ? `lookup(${symbol}, '${field}').by('${spec.by[0]}', value)`
+                : `lookup(${symbol}, '${field}')`;
+        lines.push(` *   use: ${call}`);
+        if (offered.length > 0) {
+            lines.push(` *   also: ${[...aliases.values()].map((a) => `.${a}`).join(", ")}  ·  .by(name, value)`);
+        }
+        else {
+            lines.push(" *   also: .by(name, value) only — aliases collided");
+        }
+        lines.push(` *   strategy: ${STRATEGY_PROSE[spec.strategy]}`);
+        if (spec.dependsOn && spec.dependsOn.length > 0) {
+            lines.push(` *   resolve first: ${spec.dependsOn.map((d) => `\`${d}\``).join(", ")}`);
+        }
+    }
+    return lines;
+}
+/**
+ * The descriptor's `lookups:` literal — a RUNTIME value, not a type. `lookup()`
+ * reads `aliases` from it to build the `.byName()` family.
+ */
+export function emitLookupsBlock(specs) {
+    if (specs.size === 0)
+        return [];
+    const lines = ["  lookups: {"];
+    for (const [field, spec] of specs) {
+        lines.push(`    ${keyLiteral(field)}: {`);
+        if (pyTruthy(spec.objectName))
+            lines.push(`      objectName: ${pyJsonString(spec.objectName)},`);
+        lines.push(`      path: ${pyJsonStringify(spec.path)},`);
+        lines.push(`      by: ${pyJsonStringify(spec.by)},`);
+        lines.push(`      value: ${pyJsonString(spec.value)},`);
+        const aliases = [...spec.aliases].map(([name, alias]) => `${alias}: ${pyJsonString(name)}`).join(", ");
+        lines.push(`      aliases: {${aliases ? ` ${aliases} ` : ""}},`);
+        lines.push(`      strategy: ${pyJsonString(spec.strategy)},`);
+        if (spec.dependsOn && spec.dependsOn.length > 0)
+            lines.push(`      dependsOn: ${pyJsonStringify(spec.dependsOn)},`);
+        lines.push("    },");
+    }
+    lines.push("  },");
+    return lines;
+}
+/** `entry.get("version", "1.0.0")`: the key's value when present, even `null`. */
+function versionOf(entry) {
+    return "version" in entry ? entry.version : "1.0.0";
+}
+/**
+ * A connector EVENT as a `triggerDescriptor()`, the shape `onEvent()` takes.
+ *
+ * The payload type comes from `outputSchema`, and `where` from the entry's
+ * event parameters. An entry that declares none keeps a loose
+ * `Record<string, string>`: that is either an event which genuinely takes no
+ * parameters (HTTP Webhook) or one nothing has described yet, and an empty
+ * interface would refuse every key in both cases.
+ */
+export function emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant = new Set()) {
+    const nodeType = entry.nodeType;
+    const eventId = afterLast(nodeType, ".");
+    const connectorKey = pyTruthy(entry.connector?.key) ? entry.connector.key : "";
+    const label = pyTruthy(entry.display?.label) ? entry.display.label : eventId;
+    const version = versionOf(entry);
+    const generic = entry.operation?.activityType === "GenericTrigger";
+    const lines = [];
+    let whereType = "Record<string, string>";
+    if (inFields.length > 0) {
+        whereType = `${name}Where`;
+        lines.push(...emitInterface(whereType, false, inputTypes, inputTree, true));
+        lines.push("");
+    }
+    lines.push(...emitInterface(`${name}Outputs`, true, outputTypes, outputTree));
+    lines.push("");
+    // A subscription's `where` values are resolved by `lookup()` exactly as a
+    // connector input's are, so the descriptor carries the same specs.
+    const specs = specsFromFields(inFields, invariant);
+    lines.push("/**");
+    lines.push(` * ${pyStr(label)} — ${nodeType}`);
+    lines.push(" *");
+    if (generic) {
+        lines.push(" * A GENERIC event: it fires for ONE object of the connection (an entity, a");
+        lines.push(` * table, a custom object), so name it — \`onEvent(${name}, { object: '<Object>' })\`.`);
+        lines.push(` * \`uip is triggers objects ${pyStr(connectorKey)} <EVENT> --connection-id <id>\` lists them.`);
+    }
+    else {
+        lines.push(` * Start a flow on it with \`onEvent(${name}, { where: { … } })\`, or pause for it`);
+        lines.push(` * with \`waitForEvent(${name}, { … })\`; \`where\` carries its event parameters.`);
+    }
+    // INSIDE the block: `emitLookupComment` returns bare ` * ` body lines.
+    if (specs.size > 0) {
+        lines.push(" *");
+        lines.push(...emitLookupComment(specs, name));
+    }
+    lines.push(" */");
+    lines.push(`export const ${name} = triggerDescriptor<${whereType}, ${name}Outputs>()({`);
+    lines.push(`  connector: ${pyJsonStringify(connectorKey)},`);
+    lines.push(`  event: ${pyJsonString(eventId)},`);
+    lines.push(`  version: ${pyJsonStringify(version)},`);
+    lines.push(`  displayName: ${pyJsonStringify(label)},`);
+    lines.push(...emitLookupsBlock(specs));
+    lines.push("} as const);");
+    return lines;
+}
+/** One operation: its `Inputs`/`Outputs` interfaces, doc comment and `descriptor()` const. */
+export function emitOp(entry, v1def, inputTree, outputTree, name, inputTypes, outputTypes, invariant = new Set()) {
+    const nodeType = entry.nodeType;
+    const actionId = afterLast(nodeType, ".");
+    const operation = entry.operation ?? {};
+    const isGenericExpanded = operation.activityType === "GenericExpanded";
+    const label = pyTruthy(entry.display?.label) ? entry.display.label : actionId;
+    const version = versionOf(entry);
+    const runtime = entry.runtime ?? {};
+    const inFields = descriptorInputFields(entry, v1def);
+    if (isEventNodeType(nodeType)) {
+        return emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant);
+    }
+    const lines = [];
+    lines.push(...emitInterface(`${name}Inputs`, false, inputTypes, inputTree, true));
+    lines.push("");
+    lines.push(...emitInterface(`${name}Outputs`, true, outputTypes, outputTree));
+    lines.push("");
+    // An operation whose real field set arrives at design time has an `Inputs`
+    // type that is either empty (no object chosen yet) or just the parents. The
+    // doc comment is the only place the typed surface can say so.
+    const schemaAction = operation.schemaAction ?? {};
+    const specs = lookupSpecs(entry, v1def, invariant);
+    const lookupComment = specs.size > 0 ? emitLookupComment(specs, name) : [];
+    const header = ` * ${pyStr(label)} — ${nodeType}`;
+    if (pyTruthy(operation.objectFromDiscovery)) {
+        lines.push("/**");
+        lines.push(header);
+        lines.push(" *");
+        lines.push(" * The object is chosen against the connection, so `Inputs` is empty");
+        lines.push(" * here. List the objects and read the chosen one's fields with");
+        lines.push(" * `uip is resources list` / `describe` before binding this node.");
+        if (lookupComment.length > 0) {
+            lines.push(" *");
+            lines.push(...lookupComment);
+        }
+        lines.push(" */");
+    }
+    else if (pyTruthy(schemaAction.parents)) {
+        const parents = schemaAction.parents.map((x) => `\`${pyStr(x)}\``).join(", ");
+        lines.push("/**");
+        lines.push(header);
+        lines.push(" *");
+        lines.push(` * \`Inputs\` carries only the fields that SELECT the schema (${parents}).`);
+        lines.push(` * The real set comes from the \`${pyStr(schemaAction.name)}\` design-time`);
+        lines.push(" * action — describe with those values supplied to see it.");
+        if (lookupComment.length > 0) {
+            lines.push(" *");
+            lines.push(...lookupComment);
+        }
+        lines.push(" */");
+    }
+    else if (lookupComment.length > 0) {
+        lines.push("/**");
+        lines.push(header);
+        lines.push(" *");
+        lines.push(...lookupComment);
+        lines.push(" */");
+    }
+    else {
+        lines.push(`/** ${pyStr(label)} — ${nodeType} */`);
+    }
+    lines.push(`export const ${name} = descriptor<${name}Inputs, ${name}Outputs>()({`);
+    lines.push(`  nodeType: ${pyJsonString(nodeType)},`);
+    lines.push(`  version: ${pyJsonStringify(version)},`);
+    if (isGenericExpanded && pyTruthy(operation.objectName)) {
+        lines.push(`  objectName: ${pyJsonStringify(operation.objectName)},`);
+    }
+    if (pyTruthy(runtime.requiresConnection))
+        lines.push("  requiresConnection: true,");
+    if (pyTruthy(runtime.requiresFolderKey))
+        lines.push("  requiresFolderKey: true,");
+    lines.push(...emitLookupsBlock(specs));
+    lines.push("} as const);");
+    return lines;
+}
+/**
+ * The catalog names required inputs but the generated `Inputs` interface is
+ * empty: the descriptor would type-check a call the platform rejects. One line
+ * naming the operation and the fields, or `undefined` when there is no gap.
+ */
+export function requiredInputGap(entry, inputTree) {
+    const required = (entry.inputSchema?.fields || [])
+        .filter((field) => field.required === true)
+        .map((field) => pyStr(pyTruthy(field.name) ? field.name : "<unnamed>"));
+    if (required.length === 0 || inputTree.size > 0)
+        return undefined;
+    const nodeType = "nodeType" in entry ? pyStr(entry.nodeType) : "<unknown node>";
+    return `${nodeType}: catalog requires ${required.join(", ")}, but the generated inputs interface is empty`;
+}
+/**
+ * `mark_lookup_fields`: flag the fields whose TypeScript type must also accept
+ * a `LookupToken` — exactly the set `lookupSpecs` generates helpers for. The
+ * work is `fields.ts`'s `markLookupFields`, which also merges the catalog's
+ * `reference` INTO a field whose own declaration lacks one, as the Python did;
+ * `lookupFieldNote` reads the lookup's target and value from that merged
+ * reference, so the doc comment on the field depends on the merge. This
+ * wrapper only narrows the result to the tree's field type.
+ */
+function markedInputFields(entry, fields, invariant) {
+    return markLookupFields(entry, fields, invariant);
+}
+/**
+ * Render every connector module of the library.
+ *
+ * The Python `main()` wrote every module and only then exited 1 on
+ * {@link DescriptorOutput.requiredInputGaps}; this returns both and the caller
+ * decides. A missing entry or sidecar throws, as the Python did.
+ */
+export function renderDescriptorModules(library, options = {}) {
+    const importSpecifier = options.importSpecifier ?? PACKAGE_NAME;
+    const includeGenericExpanded = options.includeGenericExpanded ?? false;
+    const subset = new Set((options.connectors ?? []).filter((c) => c.length > 0));
+    const invariant = library.invariant;
+    const rows = library.index.entries;
+    // Group Curated + http-request entries by connector key.
+    const byConnector = new Map();
+    for (const row of rows) {
+        if (row.activityType === "GenericExpanded" && !includeGenericExpanded)
+            continue;
+        // A generic EVENT's per-object variants share their template's nodeType and
+        // so would emit the same const twice. Only the template gets a descriptor:
+        // `onEvent(RecordCreated, { object: 'Message' })` names the object as an
+        // option, so one descriptor serves every object.
+        if (row.activityType === "GenericTrigger" && pyTruthy(row.objectName) && !includeGenericExpanded)
+            continue;
+        const key = row.connectorKey;
+        if (subset.size > 0 && !subset.has(key))
+            continue;
+        const group = byConnector.get(key);
+        if (group)
+            group.push(row);
+        else
+            byConnector.set(key, [row]);
+    }
+    // ONE symbol map for the whole run, shared with the Markdown generator.
+    const symbols = symbolIndex(rows, includeGenericExpanded);
+    const modules = new Map();
+    const requiredInputGaps = [];
+    for (const key of sortedStrings(byConnector.keys())) {
+        const inputTypes = new NamedTypeRegistry({ suffix: "Input", allOptional: false, mergeReused: false, isInput: true });
+        const outputTypes = new NamedTypeRegistry();
+        const loaded = [];
+        for (const row of sortedByCodePoint(byConnector.get(key), (r) => r.nodeType)) {
+            const entry = library.readEntry(row);
+            if (entry === undefined)
+                throw new Error(`library entry missing: ${library.entryPath(row)}`);
+            const v1def = library.readV1Def(row);
+            if (v1def === undefined)
+                throw new Error(`library sidecar missing: ${library.v1defPath(row)}`);
+            const isEvent = isEventNodeType(row.nodeType);
+            const operationInputFields = markedInputFields(entry, descriptorInputFields(entry, v1def), invariant);
+            const outputFields = entry.outputSchema?.fields || [];
+            const inputTree = buildTypeTree(operationInputFields);
+            // The required-input gap is a statement about a connector ACTION's
+            // inputs; an event's parameters are optional by construction.
+            const gap = isEvent ? undefined : requiredInputGap(entry, inputTree);
+            if (gap)
+                requiredInputGaps.push(gap);
+            const outputTree = buildTypeTree(outputFields);
+            inputTypes.discover(inputTree);
+            outputTypes.discover(outputTree);
+            loaded.push({ entry, v1def, inputTree, outputTree });
+        }
+        const operations = [];
+        for (const { entry, v1def, inputTree, outputTree } of loaded) {
+            const name = symbols.get(entry.nodeType);
+            if (name === undefined)
+                throw new Error(`no symbol for ${entry.nodeType}: the entry's nodeType is not in index.json`);
+            operations.push(...emitOp(entry, v1def, inputTree, outputTree, name, inputTypes, outputTypes, invariant), "");
+        }
+        const emittedTypes = inputTypes.emit(emitNestedProperty);
+        const rendered = [...emittedTypes, ...operations].join("\n");
+        let specifiers = ["descriptor", "triggerDescriptor"].filter((s) => rendered.includes(`= ${s}<`));
+        if (specifiers.length === 0)
+            specifiers = ["descriptor"];
+        for (const alias of ["ConnectorLookupValue", "ConnectorValue"]) {
+            if (rendered.includes(alias))
+                specifiers.push(`type ${alias}`);
+        }
+        const body = [`import { ${specifiers.join(", ")} } from ${pyJsonString(importSpecifier)};`, ""];
+        body.push(...emittedTypes);
+        body.push(...outputTypes.emit(emitNestedProperty));
+        body.push(...operations);
+        modules.set(`${key}.ts`, `${pyRstrip(body.join("\n"))}\n`);
+    }
+    return { modules, symbols, requiredInputGaps };
+}
+/** The text the Python printed before exiting 1 on gaps; call only with a non-empty list. */
+export function formatRequiredInputGaps(gaps) {
+    return `connector wrapper generation stopped:\n- ${gaps.join("\n- ")}`;
+}