@uipath/maestro-builder-sdk 5.2.0

package/dist/generators/generate_connectors_ts.py

@@ -0,0 +1,936 @@
+#!/usr/bin/env python3
+"""Generate statically-typed TypeScript connector descriptors from the canonical
+JSON connector library.
+
+For every **Curated** and **HTTP-request** op, emit one `descriptor<Inputs,
+Outputs>()` const plus its `Inputs`/`Outputs` interfaces, grouped one module per
+connector:
+
+    connectors/<connector-key>.ts
+      export interface FieldsInput { project: ProjectInput; summary: string; … }
+      export interface ProjectInput { key: string; }
+      export interface CreateIssueInputs { fields: FieldsInput; }
+      export interface Fields { issuetype?: Issuetype; }
+      export interface Issuetype { name?: string; }
+      export interface CreateIssueOutputs { fields?: Fields; id?: string; key?: string; … }
+      export const CreateIssue = descriptor<CreateIssueInputs, CreateIssueOutputs>()({
+        nodeType: 'uipath.connector.uipath-atlassian-jira.create-issue',
+        version: '1.0.0', requiresConnection: true, requiresFolderKey: true,
+      } as const);
+
+Inputs are the union of the op's **v1def.inputDefinition.fields** (body) and
+**entry.operation.parameters** (query/path/multipart). When both declarations are empty
+but the catalog still declares required inputs, **entry.inputSchema.fields** is
+the only available authoring surface and is used as a fallback. Catalog file
+fields also fill older snapshots that omitted their multipart parameter. Dotted
+and wildcard body fields are reconstructed as natural nested objects/arrays; `serialize()`/
+`buildConnectorInputs` project them back to the exact registry field ids and
+route every field to its declared Flow JSON slot. Outputs come from the entry's
+`outputSchema.fields` and use the same nested reusable-type model.
+
+**GenericExpanded ops are skipped for the bulk static library by default** to
+avoid emitting thousands of descriptors. A small connection-resolved overlay
+passes `--include-generic-expanded`; those entries carry the selected object's
+live fields in `v1def.inputDefinition.fields`, and their descriptors bake in
+`ConnectorMeta.objectName` so authoring needs no separate `{ object }` option.
+
+Usage:
+    generate_connectors_ts.py --library <json-lib-dir> --output <ts-dir>
+                              [--import <specifier>] [--connectors a,b,c]
+                              [--include-generic-expanded]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# Symbol derivation is SHARED with convert_library_to_md.py — the markdown cites
+# these names, and a name derived twice is a name that drifts. See _naming.py.
+from _naming import by_aliases, pascal, singular, symbol_index
+from _lookups import classify, load_invariant_collections, reference_of
+
+TYPE_MAP = {
+    "string": "string", "number": "number", "integer": "number", "float": "number",
+    "double": "number", "long": "number",
+    "boolean": "boolean", "bool": "boolean", "object": "Record<string, unknown>",
+    "array": "unknown[]", "json": "unknown", "file": "string",
+}
+
+
+def is_container_part(parameter: dict) -> bool:
+    """A multipart parameter that is not a file.
+
+    The runtime composes it from ``bodyParameters`` (Teams ``body`` from
+    ``body.content``, Gmail ``body`` from ``Body``, GenAI ``RagRequest`` from
+    ``prompt``); the author never fills it, and a value written into it is
+    ignored at dispatch (verified live 2026-09-02). It is listed in the emitted
+    ``multipartParameters`` by the compiler, not offered as an input here — the
+    same rule as ``core/library.ts``'s ``isContainerPart``.
+    """
+    return (
+        parameter.get("type") == "multipart"
+        and str(parameter.get("dataType") or "string").lower() != "file"
+    )
+
+
+def authoritative_input_fields(entry: dict, v1def: dict) -> list[dict]:
+    """Return the same complete input vocabulary consumed by the SDK runtime.
+
+    Body fields live in ``v1def.inputDefinition.fields``; query, path, and
+    FILE multipart parameters live in ``entry.operation.parameters``. A
+    declaration wins when the same name appears in both because its wire
+    location is authoritative. A string-typed multipart parameter is the
+    transport container, not an input (see ``is_container_part``).
+    """
+    fields = [dict(field) for field in
+              (((v1def.get("inputDefinition") or {}).get("fields")) or [])]
+    positions = {field.get("name"): index for index, field in enumerate(fields)}
+    parameters = ((entry.get("operation") or {}).get("parameters")) or []
+    for parameter in parameters:
+        name = parameter.get("name")
+        if not name or parameter.get("type") not in {
+            "query", "path", "multipart"
+        }:
+            continue
+        if is_container_part(parameter):
+            continue
+        field = {
+            "name": name,
+            "type": parameter.get("dataType"),
+            "required": parameter.get("required") is True,
+        }
+        if parameter.get("displayName"):
+            field["displayName"] = parameter["displayName"]
+        if parameter.get("description"):
+            field["description"] = parameter["description"]
+        # A QUERY parameter can carry a `reference` too — Slack's `send_as`
+        # does. Rebuilding the field from scratch dropped it, which made those
+        # lookups invisible to everything downstream.
+        if isinstance(parameter.get("reference"), dict):
+            field["reference"] = parameter["reference"]
+        if name in positions:
+            fields[positions[name]] = field
+        else:
+            positions[name] = len(fields)
+            fields.append(field)
+    return fields
+
+
+def input_fields(entry: dict, v1def: dict) -> list[dict]:
+    fields = authoritative_input_fields(entry, v1def)
+    catalog_fields = (entry.get("inputSchema") or {}).get("fields") or []
+    if not fields and any(
+        field.get("required") is True for field in catalog_fields
+    ):
+        fields = [dict(field) for field in catalog_fields]
+    positions = {field.get("name"): index for index, field in enumerate(fields)}
+    for catalog_field in catalog_fields:
+        name = catalog_field.get("name")
+        if (
+            not name
+            or str(catalog_field.get("type") or "").lower() != "file"
+            or name in positions
+        ):
+            continue
+        positions[name] = len(fields)
+        fields.append(dict(catalog_field))
+    return fields
+
+
+EVENT_NODE_PREFIXES = ("uipath.connector.event.", "uipath.connector.trigger.")
+
+
+def is_event_node(node_type: str) -> bool:
+    """An event/trigger entry, as opposed to a connector ACTION."""
+    return str(node_type or "").startswith(EVENT_NODE_PREFIXES)
+
+
+def descriptor_input_fields(entry: dict, v1def: dict) -> list[dict]:
+    """The one field list a descriptor's inputs — or an event's `where` — come from.
+
+    An event's authored inputs are its SUBSCRIPTION PARAMETERS, and
+    `v1def.eventParameters.fields` is the only place that holds them on BOTH
+    library shapes. A published entry happens to repeat them in
+    `inputDefinition.fields`, so reading `input_fields()` for an event looked
+    right; the overlay `prepare` writes leaves `inputDefinition.fields` empty
+    and keeps the parameters in the sidecar alone. The emit path read
+    `input_fields()` while the loop that builds the type tree read
+    `eventParameters` — two rules for one list — so after a `prepare`, and only
+    after a `prepare`, `where` degraded to `Record<string, string>` and the
+    descriptor carried no `lookups`. That is the descriptor `prepare` tells the
+    author to import, so `lookup(EmailReceived, 'parentFolderId')
+    .byDisplayName('Inbox')` failed with a bare TypeError on exactly the path
+    the skill steers them down.
+
+    An entry that declares none keeps the loose `where` (see `emit_event`).
+    """
+    if is_event_node(entry.get("nodeType") or ""):
+        return (v1def.get("eventParameters") or {}).get("fields") or []
+    return input_fields(entry, v1def)
+
+
+def required_input_gap(
+    entry: dict, input_tree: dict[str, "TypeNode"]
+) -> str | None:
+    required = [
+        str(field.get("name") or "<unnamed>")
+        for field in (entry.get("inputSchema") or {}).get("fields") or []
+        if field.get("required") is True
+    ]
+    if not required or input_tree:
+        return None
+    return (
+        f'{entry.get("nodeType", "<unknown node>")}: catalog requires '
+        f'{", ".join(required)}, but the generated inputs interface is empty'
+    )
+
+
+def ts_type(field: dict) -> str:
+    return TYPE_MAP.get(str(field.get("type") or "").lower(), "unknown")
+
+
+class TypeNode:
+    """One node in a tree reconstructed from flattened connector field paths."""
+
+    def __init__(self, *, is_array: bool = False) -> None:
+        self.array_modes: set[bool] = {is_array}
+        self.declared_types: set[str] = set()
+        self.declared: dict | None = None
+        self.opaque_object = False
+        self.opaque_array = False
+        self.required = False
+        self.children: dict[str, TypeNode] = {}
+
+    def add_declaration(self, field: dict) -> None:
+        if self.declared is None:
+            self.declared = field
+        declared_type = str(field.get("type") or "").lower()
+        self.declared_types.add(ts_type(field))
+        self.opaque_object = self.opaque_object or declared_type == "object"
+        self.opaque_array = self.opaque_array or declared_type == "array"
+        self.required = self.required or bool(field.get("required"))
+
+
+def split_field_path(name: str) -> list[tuple[str, bool]]:
+    """Split ``items[*].owner.id`` into segments plus array cardinality."""
+    parts: list[tuple[str, bool]] = []
+    for raw in name.split("."):
+        is_array = raw.endswith("[*]")
+        segment = raw[:-3] if is_array else raw
+        # Preserve malformed/opaque registry names as one quoted property.
+        if not segment:
+            return [(name, False)]
+        parts.append((segment, is_array))
+    return parts
+
+
+def build_type_tree(fields: list[dict]) -> dict[str, TypeNode]:
+    roots: dict[str, TypeNode] = {}
+    for field in fields:
+        name = field.get("name")
+        if not name:
+            continue
+        cursor = roots
+        node: TypeNode | None = None
+        for segment, is_array in split_field_path(str(name)):
+            node = cursor.setdefault(segment, TypeNode(is_array=is_array))
+            node.array_modes.add(is_array)
+            cursor = node.children
+        if node is not None:
+            node.add_declaration(field)
+    return roots
+
+
+def merge_type_nodes(target: TypeNode, source: TypeNode) -> None:
+    """Merge repeated occurrences into one reusable connector-level type."""
+    target.array_modes.update(source.array_modes)
+    target.declared_types.update(source.declared_types)
+    target.opaque_object = target.opaque_object or source.opaque_object
+    target.opaque_array = target.opaque_array or source.opaque_array
+    target.required = target.required or source.required
+    if target.declared is None:
+        target.declared = source.declared
+    for child_name, source_child in source.children.items():
+        target_child = target.children.get(child_name)
+        if target_child is None:
+            target.children[child_name] = source_child
+        else:
+            merge_type_nodes(target_child, source_child)
+
+
+def nested_type_name(field_name: str, node: TypeNode, suffix: str = "") -> str:
+    source = singular(field_name) if (True in node.array_modes or node.opaque_array) else field_name
+    name = pascal(source)
+    name = name if re.match(r"[A-Za-z_$]", name) else f"Nested{name}"
+    return f"{name}{suffix}"
+
+
+def key_literal(name: str) -> str:
+    # A field name is a valid ident only if it has no dots/brackets/etc.
+    return name if re.fullmatch(r"[A-Za-z_$][A-Za-z0-9_$]*", name) else json.dumps(name)
+
+
+def subtree_required(node: TypeNode) -> bool:
+    return node.required or any(subtree_required(child) for child in node.children.values())
+
+
+def type_fingerprint(node: TypeNode) -> tuple:
+    """Stable structural identity; input types reuse only exact shapes."""
+    return (
+        tuple(sorted(node.array_modes)),
+        tuple(sorted(node.declared_types)),
+        node.opaque_object,
+        node.opaque_array,
+        node.required,
+        tuple((name, type_fingerprint(child)) for name, child in sorted(node.children.items())),
+    )
+
+
+class NamedTypeRegistry:
+    """Reusable named interfaces shared by all ops in one connector."""
+
+    def __init__(
+        self, *, suffix: str = "", all_optional: bool = True, merge_reused: bool = True,
+        is_input: bool = False,
+    ) -> None:
+        self.is_input = is_input
+        self.suffix = suffix
+        self.all_optional = all_optional
+        self.merge_reused = merge_reused
+        self._by_name: dict[str, TypeNode] = {}
+        self._by_node: dict[int, str] = {}
+        self._shape_names: dict[tuple[str, tuple], str] = {}
+        self._definitions: list[str] = []
+        self._registering: set[str] = set()
+
+    def register(self, field_name: str, node: TypeNode) -> str:
+        known = self._by_node.get(id(node))
+        if known:
+            return known
+
+        base_name = nested_type_name(field_name, node, self.suffix)
+        if self.merge_reused:
+            type_name = base_name
+        else:
+            shape_key = (base_name, type_fingerprint(node))
+            type_name = self._shape_names.get(shape_key, "")
+            if not type_name:
+                type_name = base_name
+                suffix = 2
+                while type_name in self._by_name:
+                    type_name = f"{base_name}{suffix}"
+                    suffix += 1
+                self._shape_names[shape_key] = type_name
+
+        canonical = self._by_name.get(type_name)
+        if canonical is None:
+            canonical = node
+            self._by_name[type_name] = canonical
+            self._definitions.append(type_name)
+        elif canonical is not node:
+            if self.merge_reused:
+                merge_type_nodes(canonical, node)
+        self._by_node[id(node)] = type_name
+
+        # A schema can recursively repeat the same segment name
+        # (`children[*].children[*]...`). Merge it into the shared interface,
+        # but do not recursively rediscover that interface while it is active.
+        if type_name in self._registering:
+            return type_name
+        self._registering.add(type_name)
+
+        # Registration can enrich a canonical node, so iterate a snapshot.
+        try:
+            for child_name, child in list(canonical.children.items()):
+                if child.children or child.opaque_object:
+                    self.register(child_name, child)
+        finally:
+            self._registering.remove(type_name)
+        return type_name
+
+    def discover(self, roots: dict[str, TypeNode]) -> None:
+        for field_name, node in roots.items():
+            if node.children or node.opaque_object:
+                self.register(field_name, node)
+
+    def _known_array_element(self, field_name: str, node: TypeNode) -> str | None:
+        candidate = nested_type_name(field_name, node, self.suffix)
+        matches = [
+            name for name in self._by_name
+            if name == candidate or re.fullmatch(re.escape(candidate) + r"[2-9][0-9]*", name)
+        ]
+        return matches[0] if len(matches) == 1 else None
+
+    def type_for(self, field_name: str, node: TypeNode) -> str:
+        if node.children or node.opaque_object:
+            base = self.register(field_name, node)
+        elif node.opaque_array:
+            known_element = self._known_array_element(field_name, node)
+            if known_element:
+                return f"Array<{known_element}>"
+            return "unknown[]"
+        else:
+            base = " | ".join(sorted(node.declared_types)) or "unknown"
+
+        has_array = True in node.array_modes
+        has_scalar = False in node.array_modes
+        if has_array and has_scalar:
+            return f"{base} | Array<{base}>"
+        if has_array:
+            return f"Array<{base}>"
+        return base
+
+    def emit(self) -> list[str]:
+        lines: list[str] = []
+        # Rendering a definition may register an opaque nested object. Iterate
+        # by index so newly discovered definitions are emitted too.
+        index = 0
+        while index < len(self._definitions):
+            type_name = self._definitions[index]
+            node = self._by_name[type_name]
+            lines.append(f"export interface {type_name} {{")
+            if node.opaque_object:
+                lines.append("  [key: string]: unknown;")
+            for child_name, child in node.children.items():
+                lines += emit_nested_property(
+                    child_name, child, "  ", self, self.all_optional, self.is_input,
+                )
+            lines.append("}")
+            lines.append("")
+            index += 1
+        return lines
+
+
+def emit_nested_property(
+    name: str,
+    node: TypeNode,
+    indent: str,
+    named_types: NamedTypeRegistry,
+    all_optional: bool,
+    is_input: bool = False,
+) -> list[str]:
+    """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(…)]`;
+    `ConnectorValue` distributes over arrays to cover both.
+
+    An OUTPUT property is never wrapped. It is a value that came back from the
+    connector, so it cannot be an expression or an unresolved lookup.
+    """
+    lines: list[str] = []
+    declared = node.declared or {}
+    desc = str(declared.get("description") or "").strip().replace("\n", " ")
+    if is_input and declared.get("__lookup"):
+        # The identity goes ON the field, not only in the LOOKUP block above the
+        # descriptor: the field is where the value gets typed, and "The reporter
+        # of the issue" beside `ConnectorLookupValue<string>` read as "any string"
+        # — an e-mail went into `fields.reporter.id` and Jira refused it at run time.
+        desc = f"{desc} {lookup_field_note(declared)}".strip()
+    if desc:
+        lines.append(f"{indent}/** {desc} */")
+    optional = "?" if all_optional or not subtree_required(node) else ""
+    rendered = named_types.type_for(name, node)
+    if is_input:
+        wrapper = "ConnectorLookupValue" if declared.get("__lookup") else "ConnectorValue"
+        rendered = f"{wrapper}<{rendered}>"
+    lines.append(f"{indent}{key_literal(name)}{optional}: {rendered};")
+    return lines
+
+
+def lookup_field_note(declared: dict) -> str:
+    """One sentence for a lookup field's own doc comment: what it sends, how to get one."""
+    reference = reference_of(declared) or {}
+    target = str(reference.get("objectName") or str(reference.get("path") or "").split("?", 1)[0])
+    value = str(reference.get("lookupValue") or "id")
+    field = str(declared.get("name") or "")
+    return (
+        f"LOOKUP — sends a `{target}.{value}`, never a name or e-mail: "
+        f"lookup(<Descriptor>, '{field}') (helpers in the LOOKUP lines above the descriptor)."
+    )
+
+
+def emit_interface(
+    name: str,
+    fields: list[dict],
+    all_optional: bool,
+    named_types: NamedTypeRegistry,
+    field_tree: dict[str, TypeNode],
+    is_input: bool = False,
+) -> list[str]:
+    out = [f"export interface {name} {{"]
+    for field_name, node in field_tree.items():
+        out += emit_nested_property(
+            field_name, node, "  ", named_types, all_optional, is_input,
+        )
+    out.append("}")
+    return out
+
+
+
+def lookup_strategy(reference: dict) -> str:
+    """Which retrieval strategy `prepare` will use for this field.
+
+    Order matters. `dependsOn` wins outright because it is a PREREQUISITE
+    rather than an optimisation — the collection is not addressable at all
+    until another field resolves, so no amount of filtering helps. After that
+    a server-side filter beats a tree walk beats a full scan.
+    """
+    if reference.get("dependsOn"):
+        return "dependent"
+    if reference.get("filterPattern"):
+        return "filter"
+    if reference.get("childPath"):
+        return "tree"
+    return "scan"
+
+
+def lookup_specs(entry: dict, v1def: dict, invariant: set) -> dict:
+    """`{fieldName: spec}` for every field that earns a `.by*` helper.
+
+    Keyed by the WIRE field name — the same string `buildConnectorInputs`
+    matches on and the same one `prepare --resolve <field>:…` takes — so a
+    nested field like `fields.project.key` is addressed by its dotted path and
+    there is exactly one spelling of a field across the whole toolchain.
+
+    `reference` is unioned in from `inputSchema.fields` where the authoring
+    vocabulary lacks it: the two declarations disagree about which fields they
+    carry, and a lookup declared only in the catalog is still a lookup.
+    """
+    catalog_references = {
+        f.get("name"): f["reference"]
+        for f in ((entry.get("inputSchema") or {}).get("fields") or [])
+        if isinstance(f.get("reference"), dict)
+    }
+    return specs_from_fields(
+        input_fields(entry, v1def), invariant, catalog_references)
+
+
+def specs_from_fields(
+    fields: list[dict], invariant: set, catalog_references: dict | None = None,
+) -> dict:
+    """`{fieldName: spec}` for the lookup-bearing fields of ANY field list.
+
+    Split out of `lookup_specs` so a connector EVENT can build the same specs
+    from its `eventParameters.fields` — the list `lookup()` resolves against for
+    a subscription — instead of from `inputSchema`/`inputDefinition`, which an
+    event does not use. Two emitters, one implementation: when they were
+    separate, `emit_event` simply had none, and every event descriptor shipped
+    without the `.by*` helpers its curated sibling had.
+    """
+    specs = {}
+    for field in fields:
+        name = field.get("name")
+        if not name:
+            continue
+        merged = dict(field)
+        if (not isinstance(merged.get("reference"), dict)
+                and catalog_references and name in catalog_references):
+            merged["reference"] = catalog_references[name]
+        if classify(merged, invariant) != "lookup":
+            continue
+        reference = reference_of(merged)
+        names = [str(n) for n in (reference.get("lookupNames") or [])]
+        spec = {
+            "path": reference.get("path") or "",
+            "by": names,
+            "value": str(reference.get("lookupValue")),
+            "aliases": by_aliases(names),
+            "strategy": lookup_strategy(reference),
+        }
+        if reference.get("objectName"):
+            spec["objectName"] = str(reference["objectName"])
+        if reference.get("dependsOn"):
+            spec["dependsOn"] = [str(d) for d in reference["dependsOn"]]
+        specs[name] = spec
+    return specs
+
+
+def mark_lookup_fields(entry: dict, fields: list[dict], invariant: set) -> list[dict]:
+    """Flag the fields whose TS type must also accept a `LookupToken`.
+
+    Exactly the set `lookup_specs` generates helpers for, decided by the same
+    call, so the type and the helper cannot disagree about which fields are
+    resolvable.
+    """
+    catalog_references = {
+        f.get("name"): f["reference"]
+        for f in ((entry.get("inputSchema") or {}).get("fields") or [])
+        if isinstance(f.get("reference"), dict)
+    }
+    out = []
+    for field in fields:
+        merged = dict(field)
+        name = merged.get("name")
+        if not isinstance(merged.get("reference"), dict) and name in catalog_references:
+            merged["reference"] = catalog_references[name]
+        if classify(merged, invariant) == "lookup":
+            merged["__lookup"] = True
+        out.append(merged)
+    return out
+
+
+def emit_lookup_comment(specs: dict, symbol: str = "<Descriptor>") -> list[str]:
+    """The grep-able header — route 3 of the design's discoverability section.
+
+    The agents this surface is for run with Bash/Read/Grep and no language
+    server, so a `.byEmail` discoverable only by hovering is invisible. The
+    descriptor module is real source and is already opened to check a name, so
+    the lookups are stated there in prose beside the data.
+    """
+    lines = []
+    for field, spec in specs.items():
+        target = str(spec.get("objectName") or spec["path"]).split("?", 1)[0]
+        lines.append(f" * LOOKUP: `{field}` -> {target}.{spec['value']}")
+        aliases = spec["aliases"]
+        offered = [f"{a}()" for a in aliases.values()] if aliases else []
+        by_list = ", ".join(f"`{n}`" for n in spec["by"])
+        lines.append(f" *   by: {by_list}")
+        # THE WHOLE CALL, not just the method names. Naming `.byEmail` without
+        # the `lookup(Descriptor, 'field')` wrapper tells a reader that helpers
+        # exist but not how to reach one — measured: an agent read this comment,
+        # learned the helper names, and then made three separate reads of
+        # api.md to find the signature. One line here removes that trip.
+        first = next(iter(aliases.values()), None)
+        call = (f"lookup({symbol}, '{field}').{first}(value)" if first
+                else f"lookup({symbol}, '{field}').by('{spec['by'][0]}', value)"
+                if spec["by"] else f"lookup({symbol}, '{field}')")
+        lines.append(f" *   use: {call}")
+        if offered:
+            lines.append(f" *   also: {', '.join('.' + a for a in aliases.values())}"
+                         f"  ·  .by(name, value)")
+        else:
+            lines.append(" *   also: .by(name, value) only — aliases collided")
+        lines.append(f" *   strategy: {STRATEGY_PROSE[spec['strategy']]}")
+        if spec.get("dependsOn"):
+            lines.append(f" *   resolve first: {', '.join('`' + d + '`' for d in spec['dependsOn'])}")
+    return lines
+
+
+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",
+}
+
+
+def emit_event(
+    entry: dict,
+    in_fields: list[dict],
+    out_fields: list[dict],
+    input_tree: dict[str, TypeNode],
+    output_tree: dict[str, TypeNode],
+    name: str,
+    input_types: NamedTypeRegistry,
+    output_types: NamedTypeRegistry,
+    invariant: set | None = None,
+) -> list[str]:
+    """Emit a connector EVENT as a `triggerDescriptor()`, the shape `onEvent()` takes.
+
+    An event entry (`uipath.connector.event.<key>.<event>`, or the curated
+    `.trigger.` sibling) is not an action: `onEvent`/`waitForEvent` identify it by
+    `connector` + `event`, and a `descriptor()` const — the action shape this
+    generator used to emit for it — fails their positive descriptor test, so the
+    subscription lost its connector and event (EVENT_NO_CONNECTOR/EVENT_NO_EVENT)
+    and every author hand-wrote a `triggerDescriptor()` instead. The payload type
+    comes from `outputSchema`, and `where` from the entry's event parameters —
+    a GENERIC event's object is the author's `object` option, not a field here.
+
+    `where` was `Record<string, string>` while an event entry carried no
+    parameters to type it from. It does now, so a misspelt parameter is a
+    compile error rather than a `check` warning. The fallback stays for an
+    entry that declares NONE: that is either an event which genuinely takes no
+    parameters (HTTP Webhook — the connection is the subscription's whole
+    scope) or one nothing has described yet, and an empty interface would
+    refuse every key in both cases — wrongly in the second.
+    """
+    node_type = entry["nodeType"]
+    event_id = node_type.rsplit(".", 1)[-1]
+    connector_key = (entry.get("connector") or {}).get("key") or ""
+    label = (entry.get("display") or {}).get("label") or event_id
+    version = entry.get("version", "1.0.0")
+    generic = (entry.get("operation") or {}).get("activityType") == "GenericTrigger"
+    lines: list[str] = []
+    where_type = "Record<string, string>"
+    if in_fields:
+        where_type = f"{name}Where"
+        lines += emit_interface(
+            where_type, in_fields, all_optional=False,
+            named_types=input_types, field_tree=input_tree, is_input=True,
+        )
+        lines.append("")
+    lines += emit_interface(
+        f"{name}Outputs", out_fields, all_optional=True,
+        named_types=output_types, field_tree=output_tree,
+    )
+    lines.append("")
+    # A subscription's `where` values are resolved by `lookup()` exactly as a
+    # connector input's are, and `prepare --resolve` reads the same reference
+    # block — so the descriptor has to carry the same specs. Emitting none is
+    # what made `lookup(EmailReceived, 'parentFolderId').byDisplayName('Inbox')`
+    # fail with a bare TypeError while the curated sibling's `.byDisplayName`
+    # worked, on a field both forms declare identically.
+    specs = specs_from_fields(in_fields, invariant or set())
+    lines.append("/**")
+    lines.append(f" * {label} — {node_type}")
+    lines.append(" *")
+    if generic:
+        lines.append(" * A GENERIC event: it fires for ONE object of the connection (an entity, a")
+        lines.append(" * table, a custom object), so name it — `onEvent(" + name + ", { object: '<Object>' })`.")
+        lines.append(f" * `uip is triggers objects {connector_key} <EVENT> --connection-id <id>` lists them.")
+    else:
+        lines.append(f" * Start a flow on it with `onEvent({name}, {{ where: {{ … }} }})`, or pause for it")
+        lines.append(f" * with `waitForEvent({name}, {{ … }})`; `where` carries its event parameters.")
+    # INSIDE the block, as `emit_op` does. `emit_lookup_comment` returns bare
+    # ` * ` body lines; prepending them to the module instead emitted a comment
+    # with no `/**` opener, and every connector module holding an event with a
+    # lookup stopped parsing — which no assertion on substrings could see.
+    if specs:
+        lines.append(" *")
+        lines += emit_lookup_comment(specs, name)
+    lines.append(" */")
+    lines.append(f"export const {name} = triggerDescriptor<{where_type}, {name}Outputs>()({{")
+    lines.append(f"  connector: {json.dumps(connector_key)},")
+    lines.append(f"  event: {json.dumps(event_id)},")
+    lines.append(f"  version: {json.dumps(version)},")
+    lines.append(f"  displayName: {json.dumps(label)},")
+    lines += emit_lookups_block(specs)
+    lines.append("} as const);")
+    return lines
+
+
+def emit_op(
+    entry: dict,
+    v1def: dict,
+    input_tree: dict[str, TypeNode],
+    output_tree: dict[str, TypeNode],
+    name: str,
+    input_types: NamedTypeRegistry,
+    output_types: NamedTypeRegistry,
+    invariant: set | None = None,
+) -> list[str]:
+    node_type = entry["nodeType"]
+    action_id = node_type.rsplit(".", 1)[-1]
+    operation = entry.get("operation") or {}
+    is_generic_expanded = operation.get("activityType") == "GenericExpanded"
+    label = (entry.get("display") or {}).get("label") or action_id
+    version = entry.get("version", "1.0.0")
+    runtime = entry.get("runtime", {}) or {}
+    in_fields = descriptor_input_fields(entry, v1def)
+    out_fields = (entry.get("outputSchema") or {}).get("fields") or []
+
+    if is_event_node(node_type):
+        return emit_event(entry, in_fields, out_fields, input_tree, output_tree,
+                          name, input_types, output_types, invariant)
+
+    lines: list[str] = []
+    lines += emit_interface(
+        f"{name}Inputs", in_fields, all_optional=False,
+        named_types=input_types, field_tree=input_tree, is_input=True,
+    )
+    lines.append("")
+    lines += emit_interface(
+        f"{name}Outputs",
+        out_fields,
+        all_optional=True,
+        named_types=output_types,
+        field_tree=output_tree,
+    )
+    lines.append("")
+    # 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.
+    # Nothing in the type says so, and the Markdown page that does say it is a
+    # different artifact — so a developer reading types alone concludes the
+    # operation takes exactly what is written here. The doc comment is the only
+    # place the typed surface can carry it.
+    schema_action = operation.get("schemaAction") or {}
+    specs = lookup_specs(entry, v1def, invariant or set())
+    lookup_comment = emit_lookup_comment(specs, name) if specs else []
+    if operation.get("objectFromDiscovery"):
+        lines.append("/**")
+        lines.append(f" * {label} — {node_type}")
+        lines.append(" *")
+        lines.append(" * The object is chosen against the connection, so `Inputs` is empty")
+        lines.append(" * here. List the objects and read the chosen one's fields with")
+        lines.append(" * `uip is resources list` / `describe` before binding this node.")
+        if lookup_comment:
+            lines.append(" *")
+            lines += lookup_comment
+        lines.append(" */")
+    elif schema_action.get("parents"):
+        parents = ", ".join(f"`{x}`" for x in schema_action["parents"])
+        lines.append("/**")
+        lines.append(f" * {label} — {node_type}")
+        lines.append(" *")
+        lines.append(f" * `Inputs` carries only the fields that SELECT the schema ({parents}).")
+        lines.append(f" * The real set comes from the `{schema_action.get('name')}` design-time")
+        lines.append(" * action — describe with those values supplied to see it.")
+        if lookup_comment:
+            lines.append(" *")
+            lines += lookup_comment
+        lines.append(" */")
+    elif lookup_comment:
+        lines.append("/**")
+        lines.append(f" * {label} — {node_type}")
+        lines.append(" *")
+        lines += lookup_comment
+        lines.append(" */")
+    else:
+        lines.append(f"/** {label} — {node_type} */")
+    lines.append(f"export const {name} = descriptor<{name}Inputs, {name}Outputs>()({{")
+    lines.append(f"  nodeType: {json.dumps(node_type)},")
+    lines.append(f"  version: {json.dumps(version)},")
+    if is_generic_expanded and operation.get("objectName"):
+        lines.append(f"  objectName: {json.dumps(operation['objectName'])},")
+    if runtime.get("requiresConnection"):
+        lines.append("  requiresConnection: true,")
+    if runtime.get("requiresFolderKey"):
+        lines.append("  requiresFolderKey: true,")
+    lines += emit_lookups_block(specs)
+    lines.append("} as const);")
+    return lines
+
+
+def emit_lookups_block(specs: dict) -> list[str]:
+    """The descriptor's `lookups:` literal — a RUNTIME value, not a type.
+
+    `lookup()` reads `aliases` from it to build the `.byName()` family, so a
+    descriptor emitted without this block offers only the generic
+    `.by(name, value)` and any alias call fails as a plain `TypeError`.
+    """
+    if not specs:
+        return []
+    lines = ["  lookups: {"]
+    for field, spec in specs.items():
+        lines.append(f"    {key_literal(field)}: {{")
+        if spec.get("objectName"):
+            lines.append(f"      objectName: {json.dumps(spec['objectName'])},")
+        lines.append(f"      path: {json.dumps(spec['path'])},")
+        lines.append(f"      by: {json.dumps(spec['by'])},")
+        lines.append(f"      value: {json.dumps(spec['value'])},")
+        aliases = ", ".join(
+            f"{alias}: {json.dumps(name)}" for name, alias in spec["aliases"].items()
+        )
+        lines.append(f"      aliases: {{{(' ' + aliases + ' ') if aliases else ''}}},")
+        lines.append(f"      strategy: {json.dumps(spec['strategy'])},")
+        if spec.get("dependsOn"):
+            lines.append(f"      dependsOn: {json.dumps(spec['dependsOn'])},")
+        lines.append("    },")
+    lines.append("  },")
+    return lines
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--library", required=True)
+    ap.add_argument("--output", required=True)
+    ap.add_argument("--import", dest="imp", default="@uipath/maestro-builder-sdk",
+                    help="module specifier for `import { descriptor }`")
+    ap.add_argument("--connectors", default="", help="csv subset of connector keys (default: all)")
+    ap.add_argument(
+        "--include-generic-expanded", action="store_true",
+        help="emit typed descriptors for GenericExpanded entries (used by "
+             "small connection-resolved overlays; off for the bulk library)",
+    )
+    args = ap.parse_args()
+
+    lib = Path(args.library)
+    idx = json.loads((lib / "index.json").read_text())
+    # The invariant-collection ledger sits beside the index. Absent reads as
+    # empty, which is the permissive pre-ledger behaviour (see _lookups.py).
+    invariant = load_invariant_collections(lib)
+    subset = {c for c in args.connectors.split(",") if c} or None
+
+    # group Curated + http-request entries by connector key
+    by_conn: dict[str, list[dict]] = {}
+    for e in idx["entries"]:
+        if e.get("activityType") == "GenericExpanded" and not args.include_generic_expanded:
+            continue
+        # A generic EVENT's per-object variants share their template's nodeType
+        # and so would emit the same const twice — a module that does not
+        # compile. Only the template gets a descriptor, which is also the right
+        # surface: `onEvent(RecordCreated, { object: 'Message' })` names the
+        # object as an OPTION, so one descriptor serves every object. The
+        # variants still back `check` and `compile`, which resolve by object.
+        if (e.get("activityType") == "GenericTrigger" and e.get("objectName")
+                and not args.include_generic_expanded):
+            continue
+        ck = e["connectorKey"]
+        if subset and ck not in subset:
+            continue
+        by_conn.setdefault(ck, []).append(e)
+
+    out_dir = Path(args.output)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    written = 0
+    required_input_gaps: list[str] = []
+    # ONE symbol map for the whole run, shared with convert_library_to_md.py so
+    # the markdown can cite these names without re-deriving them (see
+    # _naming.symbol_index for why re-deriving cannot be made safe).
+    names = symbol_index(idx["entries"], args.include_generic_expanded)
+
+    for ck, entries in sorted(by_conn.items()):
+        input_types = NamedTypeRegistry(
+            suffix="Input", all_optional=False, merge_reused=False, is_input=True,
+        )
+        output_types = NamedTypeRegistry()
+        loaded: list[tuple[dict, dict, dict[str, TypeNode], dict[str, TypeNode]]] = []
+        for e in sorted(entries, key=lambda x: x["nodeType"]):
+            entry = json.loads((lib / e["path"]).read_text())
+            v1def_raw = json.loads((lib / e["path"].replace(".json", ".v1def.json")).read_text())
+            v1def = v1def_raw[0] if isinstance(v1def_raw, list) else v1def_raw
+            is_event = is_event_node(e["nodeType"])
+            operation_input_fields = mark_lookup_fields(
+                entry, descriptor_input_fields(entry, v1def), invariant,
+            )
+            output_fields = (entry.get("outputSchema") or {}).get("fields") or []
+            input_tree = build_type_tree(operation_input_fields)
+            # The required-input gap is a statement about a connector ACTION's
+            # inputs; an event's parameters are optional by construction (an
+            # unscoped subscription is legal, `check` only warns).
+            gap = None if is_event else required_input_gap(entry, input_tree)
+            if gap:
+                required_input_gaps.append(gap)
+            output_tree = build_type_tree(output_fields)
+            input_types.discover(input_tree)
+            output_types.discover(output_tree)
+            loaded.append((entry, v1def, input_tree, output_tree))
+
+        operations: list[str] = []
+        for entry, v1def, input_tree, output_tree in loaded:
+            operations += emit_op(
+                entry, v1def, input_tree, output_tree, names[entry["nodeType"]],
+                input_types, output_types, invariant,
+            )
+            operations.append("")
+
+        emitted_types = input_types.emit()
+        rendered = "\n".join(emitted_types + operations)
+        specifiers = [s for s in ("descriptor", "triggerDescriptor") if f"= {s}<" in rendered] or ["descriptor"]
+        for alias in ("ConnectorLookupValue", "ConnectorValue"):
+            if alias in rendered:
+                specifiers.append(f"type {alias}")
+        body: list[str] = [
+            f"import {{ {', '.join(specifiers)} }} from {json.dumps(args.imp)};", "",
+        ]
+        body += emitted_types
+        body += output_types.emit()
+        body += operations
+        (out_dir / f"{ck}.ts").write_text("\n".join(body).rstrip() + "\n")
+        written += 1
+    if required_input_gaps:
+        sys.exit(
+            "connector wrapper generation stopped:\n- "
+            + "\n- ".join(required_input_gaps)
+        )
+    print(f"generated {written} connector module(s) → {out_dir}")
+
+
+if __name__ == "__main__":
+    main()