@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

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[];

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

@@ -0,0 +1,150 @@
+/**
+ * `## Resolving lookups`: helpers first, enumeration commands only where owed.
+ *
+ * A field holding an id is resolved late through `lookup(...)` and one
+ * `prepare`; the `resources run list` command survives only for IDENTITY
+ * lookups, which have no helper and no offline vocabulary. Ported from
+ * `lookup_lines`, `enumeration_command` and `reference_strategy`.
+ */
+import { pyJsonString } from "../../../codecs/pyjson.js";
+import { sortedStrings } from "../../../compat/compare.js";
+import { pyStr, splitOnce } from "../../../compat/pystr.js";
+import { classify, referenceOf } from "../../../lookup-specs.js";
+import { byAliases } from "../../../naming.js";
+import { authoringField, referenceCollection, referenceQuery } from "../common.js";
+import { firstValue, IDENT, pyOr, pyTruthy, strList } from "../pyvalue.js";
+/** The `resources run list` call that shows what an identity-lookup field accepts. */
+export function enumerationCommand(connectorKey, f) {
+    const collection = referenceCollection(f);
+    const query = referenceQuery(f);
+    let command = `uip is resources run list ${connectorKey} ${collection} --connection-id <id>`;
+    if (query)
+        command += ` --query "${query}"`;
+    return command;
+}
+/** Prose for how `prepare` will retrieve this collection. */
+export function referenceStrategy(reference) {
+    if (pyTruthy(reference.dependsOn)) {
+        const depends = strList(reference.dependsOn)
+            .map((d) => `\`${d}\``)
+            .join(", ");
+        return `dependent — resolve ${depends} first`;
+    }
+    if (pyTruthy(reference.filterPattern))
+        return "one request (server-side filter)";
+    if (pyTruthy(reference.childPath))
+        return "hierarchical walk";
+    return "paged scan (no server-side filter declared)";
+}
+/**
+ * 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 function lookupLines(connectorKey, action, fields, symbol, invariant) {
+    const resolvable = [];
+    const identity = [];
+    for (const f of fields) {
+        const kind = classify(f, invariant);
+        if (kind === "lookup")
+            resolvable.push([f, referenceOf(f)]);
+        else if (kind === "identity")
+            identity.push(f);
+    }
+    if (!resolvable.length && !identity.length)
+        return [];
+    const out = [];
+    if (resolvable.length) {
+        const [firstField, firstReference] = resolvable[0];
+        // Keyed by the WIRE name (`users[*]`), the string `--resolve` and
+        // buildConnectorInputs match on; the table's `field` column keeps the
+        // authoring name the reader writes as an object key.
+        const firstName = pyStr(pyOr(firstField.name, authoringField(firstField)[0]));
+        const firstNames = strList(firstReference.lookupNames);
+        const firstAliases = byAliases(firstNames);
+        const holder = symbol || `'${connectorKey}', '${action}'`;
+        const call = `lookup(${holder}, '${firstName}')`;
+        const sample = firstAliases.size
+            ? `.${firstValue(firstAliases)}('…')`
+            : firstNames.length
+                ? `.by('${firstNames[0]}', '…')`
+                : ".by('id', '…')";
+        // The MECHANISM — resolve, never hand-write the wire value — is true of
+        // every lookup. The old JUSTIFICATION was not: it asserted the value is an
+        // opaque, connection-specific id, which is false for 320 of the library's
+        // 2,563 rows and, on `uipath-salesforce-slack` `send-message-to-user`, for
+        // a row printed three lines below the claim (`send_as` sends the word
+        // `bot`) — #706. Nothing in the metadata says which case a field is in, so
+        // the id claim is stated as the CONDITION it always was, and the `sends`
+        // column — already printed below — answers which case this page is.
+        out.push("These fields send a value the connector defines, not the label you " +
+            "know it by — the `sends` column says which. Do not write that value " +
+            "by hand: where it is an opaque id it is also connection-specific, so " +
+            "a pasted one resolves to nobody (or to somebody else) against a " +
+            "different connection. Resolve it late:");
+        out.push("");
+        out.push("```ts");
+        // A dotted wire name is a legal object key only when quoted.
+        const key = IDENT.test(firstName) ? firstName : pyJsonString(firstName);
+        out.push(`${key}: ${call}${sample}`);
+        out.push("```");
+        out.push("");
+        out.push("| field | helpers | matches on | sends |");
+        out.push("| --- | --- | --- | --- |");
+        for (const [f, reference] of resolvable) {
+            const [name] = authoringField(f);
+            const names = strList(reference.lookupNames);
+            const aliases = byAliases(names);
+            const helperCell = aliases.size
+                ? [...aliases.values()].map((a) => `\`.${a}(v)\``).join(" ")
+                : "_(generic form only)_";
+            // `objectName` can carry a query string; show the collection.
+            const target = pyOr(splitOnce(pyStr(pyOr(reference.objectName, "")), "?")[0], referenceCollection(f));
+            out.push(`| \`${name}\` | ${helperCell} | ` +
+                names.map((n) => `\`${n}\``).join(" ") +
+                ` | \`${target}.${pyStr(reference.lookupValue)}\` |`);
+        }
+        out.push("");
+        out.push("Any field also takes the generic form: `.by('<name>', value)`.");
+        out.push("");
+        // ORDERING, not just the command: author the token, let check name the command, run it once.
+        out.push("Author the `lookup()` call and finish the flow — `check` reports " +
+            "each token still unresolved with exactly this command; run it " +
+            "once before compiling (`compile` refuses an unresolved lookup):");
+        out.push("");
+        // ONE command carrying every --resolve, and no `--connection-id`.
+        out.push("```bash");
+        out.push(`npx flow-sdk registry prepare ${connectorKey} ${action} \\`);
+        const resolves = resolvable.map(([f, reference]) => {
+            const [name] = authoringField(f);
+            const names = pyOr(strList(reference.lookupNames), ["id"]);
+            return `  --resolve ${name}:${names[0]}=<value>`;
+        });
+        for (const line of resolves.slice(0, -1))
+            out.push(`${line} \\`);
+        out.push(resolves[resolves.length - 1]);
+        out.push("```");
+        out.push("");
+        const strategies = new Set(resolvable.map(([, r]) => referenceStrategy(r)));
+        out.push(`Strategy: ${sortedStrings(strategies).join("; ")}.`);
+        out.push("");
+    }
+    if (identity.length) {
+        out.push("**These fields take a plain string.** Their `reference` enumerates " +
+            "the legal values rather than mapping a name to an id — what you " +
+            "send back is what you searched for — so there is no helper and " +
+            "nothing to resolve. The values exist only behind the connection, " +
+            "so this is how to see what is accepted:");
+        out.push("");
+        out.push("```bash");
+        for (const f of identity) {
+            const [name] = authoringField(f);
+            out.push(`# ${name}`);
+            out.push(enumerationCommand(connectorKey, f));
+        }
+        out.push("```");
+        out.push("");
+    }
+    return out;
+}

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

@@ -0,0 +1,3 @@
+/** `## Outputs`: the entry's `outputSchema.fields`, one bullet each. The sidecar carries no output fields. */
+import { type Dict } from "../pyvalue.js";
+export declare function outputsLines(j: Dict): string[];

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

@@ -0,0 +1,9 @@
+/** `## Outputs`: the entry's `outputSchema.fields`, one bullet each. The sidecar carries no output fields. */
+import { dictOf, listOf, pyOr } from "../pyvalue.js";
+import { fieldLine } from "./inputs.js";
+export function outputsLines(j) {
+    const outFields = listOf(pyOr(dictOf(j.outputSchema).fields, []));
+    if (!outFields.length)
+        return [];
+    return ["## Outputs", "", ...outFields.map((f) => fieldLine(dictOf(f))), ""];
+}

package/dist/registry/generators/markdown/sections/resolving-fields.d.ts

@@ -0,0 +1,2 @@
+import { type Dict } from "../pyvalue.js";
+export declare function schemaActionLines(connectorKey: string, objectName: string, verb: string, action: Dict, fields: readonly Dict[]): string[];

package/dist/registry/generators/markdown/sections/resolving-fields.js

@@ -0,0 +1,139 @@
+/**
+ * `## Resolving the field set`: how to get an operation's real field set when
+ * parent VALUES select it (Jira `create-issue` describes to 2 fields with
+ * nothing supplied and 32 once a project and an issue type are given).
+ * Ported from `schema_action_lines`.
+ */
+import { pyStr, splitOnce } from "../../../compat/pystr.js";
+import { referenceCollection, referenceQuery } from "../common.js";
+import { dictOf, listOf, pyOr, pyTruthy } from "../pyvalue.js";
+export function schemaActionLines(connectorKey, objectName, verb, action, fields) {
+    const parents = listOf(pyOr(action.parents, []));
+    if (!parents.length)
+        return [];
+    const byName = new Map();
+    for (const f of fields)
+        byName.set(f.name, f);
+    const trigger = action.trigger;
+    const replaces = action.replaces;
+    const obj = pyOr(objectName, "<object>");
+    const out = ["## Resolving the field set", ""];
+    out.push("The inputs listed below are only the ones that SELECT the field set. " +
+        "The real set depends on the values of " +
+        parents.map((p) => `\`${pyStr(p)}\``).join(", ") +
+        " — a different value gives a different set, so there is no single " +
+        "field list for this operation.");
+    out.push("");
+    if (pyTruthy(trigger)) {
+        out.push(`It is not automatic: \`${pyStr(trigger)}\` is a trigger rather than data, ` +
+            "so the schema has to be requested once the values are in place.");
+        out.push("");
+    }
+    out.push("Resolve the parents in this order, then describe again:");
+    out.push("");
+    parents.forEach((parentRaw, i) => {
+        const position = i + 1;
+        const parent = pyStr(parentRaw);
+        const field = dictOf(byName.get(parentRaw));
+        const reference = dictOf(pyOr(field.reference, {}));
+        const collection = referenceCollection(field);
+        if (!collection) {
+            out.push(`${position}. \`${parent}\` — supply the value; it is not chosen from a list.`);
+            out.push("");
+            return;
+        }
+        const query = referenceQuery(field);
+        const pattern = pyStr(pyOr(reference.filterPattern, ""));
+        const names = listOf(pyOr(reference.lookupNames, []));
+        const send = pyStr(pyOr(reference.lookupValue, "id"));
+        out.push(`${position}. \`${parent}\` — from \`${collection}\`` +
+            (names.length ? `, match on ${names.map((n) => `\`${pyStr(n)}\``).join(" or ")}` : "") +
+            `, send \`${send}\`.`);
+        // A placeholder means an earlier parent's value goes here.
+        if (collection.includes("{")) {
+            out.push("   Substitute the value resolved above for the `{…}` part of the collection.");
+        }
+        out.push("");
+        out.push("   ```bash");
+        out.push(`   uip is resources run list ${connectorKey} ${collection} --connection-id <id> \\`);
+        if (pattern) {
+            // The connector declares its own search; substituting the term narrows server-side.
+            out.push(`     --query "${pattern.replaceAll("{filter}", "<search-term>")}" \\`);
+        }
+        else if (query) {
+            out.push(`     --query "${query}" \\`);
+        }
+        const projection = pyOr(names.slice(0, 2), ["name"])
+            .map((n) => `${splitOnce(pyStr(n), "[")[0]}:${pyStr(n)}`)
+            .join(",");
+        out.push(`     --output-filter "{items: items[*].{${projection},` +
+            `send:${send}}, page: Pagination.{h:HasMore,t:NextPageToken}}" \\`);
+        out.push("     --output json");
+        out.push("   ```");
+        out.push("");
+        if (pattern) {
+            out.push("   The connector declares its own search, so narrow with " +
+                "the term the user gave rather than reading pages: one " +
+                "call usually returns a handful, and `page` comes back " +
+                "either absent or with `h` as `\"false\"`. Page only if " +
+                "the term matches nothing.");
+        }
+        else {
+            out.push("   Page it: `page.h` is the `elements-has-more` response " +
+                "header verbatim, so it is the string `\"true\"` rather " +
+                "than a boolean, and `page` is absent altogether when the " +
+                "connector sends no pagination headers. While it reads " +
+                "`\"true\"` and the value has not appeared, pass `page.t` " +
+                "back as `--query \"nextPage=<token>\"` and read the next " +
+                "page. Stop on the match. The projection keeps each page " +
+                "small but does not reduce the call count.");
+            out.push("");
+            out.push("   Before paging, check this field's `Reference` in the " +
+                "`describe` output for a `FilterPattern`: it is " +
+                "connection-scoped, so it is not in this catalog, but when " +
+                "present it is the connector's own search and removes the " +
+                "paging — Jira's project lookup declares `query={filter}`, " +
+                "which turns 420-plus rows across pages into two in one call. " +
+                "Substitute the wanted term into whatever pattern this field " +
+                "declares; the shape is:");
+            out.push("");
+            out.push("   ```bash");
+            out.push(`   uip is resources run list ${connectorKey} ${collection} --connection-id <id> \\`);
+            out.push('     --query "<filter-pattern with the term substituted>" --output json');
+            out.push("   ```");
+        }
+        out.push("");
+    });
+    const supplied = parents.map((p) => `-f ${pyStr(p)}=<value>`).join(" ");
+    out.push(`${parents.length + 1}. Describe again with the resolved values:`);
+    out.push("");
+    out.push("   ```bash");
+    out.push(`   uip is resources describe ${connectorKey} ${pyStr(obj)} --operation ${verb} \\`);
+    out.push(`     --connection-id <id> ${supplied} --output json`);
+    out.push("   ```");
+    out.push("");
+    if (replaces === "output") {
+        out.push("   This replaces the **response** fields — it tells you the shape " +
+            "of what comes back, not what to send.");
+    }
+    else if (replaces === "both") {
+        out.push("   This replaces the **request** fields AND the **response** " +
+            "fields — both halves of this operation change with the values " +
+            "above, so read the response shape from the same call.");
+    }
+    else {
+        out.push("   This replaces the **request** fields.");
+    }
+    out.push("");
+    // Only meaningful where the action rewrites the INPUT (matches the CLI's `isParentOnlyResult` gate).
+    if (replaces === "input" || replaces === "both") {
+        out.push("If the result contains only the parents again, one of the values " +
+            "does not exist on this connection. The call reports `Success` " +
+            "either way, so the count alone cannot tell that apart from having " +
+            "supplied nothing — check whether anything beyond the parents came " +
+            "back. Too FEW parents fails loudly instead, with " +
+            "`No api-type ObjectAction matched`.");
+        out.push("");
+    }
+    return out;
+}

package/dist/registry/generators/markdown/sections/schema-dynamic.d.ts

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