@uipath/maestro-builder-sdk 6.3.0 → 6.5.0

package/dist/registry/generators/markdown/sections/example.js

@@ -0,0 +1,295 @@
+/**
+ * `## Example`: a compilable `connector(...)` call — or, for an event, an
+ * `onEvent(...)` / `waitForEvent(...)` call — for the operation.
+ *
+ * Required inputs only, nested the way the descriptor's `Inputs` type is
+ * nested, with the import path DERIVED: a schema-dynamic operation's
+ * descriptor lives in `./connectors-local/` after a `prepare`. When a
+ * descriptor exists the example is type-checked against its `Inputs`, so the
+ * required set is the descriptor generator's, not this module's; the two
+ * vocabularies disagree about required-ness on most operations, and that
+ * disagreement is pre-existing. Ported from `example_lines`,
+ * `event_example_lines`, `nest_inputs`, `example_value`, `leaf_name` and
+ * `pascal_step`.
+ */
+import { PACKAGE_NAME } from "../../../../package-name.js";
+import { pyJsonString } from "../../../codecs/pyjson.js";
+import { sortedStrings } from "../../../compat/compare.js";
+import { afterLast, pyStr, upperFirst } from "../../../compat/pystr.js";
+import { classify, referenceOf } from "../../../lookup-specs.js";
+import { isEventNodeType, TRIGGER_PREFIX } from "../../../model/library.js";
+import { byAliases } from "../../../naming.js";
+import { descriptorInputFields, markLookupFields } from "../../fields.js";
+import { authoringField, enumValue } from "../common.js";
+import { dictOf, firstValue, getStr, IDENT, listOf, pyFloatAccepts, pyOr, pyTruthy, strList, } from "../pyvalue.js";
+/** `fields.project.key` → `projectKey`: a readable input name, not a path. */
+export function leafName(fieldName) {
+    const parts = fieldName.replaceAll("[*]", "").split(".").filter((p) => p);
+    if (!parts.length)
+        return "value";
+    if (parts.length === 1)
+        return parts[0];
+    const [head, ...rest] = parts.slice(-2);
+    return head + rest.map(upperFirst).join("");
+}
+/** `send-message-to-user` → `sendMessageToUser`, a usable step name. */
+export function pascalStep(action) {
+    const words = action.replaceAll("_", "-").split("-").filter((w) => w);
+    if (!words.length)
+        return "step";
+    const [head, ...rest] = words;
+    return head + rest.map(upperFirst).join("");
+}
+/**
+ * One level of the example's input literal. A segment can be BOTH an array
+ * and an object (`contacts[*].name` is a list of objects), so array-ness is a
+ * flag on the node. `children` is insertion-ordered, like the Python dict.
+ */
+class Node {
+    children = new Map();
+    isArray = false;
+    leaf;
+}
+/** Render `[name, value]` pairs as the nested object literal an author writes. */
+export function nestInputs(pairs) {
+    const root = new Node();
+    for (const [name, value] of pairs) {
+        let node = root;
+        for (const segment of pyStr(name).split(".").filter((p) => p)) {
+            const isArray = segment.endsWith("[*]");
+            const key = isArray ? segment.slice(0, -3) : segment;
+            let child = node.children.get(key);
+            if (child === undefined) {
+                child = new Node();
+                node.children.set(key, child);
+            }
+            child.isArray = child.isArray || isArray;
+            node = child;
+        }
+        node.leaf = value;
+    }
+    const render = (node, indent) => {
+        const pad = "  ".repeat(indent);
+        const lines = [];
+        for (const [key, child] of node.children) {
+            const safe = IDENT.test(key) ? key : pyJsonString(key);
+            if (child.children.size) {
+                const [openBrace, closeBrace] = child.isArray ? ["[{", "}],"] : ["{", "},"];
+                lines.push(`${pad}${safe}: ${openBrace}`);
+                lines.push(...render(child, indent + 1));
+                lines.push(`${pad}${closeBrace}`);
+            }
+            else {
+                const value = child.leaf !== undefined ? child.leaf : "undefined";
+                lines.push(child.isArray ? `${pad}${safe}: [${value}],` : `${pad}${safe}: ${value},`);
+            }
+        }
+        return lines;
+    };
+    return render(root, 1);
+}
+/**
+ * The value to show for one required input: a resolvable lookup shows its
+ * helper; an enum shows its FIRST DECLARED CHOICE, typed to the declaration
+ * where it can be; anything else shows `input('<name>')`.
+ */
+export function exampleValue(f, symbol, invariant, connectorKey = "", action = "") {
+    const [name] = authoringField(f);
+    // The lookup table is keyed by the WIRE name (`addLabelIds[*]`), which is
+    // what `--resolve` and `buildConnectorInputs` both match on.
+    const wire = pyStr(pyOr(f.name, name));
+    const kind = classify(f, invariant);
+    if (kind === "lookup") {
+        const reference = referenceOf(f);
+        const names = strList(reference.lookupNames);
+        const aliases = byAliases(names);
+        const first = names.length ? names[0] : "id";
+        if (symbol) {
+            if (aliases.size)
+                return `lookup(${symbol}, '${wire}').${firstValue(aliases)}('…')`;
+            return `lookup(${symbol}, '${wire}').by('${first}', '…')`;
+        }
+        // NO DESCRIPTOR — a Generic CRUD expansion: the string form, generic `.by` only.
+        return `lookup('${connectorKey}', '${action}', '${wire}').by('${first}', '…')`;
+    }
+    const type = getStr(f, "type", "").toLowerCase();
+    const enumeration = f.enum;
+    if (pyTruthy(enumeration)) {
+        // The choice list is strings even when the field is not; fall back rather
+        // than emit something that does not compile.
+        const choice = enumValue(listOf(enumeration)[0]);
+        if (type === "boolean" || type === "bool") {
+            const lowered = choice.toLowerCase();
+            if (lowered === "true" || lowered === "false")
+                return lowered;
+        }
+        else if (type === "number" || type === "integer" || type === "float" || type === "double" || type === "long") {
+            if (pyFloatAccepts(choice))
+                return choice;
+        }
+        else {
+            return pyJsonString(choice);
+        }
+    }
+    return `input('${leafName(name)}')`;
+}
+/** A compilable `connector(...)` call for this operation; events go to {@link eventExampleLines}. */
+export function exampleLines(j, fields, symbol, invariant, v1def) {
+    const connectorKey = pyStr(pyOr(dictOf(j.connector).key, "<connector>"));
+    const operation = dictOf(j.operation);
+    const runtime = dictOf(j.runtime);
+    const nodeType = pyStr(pyOr(j.nodeType, ""));
+    const action = afterLast(nodeType, ".");
+    const step = pascalStep(action);
+    if (isEventNodeType(nodeType))
+        return eventExampleLines(j, symbol, connectorKey, action, step, v1def);
+    // WHICH REQUIRED SET: the descriptor's `Inputs` when a descriptor exists,
+    // marked with the SAME call the descriptor generator uses; else this
+    // module's own vocabulary, which the string form cannot fail on.
+    let exampleFields;
+    if (symbol) {
+        const entry = j;
+        const raw = (v1def ?? {});
+        // Marked with the SAME call the descriptor generator uses — it also merges
+        // the catalog's `reference` into a field whose authoring vocabulary lacks
+        // one — so the example puts a helper on exactly the fields that have one.
+        exampleFields = markLookupFields(entry, descriptorInputFields(entry, raw), invariant);
+    }
+    else {
+        exampleFields = fields;
+    }
+    const required = exampleFields.filter((f) => pyTruthy(f.required));
+    const schemaDynamic = pyTruthy(operation.objectFromDiscovery) ||
+        pyTruthy(dictOf(operation.schemaAction).parents) ||
+        pyTruthy(runtime.requiresConnectionForSchema);
+    const out = ["## Example", ""];
+    const pairs = required.map((f) => {
+        const [name, , wireName] = authoringField(f);
+        return [wireName ? f.name : name, exampleValue(f, symbol, invariant, connectorKey, action)];
+    });
+    // Import exactly what the rendered body uses.
+    const bodyUses = new Set(["connector"]);
+    if (pairs.some(([, v]) => v.includes("lookup(")))
+        bodyUses.add("lookup");
+    if (pairs.some(([, v]) => v.includes("input(")))
+        bodyUses.add("input");
+    const imported = sortedStrings(bodyUses).join(", ");
+    out.push("```ts");
+    // THE PACKAGE, not a relative path.
+    out.push(`import { ${imported} } from '${PACKAGE_NAME}';`);
+    let head;
+    if (symbol) {
+        const directory = schemaDynamic ? "connectors-local" : "connectors";
+        out.push(`import { ${symbol} } from './${directory}/${connectorKey}.ts';`);
+        out.push("");
+        head = `.step('${step}', connector(${symbol}, {`;
+    }
+    else {
+        out.push("");
+        head = `.step('${step}', connector('${connectorKey}', '${action}', {`;
+    }
+    out.push(head);
+    if (pairs.length)
+        out.push(...nestInputs(pairs));
+    const opts = [];
+    if (pyTruthy(runtime.requiresConnection))
+        opts.push(`connection: '${afterLast(connectorKey, "-")}'`);
+    if (pyTruthy(runtime.requiresFolderKey))
+        opts.push("folder: 'shared'");
+    if (!symbol && (operation.activityType === "Generic" || operation.activityType === "GenericExpanded")) {
+        opts.push(`object: '${pyStr(pyOr(operation.objectName, "<object>"))}'`);
+    }
+    const tail = "}" + (opts.length ? `, { ${opts.join(", ")} }` : "") + "))";
+    out.push(tail);
+    out.push("```");
+    out.push("");
+    if (schemaDynamic && symbol) {
+        // ONE ordering per page: the import fact stays; authoring comes first.
+        if (pyTruthy(operation.objectFromDiscovery)) {
+            out.push("The descriptor comes from `./connectors-local/` and this " +
+                "import resolves only after " +
+                `\`npx flow-sdk registry prepare ${connectorKey} ${action} ` +
+                "--object <name>` runs. That never blocks authoring: write " +
+                "the step first with the string form and " +
+                "`{ object: '<name-as-the-task-said-it>' }` — `check` " +
+                "names this exact prepare — then switch to this import.");
+        }
+        else {
+            out.push("The descriptor comes from `./connectors-local/` and this " +
+                "import resolves only after " +
+                `\`npx flow-sdk registry prepare ${connectorKey} ${action}\` ` +
+                "runs. That never blocks authoring: the fields in this " +
+                "catalog are authorable immediately, and `check` flags any " +
+                "input outside them with this same command.");
+        }
+        out.push("");
+    }
+    return out;
+}
+/**
+ * A compilable `onEvent(...)` / `waitForEvent(...)` call for a connector
+ * EVENT. A GENERIC event (`GenericTrigger`) watches ONE object the entry does
+ * not name, so the example shows the `object` option; a curated event shows
+ * `where` with the sidecar's event parameters.
+ */
+export function eventExampleLines(j, symbol, connectorKey, action, step, v1def) {
+    const operation = dictOf(j.operation);
+    const generic = operation.activityType === "GenericTrigger";
+    const start = getStr(j, "nodeType", "").startsWith(TRIGGER_PREFIX);
+    // The SIDECAR's event parameters: the raw input definition's names are not
+    // even legal object keys. No parameters, no `where`.
+    const params = listOf(pyOr(dictOf(pyOr(dictOf(v1def).eventParameters, {})).fields, []))
+        .map(dictOf)
+        .filter((f) => typeof f.name === "string" && !pyTruthy(f.hidden))
+        .map((f) => f.name);
+    const factory = start ? "onEvent" : "waitForEvent";
+    const out = ["## Example", "", "```ts"];
+    out.push(`import { ${factory} } from '${PACKAGE_NAME}';`);
+    if (symbol)
+        out.push(`import { ${symbol} } from './connectors/${connectorKey}.ts';`);
+    out.push("");
+    const opts = [];
+    let whereLines = [];
+    if (generic)
+        opts.push("object: '<Object>'");
+    else if (params.length) {
+        // NESTED, exactly as inputs are: the generated `…Where` interface splits a
+        // dotted parameter into an object (`channelData.channel.id` becomes
+        // `channelData: ConnectorValue<ChannelDataInput>`), so a flat key — quoted
+        // or not — is not a member of the type. Unnested, Teams'
+        // `channelData.channel.id` made the only two event examples in the library
+        // the only `## Example` fences in ~8,000 that did not parse.
+        whereLines = nestInputs(params.map((p) => [p, `'<${p}>'`])).map((line) => `  ${line}`);
+    }
+    opts.push(`connection: '${afterLast(connectorKey, "-")}'`);
+    opts.push("folder: 'shared'");
+    const lead = symbol
+        ? `${factory}(${symbol}, {`
+        : `${factory}({ connector: '${connectorKey}', event: '${action}',`;
+    if (whereLines.length > 0) {
+        // Multi-line, like the action example, because the nested `where` is.
+        out.push(start ? `.trigger(${lead}` : `.step('${step}', ${lead}`);
+        out.push("  where: {");
+        out.push(...whereLines);
+        out.push("  },");
+        for (const option of opts)
+            out.push(`  ${option},`);
+        out.push("}))");
+    }
+    else {
+        const call = symbol
+            ? `${factory}(${symbol}, { ${opts.join(", ")} })`
+            : `${factory}({ connector: '${connectorKey}', event: '${action}', ${opts.join(", ")} })`;
+        out.push(start ? `.trigger(${call})` : `.step('${step}', ${call})`);
+    }
+    out.push("```");
+    out.push("");
+    if (generic) {
+        out.push("A GENERIC event: it fires for ONE object of the connection, so `object` " +
+            `names it. \`uip is triggers objects ${connectorKey} ` +
+            `${pyStr(pyOr(operation.eventOperation, operation.name, "<EVENT>"))} ` +
+            "--connection-id <id>` lists the objects the bound connection exposes.");
+        out.push("");
+    }
+    return out;
+}

package/dist/registry/generators/markdown/sections/filtering.d.ts

@@ -0,0 +1,2 @@
+import { type Dict } from "../pyvalue.js";
+export declare function eventFilterLines(j: Dict, v1def: Dict | undefined): string[];

package/dist/registry/generators/markdown/sections/filtering.js

@@ -0,0 +1,76 @@
+/**
+ * `## Filtering`: the fields a subscription may filter on, and how complete
+ * that list is. Two sources, matching how the platform builds each list and
+ * what `Library.eventFilterFields` reads: a CURATED event filters on the
+ * fields its definition marks (`v1def.filterFields`); a GENERIC event filters
+ * on every field the object supports GET on (the entry's `outputSchema`).
+ * Ported from `event_filter_lines`.
+ */
+import { pyStr } from "../../../compat/pystr.js";
+import { isEventNodeType } from "../../../model/library.js";
+import { dictOf, getStr, listOf, pyOr, pyTruthy } from "../pyvalue.js";
+export function eventFilterLines(j, v1def) {
+    const nodeType = getStr(j, "nodeType", "");
+    if (!isEventNodeType(nodeType))
+        return [];
+    const generic = dictOf(j.operation).activityType === "GenericTrigger";
+    const fields = [...listOf(pyOr(dictOf(pyOr(dictOf(v1def).filterFields, {})).fields, []))];
+    if (generic)
+        fields.push(...listOf(pyOr(dictOf(j.outputSchema).fields, [])));
+    const names = [];
+    for (const raw of fields) {
+        const name = dictOf(raw).name;
+        if (typeof name === "string" && name && !names.includes(name))
+            names.push(name);
+    }
+    if (!names.length)
+        return [];
+    const selectors = listOf(pyOr(dictOf(pyOr(dictOf(v1def).eventParameters, {})).fields, []))
+        .map(dictOf)
+        .filter((f) => pyTruthy(f.required) && (f.bucket === "query" || f.bucket === "path"))
+        .map((f) => pyStr(f.name));
+    const out = ["## Filtering", ""];
+    out.push("Narrow which records fire the subscription with `filters`. Each leaf is " +
+        "`{ field, <operator>: value }` with exactly ONE operator " +
+        "(`contains`, `startsWith`, `endsWith`, `equals`, `notEquals`, " +
+        "`lessThan`, `lessThanOrEqual`, `greaterThan`, `greaterThanOrEqual`):");
+    out.push("");
+    out.push("```ts");
+    out.push(`filters: [{ field: '${names[0]}', contains: '<value>' }]`);
+    out.push("```");
+    out.push("");
+    out.push("Field names are CASE-SENSITIVE and only these are filterable — the " +
+        "platform drops a leaf it does not recognise and the trigger then fires " +
+        "on records the filter should have excluded, so `check` reports one that " +
+        "is not here.");
+    out.push("");
+    const shown = names
+        .slice(0, 40)
+        .map((n) => `\`${n}\``)
+        .join(", ");
+    const more = names.length > 40 ? ` …and ${names.length - 40} more` : "";
+    out.push(`${shown}${more}`);
+    out.push("");
+    if (selectors.length) {
+        const listed = selectors.map((n) => `\`${n}\``).join(", ");
+        out.push(`> **This list is a baseline, not the whole vocabulary.** ${listed} ` +
+            "select this event's schema, and the connector derives its filter " +
+            "and output fields from their VALUES — which no discovery call " +
+            "accepts, so the fields above are the ones reported with none " +
+            "supplied. A name outside them may still be legal, which is why " +
+            "`check` warns rather than refuses here. Confirm it against the " +
+            "trigger in the designer before deploying.");
+        out.push("");
+    }
+    else if (Object.entries(dictOf(pyOr(dictOf(j.connector).discovery, {}))).some(([name, value]) => name !== "type" && pyTruthy(value))) {
+        // Keyed on ANY discovery flag to match `Library.eventParameterFields.filtersPartial`.
+        out.push("> **This list is a subset no `prepare` can complete.** This connector " +
+            "reads its schema from the connection, and the trigger metadata call " +
+            "takes no parent values — `uip is triggers describe` has no `-f`, the " +
+            "flag that materializes an ACTIVITY's connection-scoped fields. So a " +
+            "name outside the list above may be a real field of yours; `check` warns " +
+            "rather than refuses, and the designer is where to confirm it.");
+        out.push("");
+    }
+    return out;
+}

package/dist/registry/generators/markdown/sections/header.d.ts

@@ -0,0 +1,2 @@
+import { type Dict } from "../pyvalue.js";
+export declare function headerLines(j: Dict, nodeType: string): string[];

package/dist/registry/generators/markdown/sections/header.js

@@ -0,0 +1,37 @@
+/**
+ * The page header: `# <nodeType>@<version>` and the connector / operation /
+ * object / label / description / HTTP lines. Curated and Generic entries share
+ * the shape; only the values differ.
+ */
+import { pyStr, pyStrip } from "../../../compat/pystr.js";
+import { dictOf, getStr, pyOr, pyTruthy } from "../pyvalue.js";
+export function headerLines(j, nodeType) {
+    const version = getStr(j, "version", "?");
+    const conn = dictOf(j.connector);
+    const op = dictOf(j.operation);
+    const display = dictOf(j.display);
+    const out = [`# ${nodeType}@${version}`, ""];
+    let connLabel = getStr(conn, "key", "?");
+    if (pyTruthy(conn.name))
+        connLabel += ` (${pyStr(conn.name)})`;
+    out.push(`**Connector:** ${connLabel}`);
+    const verb = pyOr(op.name, "");
+    if (pyTruthy(verb))
+        out.push(`**Operation:** ${pyStr(verb)}`);
+    const objectName = pyOr(op.objectName, "");
+    if (pyTruthy(objectName))
+        out.push(`**Object:** \`${pyStr(objectName)}\``);
+    // Only shown when it adds information beyond `<verb> <object>`.
+    const label = pyStrip(pyStr(pyOr(display.label, "")));
+    if (label)
+        out.push(`**Label:** ${label}`);
+    const desc = pyStrip(pyStr(pyOr(display.description, "")));
+    if (desc)
+        out.push(`**Description:** ${desc}`);
+    const httpMethod = pyOr(op.httpMethod, "");
+    const httpPath = pyOr(op.pathTemplate, op.path, "");
+    if (pyTruthy(httpMethod) && pyTruthy(httpPath))
+        out.push(`**HTTP:** ${pyStr(httpMethod)} ${pyStr(httpPath)}`);
+    out.push("");
+    return out;
+}

package/dist/registry/generators/markdown/sections/inputs.d.ts

@@ -0,0 +1,30 @@
+import { type Dict } from "../pyvalue.js";
+export declare function scalarType(dataType: unknown): string;
+/**
+ * The op's QUERY, PATH and file MULTIPART parameters as body-shaped fields,
+ * each tagged with its `location`. A string-typed multipart part is the
+ * transport container the runtime composes, not an input.
+ */
+export declare function paramFields(j: Dict): Dict[];
+/** File fields whose older catalog entry omitted the multipart parameter. */
+export declare function catalogMultipartFields(j: Dict): Dict[];
+/**
+ * The op's body fields: the sidecar's `inputDefinition.fields` whenever that
+ * key is present (an empty list stays empty), else the catalog's
+ * `inputSchema.fields`. This is the markdown generator's own rule, distinct
+ * from the descriptor generator's `inputFields`.
+ */
+export declare function inputFields(j: Dict, v1def: Dict | undefined): unknown[];
+/**
+ * Body fields, catalog-only file fields, then declared parameters. A
+ * parameter is authoritative on location, so it fills a same-named field in
+ * place — keeping any `reference`, `enum` or `displayName` the entry's field
+ * already carries — or is appended when the name is new.
+ */
+export declare function assembleFields(j: Dict, v1def: Dict | undefined): Dict[];
+/** One `- \`name\` (type, …) — description` bullet. */
+export declare function fieldLine(f: Dict): string;
+/** `## Required inputs`, always present; `_(none)_` when empty. */
+export declare function requiredInputsLines(required: readonly Dict[]): string[];
+/** `## Optional inputs`, only when there are any. */
+export declare function optionalInputsLines(optional: readonly Dict[]): string[];

package/dist/registry/generators/markdown/sections/inputs.js

@@ -0,0 +1,151 @@
+/**
+ * The input field set a page documents, and the line each field prints as.
+ *
+ * The set is the sidecar's `inputDefinition.fields` (what the compiler
+ * validates), falling back to the catalog's `inputSchema.fields` when an
+ * operation ships no sidecar; then the catalog's file fields as multipart
+ * parts; then the operation's QUERY, PATH and file MULTIPART parameters, a
+ * parameter filling gaps in a same-named body field rather than replacing it.
+ * Ported from `input_fields`, `catalog_multipart_fields`, `param_fields`,
+ * `field_line` and the assembly in `render_op`.
+ */
+import { pyStr, pyStrip } from "../../../compat/pystr.js";
+import { isContainerPart } from "../../fields.js";
+import { authoringField, enumValue, referenceCollection } from "../common.js";
+import { dictOf, listOf, pyOr, pyTruthy } from "../pyvalue.js";
+/** `operation.parameters[].type` → the wire slot, mirroring `core/library.ts`'s PARAM_LOCATIONS. */
+const PARAM_LOCATIONS = { query: "query", path: "path", multipart: "multipart" };
+/** A parameter's `dataType` → the scalar names `compile`'s literal type-check understands. */
+const SCALARS = {
+    integer: "number",
+    number: "number",
+    double: "number",
+    float: "number",
+    long: "number",
+    boolean: "boolean",
+    string: "string",
+};
+export function scalarType(dataType) {
+    if (typeof dataType !== "string")
+        return "?";
+    return Object.hasOwn(SCALARS, dataType) ? SCALARS[dataType] : dataType;
+}
+/**
+ * The op's QUERY, PATH and file MULTIPART parameters as body-shaped fields,
+ * each tagged with its `location`. A string-typed multipart part is the
+ * transport container the runtime composes, not an input.
+ */
+export function paramFields(j) {
+    const out = [];
+    for (const raw of listOf(pyOr(dictOf(j.operation).parameters, []))) {
+        const p = dictOf(raw);
+        const name = p.name;
+        const type = p.type;
+        const loc = typeof type === "string" && Object.hasOwn(PARAM_LOCATIONS, type) ? PARAM_LOCATIONS[type] : undefined;
+        if (typeof name !== "string" || !name || !loc)
+            continue;
+        if (isContainerPart(p))
+            continue;
+        const f = { name, type: scalarType(p.dataType), required: p.required === true, location: loc };
+        if (pyTruthy(p.description))
+            f.description = p.description;
+        if (pyTruthy(p.displayName))
+            f.displayName = p.displayName;
+        // `reference` says the value is an id resolved from a collection, not free text.
+        if (pyTruthy(p.reference))
+            f.reference = p.reference;
+        // A parameter's `enum` is deprecated in favour of `enhancedEnum`.
+        if (pyTruthy(p.enum))
+            f.enum = p.enum;
+        else if (pyTruthy(p.enhancedEnum))
+            f.enum = p.enhancedEnum;
+        out.push(f);
+    }
+    return out;
+}
+/** File fields whose older catalog entry omitted the multipart parameter. */
+export function catalogMultipartFields(j) {
+    const out = [];
+    for (const raw of listOf(pyOr(dictOf(j.inputSchema).fields, []))) {
+        const field = dictOf(raw);
+        if (!pyTruthy(field.name) || pyStr(pyOr(field.type, "")).toLowerCase() !== "file")
+            continue;
+        out.push({ ...field, location: "multipart" });
+    }
+    return out;
+}
+/**
+ * The op's body fields: the sidecar's `inputDefinition.fields` whenever that
+ * key is present (an empty list stays empty), else the catalog's
+ * `inputSchema.fields`. This is the markdown generator's own rule, distinct
+ * from the descriptor generator's `inputFields`.
+ */
+export function inputFields(j, v1def) {
+    const fields = dictOf(pyOr(dictOf(v1def).inputDefinition, {})).fields;
+    if (fields === undefined || fields === null)
+        return listOf(pyOr(dictOf(j.inputSchema).fields, []));
+    return listOf(fields);
+}
+/**
+ * Body fields, catalog-only file fields, then declared parameters. A
+ * parameter is authoritative on location, so it fills a same-named field in
+ * place — keeping any `reference`, `enum` or `displayName` the entry's field
+ * already carries — or is appended when the name is new.
+ */
+export function assembleFields(j, v1def) {
+    const fields = inputFields(j, v1def).map((f) => ({ ...dictOf(f) }));
+    for (const p of [...catalogMultipartFields(j), ...paramFields(j)]) {
+        const at = fields.findIndex((f) => f.name === p.name);
+        if (at >= 0) {
+            const merged = { ...fields[at] };
+            for (const [k, v] of Object.entries(p)) {
+                if (v !== null && v !== undefined && v !== "")
+                    merged[k] = v;
+            }
+            for (const key of ["reference", "enum", "displayName"]) {
+                if (key in fields[at] && !(key in p))
+                    merged[key] = fields[at][key];
+            }
+            fields[at] = merged;
+        }
+        else {
+            fields.push(p);
+        }
+    }
+    return fields;
+}
+/** One `- \`name\` (type, …) — description` bullet. */
+export function fieldLine(f) {
+    const [name, type, wireName] = authoringField(f);
+    const desc = pyStrip(pyStr(pyOr(f.description, "")).replaceAll("\n", " "));
+    const enumeration = f.enum;
+    let suffix = pyTruthy(enumeration) ? `, enum: ${listOf(enumeration).map(enumValue).join(" | ")}` : "";
+    if (wireName)
+        suffix += `, wire field: \`${wireName}\``;
+    // The wire slot for a QUERY, PATH or MULTIPART parameter; body fields stay untagged.
+    const loc = f.location;
+    if (loc === "query" || loc === "path" || loc === "multipart")
+        suffix += `, ${loc}`;
+    // Name the collection so the line itself says "this is a lookup, not free text".
+    const collection = referenceCollection(f);
+    if (collection)
+        suffix += `, lookup: ${collection}`;
+    const head = `- \`${name}\` (${type}${suffix})`;
+    return desc ? `${head} — ${desc}` : head;
+}
+/** `## Required inputs`, always present; `_(none)_` when empty. */
+export function requiredInputsLines(required) {
+    const out = ["## Required inputs", ""];
+    if (required.length)
+        out.push(...required.map(fieldLine));
+    else
+        out.push("_(none)_");
+    out.push("");
+    return out;
+}
+/** `## Optional inputs`, only when there are any. */
+export function optionalInputsLines(optional) {
+    if (!optional.length)
+        return [];
+    return ["## Optional inputs", "", ...optional.map(fieldLine), ""];
+}

package/dist/registry/generators/markdown/sections/lookups.d.ts

@@ -0,0 +1,12 @@
+import { type Dict } from "../pyvalue.js";
+/** The `resources run list` call that shows what an identity-lookup field accepts. */
+export declare function enumerationCommand(connectorKey: string, f: Dict): string;
+/** Prose for how `prepare` will retrieve this collection. */
+export declare function referenceStrategy(reference: Dict): string;
+/**
+ * The section body, or `[]` when no field is a lookup. `symbol` is the
+ * generated descriptor's exported name, or `undefined` when the operation has
+ * no descriptor (a Generic CRUD expansion), in which case the string form of
+ * `lookup()` carries the real key and action.
+ */
+export declare function lookupLines(connectorKey: string, action: string, fields: readonly Dict[], symbol: string | undefined, invariant: ReadonlySet<string>): string[];