@uipath/maestro-builder-sdk 5.2.0

package/dist/generators/prepare_connector.py

@@ -0,0 +1,1688 @@
+#!/usr/bin/env python3
+"""prepare-connector — fetch ONE connector op's FULL, connection-resolved schema
+into an ephemeral `./connectors-local/` overlay + a typed `.ts` (C4 / design §E).
+
+The baked library is tenant-agnostic, so schema-dynamic ops (Jira create-issue,
+Salesforce, …) ship only their connection-independent fields — the compiler then
+rejects the real fields (`fields.summary`, …) as unknown. `prepare-connector`
+closes that at author time: with a live connection it fetches the complete field
+schema for ONE op and writes the same artifacts the bulk generator produces, into
+a local overlay dir the compile CLIs auto-detect (`core/library.ts` overlay).
+
+    prepare_connector.py <key> <action> --connection-id <id> [--object <name>]
+                         [--all-objects] [-f NAME=VALUE ...] [--out ./connectors-local]
+
+Schema-dynamic ops resolve their fields from the VALUES of a few parent fields,
+not from the connection alone, so `-f` is what actually materializes them (Jira
+create-issue: 2 fields with no `-f`, 19 with project + issue type, a different
+22 for a different issue type). The values themselves have to be discovered
+first — that loop is the connector guide's, not this tool's.
+
+It's a single-op, connection-scoped slice of `generate_library_json.py`: it reuses
+that module's `registry_get` → `extract_canonical` → `enrich_entry` → `write_library`
+(routing all uip calls through `--connection-id` via `set_connection_id`), then
+runs `generate_connectors_ts.py` over the overlay. Calls ACCUMULATE — each prepared
+op merges into `--out` rather than replacing it.
+
+Needs a live connection + `uip`; it targets REAL/LIVE authoring (and the live eval
+rung), not the pure-offline arm. Custom (instance-specific) fields captured from
+one connection may not exist on another tenant at deploy — inherent to
+schema-dynamic connectors.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+import generate_library_json as gen  # noqa: E402
+import generate_connectors_ts as gen_ts  # noqa: E402
+import _resolve  # noqa: E402
+import _connections  # noqa: E402
+import _events  # noqa: E402
+import _objects  # noqa: E402
+from _lookups import load_invariant_collections  # noqa: E402
+
+
+def _variant_key(entry: dict) -> tuple[str, str, str]:
+    """Identity for one resolvable activity schema variant.
+
+    Generic object variants intentionally share a nodeType, so keying only by
+    nodeType makes the last prepared object overwrite every earlier one.
+    """
+    return (
+        entry.get("nodeType", ""),
+        entry.get("version", ""),
+        entry.get("objectName", ""),
+    )
+
+
+def _descriptor_overlay_path(path: str) -> str:
+    parts = Path(path).parts
+    if parts and parts[0] == "descriptors":
+        return Path(*parts).as_posix()
+    return (Path("descriptors") / Path(*parts)).as_posix()
+
+
+def _migrate_legacy_descriptor_roots(dst: str, entries: list[dict]) -> None:
+    legacy_roots = {
+        Path(entry["path"]).parts[0]
+        for entry in entries
+        if entry.get("path") and Path(entry["path"]).parts[0] != "descriptors"
+    }
+    for legacy_root in legacy_roots:
+        source_root = Path(dst) / legacy_root
+        if not source_root.is_dir():
+            continue
+        destination_root = Path(dst) / "descriptors" / legacy_root
+        for root, dirs, files in os.walk(source_root, topdown=False):
+            relative_root = Path(root).relative_to(source_root)
+            destination = destination_root / relative_root
+            destination.mkdir(parents=True, exist_ok=True)
+            for name in files:
+                os.replace(Path(root) / name, destination / name)
+            for name in dirs:
+                (Path(root) / name).rmdir()
+        source_root.rmdir()
+
+
+def merge_into(src: str, dst: str) -> None:
+    """Merge a freshly-written single-op library `src` into the overlay `dst`,
+    accumulating index entries by operation/object variant and copying files."""
+    os.makedirs(dst, exist_ok=True)
+    with open(os.path.join(src, "index.json")) as src_index:
+        src_idx = json.load(src_index)
+    dst_idx_path = os.path.join(dst, "index.json")
+    if os.path.exists(dst_idx_path):
+        with open(dst_idx_path) as dst_index:
+            dst_idx = json.load(dst_index)
+    else:
+        dst_idx = {"schemaVersion": gen.SCHEMA_VERSION, "entries": []}
+    dst_entries = dst_idx.get("entries", [])
+    _migrate_legacy_descriptor_roots(dst, dst_entries)
+    for entry in dst_entries:
+        entry["path"] = _descriptor_overlay_path(entry["path"])
+    by_variant = {
+        _variant_key(e): e for e in dst_entries
+    }
+    for e in src_idx.get("entries", []):
+        # Re-preparing the same object refreshes it; preparing a different object
+        # accumulates a sibling variant under the shared generic nodeType.
+        e["path"] = _descriptor_overlay_path(e["path"])
+        by_variant[_variant_key(e)] = e
+    dst_idx["entries"] = sorted(
+        by_variant.values(),
+        key=lambda e: (
+            e.get("connectorKey", ""),
+            e.get("nodeType", ""),
+            e.get("version", ""),
+            e.get("objectName", ""),
+            e.get("path", ""),
+        ),
+    )
+    with open(dst_idx_path, "w") as f:
+        json.dump(dst_idx, f, indent=2)
+    for root, _dirs, files in os.walk(src):
+        for name in files:
+            if name == "index.json":
+                continue
+            rel = os.path.relpath(os.path.join(root, name), src)
+            rel = _descriptor_overlay_path(rel)
+            out = os.path.join(dst, rel)
+            os.makedirs(os.path.dirname(out), exist_ok=True)
+            shutil.copyfile(os.path.join(root, name), out)
+
+
+def _missing_generic_schema_message(
+    operation: str, object_name: str | None = None
+) -> str:
+    target = (
+        f'object "{object_name}" was not found or does not support action '
+        f'"{operation}"'
+        if object_name
+        else f'no object in the connected catalog supports action "{operation}"'
+    )
+    return (
+        f"prepare-connector: {target}. A connection-resolved schema requires a "
+        "working live connection id. For an offline/validate-only flow that does "
+        "not need connection-specific fields, use the baked connector descriptor "
+        "without custom fields instead."
+    )
+
+
+def _object_action_specs(registry_path: str) -> list[tuple[str, list[str]]]:
+    """Return each api-type ObjectAction and its ordered parent-field names."""
+    try:
+        with open(registry_path) as registry_file:
+            node = json.load(registry_file)["Data"]["Node"]
+        actions = (
+            (node.get("connectorMethodInfo") or {})
+            .get("design") or {}
+        ).get("actions") or []
+    except (OSError, json.JSONDecodeError, KeyError, TypeError):
+        return []
+
+    specs = []
+    for action in actions:
+        if not isinstance(action, dict) or action.get("actionType") != "api":
+            continue
+        action_name = action.get("name")
+        if not isinstance(action_name, str) or not action_name:
+            continue
+        refs = [
+            rule.get("refFieldName")
+            for rule in (action.get("rules") or [])
+            if not rule.get("isCleared") and rule.get("refFieldName")
+        ]
+        if refs:
+            specs.append((action_name, refs))
+    return specs
+
+
+def _object_action_request(
+    registry_path: str, parent_fields: dict[str, str]
+) -> dict | None:
+    """Build the design-time schema replay request for a prepared operation.
+
+    The connection-resolved field list is only half of a schema-dynamic
+    connector configuration. Studio Web also persists the ObjectAction and the
+    parent values that produced that field list so it can replay the same
+    schema. The registry owns the action name and rule order; ``-f`` owns the
+    values.
+    """
+    if not parent_fields:
+        return None
+    for action_name, refs in _object_action_specs(registry_path):
+        if not refs or set(refs) != set(parent_fields):
+            continue
+        return {
+            "objectActionName": action_name,
+            "parameterValues": [
+                [name.replace(".", "_sub_"), parent_fields[name]]
+                for name in refs
+            ],
+        }
+    return None
+def _registry_actions(connector_key: str) -> list[str]:
+    """The action ids the REGISTRY serves for one connector, newest catalog.
+
+    `registry search` rather than a cached index: this runs only on the failure
+    path, where the whole question is what the tenant actually serves.
+    """
+    result = subprocess.run(
+        ["uip", "maestro", "flow", "registry", "search", connector_key, "--output", "json"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return []
+    try:
+        data = json.loads(result.stdout).get("Data") or []
+    except json.JSONDecodeError:
+        return []
+    prefix = f"uipath.connector.{connector_key}."
+    return sorted(
+        {
+            node_type[len(prefix):]
+            for entry in data
+            if isinstance(entry, dict)
+            for node_type in [entry.get("NodeType") or ""]
+            # Exact prefix only: the same search returns
+            # `uipath.agent.resource.tool.connector.<key>.<action>` and
+            # `uipath.connector.trigger.<key>.<event>`, which are not actions of
+            # this node and would read as alternatives an author could pass.
+            if node_type.startswith(prefix) and "." not in node_type[len(prefix):]
+        }
+    )
+
+
+def _closest_actions(action: str, candidates: list[str]) -> list[str]:
+    """Candidates ranked by shared hyphen tokens, best first.
+
+    Token overlap rather than edit distance because the two namespaces differ by
+    whole words, not typos: the baked library's `list-all-records` against the
+    registry's `list-records`.
+    """
+    wanted = set(action.split("-"))
+    scored = [
+        (len(wanted & set(c.split("-"))), -len(c), c)
+        for c in candidates
+        if wanted & set(c.split("-"))
+    ]
+    return [c for _, _, c in sorted(scored, reverse=True)]
+
+
+def _unresolved_action_message(connector_key: str, action: str, node_type: str) -> str:
+    """What to do when the action id is not a registry key.
+
+    NOT auto-substituted, deliberately. The baked action id and the registry key
+    are different namespaces — a generic op is `list-all-records` in the library
+    and materializes per object, while the registry serves `list-records` — and
+    guessing between them would emit a node both offline validators accept and
+    the runtime dispatches to the wrong operation. So this names the candidates
+    and lets the author choose.
+
+    The message earns its length: in the `generic-dynamic-node` eval the bare
+    "check the key/action" version sent an agent to page 18,037 objects through
+    `uip is resources list` for six turns instead of retrying with the right id.
+    """
+    actions = _registry_actions(connector_key)
+    lines = [
+        f"prepare-connector: `registry get {node_type}` found no such node.",
+        "",
+        "The baked library's action id is not always the registry's key — a Generic",
+        "op is `list-all-records` in the library and materializes per object, while",
+        "the registry serves the un-expanded form. Re-run with a registry action id.",
+    ]
+    if not actions:
+        lines += [
+            "",
+            f"`registry search {connector_key}` returned nothing. If the catalog looks",
+            "stale, refresh it first: `uip maestro flow registry pull --force`.",
+        ]
+        return "\n".join(lines)
+    close = _closest_actions(action, actions)
+    if close:
+        lines += ["", f"Closest to \"{action}\": {', '.join(close[:3])}"]
+    lines += ["", f"All actions the registry serves for {connector_key}:", *(f"  {a}" for a in actions)]
+    return "\n".join(lines)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Prepare a connector op's full schema into ./connectors-local")
+    ap.add_argument("key", help="connector key, e.g. uipath-atlassian-jira")
+    ap.add_argument("action", help="op action id, e.g. create-issue")
+    # OPTIONAL. `prepare` already knows the connector; making the author find
+    # its connection id by hand is work the command can do from what it has.
+    ap.add_argument(
+        "--connection-id", default=None,
+        help="a live connection id. Omit it and the connection is discovered "
+             "from `uip is connections list` — your folder first, the tenant "
+             "second — and its id AND folder key are written into bindings.json.")
+    ap.add_argument(
+        "--connection", default=None, metavar="NAME",
+        help="pick the connection by name when several match. Several "
+             "connections for one connector are NOT interchangeable, so an "
+             "ambiguous match is an error rather than a guess.")
+    ap.add_argument(
+        "--bindings", default="./bindings.json",
+        help="bindings file to add the discovered connection to "
+             "(default: ./bindings.json). Additive and idempotent.")
+    ap.add_argument(
+        "--bind-connection", default=None, metavar="NAME",
+        help="symbolic connection name to bind (default: the connector's last "
+             "dash-segment, e.g. `slack` for uipath-salesforce-slack)")
+    ap.add_argument(
+        "--bind-folder", default="shared",
+        help="symbolic folder name to bind (default: shared)")
+    ap.add_argument(
+        "--no-bindings", action="store_true",
+        help="discover the connection but do not touch bindings.json")
+    objects = ap.add_mutually_exclusive_group()
+    objects.add_argument(
+        "--object",
+        help="expand one connection-discovered object for a Generic action",
+    )
+    objects.add_argument(
+        "--all-objects",
+        action="store_true",
+        help="expand every connection-discovered object for a Generic action",
+    )
+    ap.add_argument(
+        "-f", "--field", action="append", default=[], metavar="NAME=VALUE",
+        help="a PARENT-field value that resolves the schema (repeatable), e.g. "
+             "-f fields.project.key=IN -f fields.issuetype.id=10620. Pass every "
+             "parent the operation declares: a partial set is rejected. See the "
+             "connector guide's parent-field loop.",
+    )
+    ap.add_argument("--out", default="./connectors-local", help="overlay dir (default: ./connectors-local)")
+    ap.add_argument("--source", default=None,
+                    help="the .flow.ts whose import should be repointed at the "
+                         "prepared descriptor (default: the one that imports "
+                         "this connector, when exactly one does)")
+    ap.add_argument("--no-source-rewrite", action="store_true",
+                    help="print the import line instead of editing the source")
+    ap.add_argument("--version", default=None, help="pin an op version (default: newest)")
+    ap.add_argument("--import", dest="imp", default="../sdk/flow-sdk.js",
+                    help="module specifier for the emitted .ts (default: ../sdk/flow-sdk.js)")
+    ap.add_argument(
+        "--resolve", action="append", default=[], metavar="FIELD:BY=VALUE",
+        help="resolve a lookup field to the id the connector wants, e.g. "
+             "--resolve channel:profile.email=someone@example.com. Repeatable; "
+             "order does not matter (a dependsOn prerequisite is resolved first). "
+             "Results land in <out>/resolutions.json, which compile reads.")
+    ap.add_argument(
+        "--refresh-lookups", action="store_true",
+        help="re-resolve lookups that are already recorded. Default is to leave "
+             "them alone: a resolved id is a snapshot either way, and silently "
+             "changing one during an unrelated prepare is worse than a stale one "
+             "you can see in a diff.")
+    ap.add_argument("--json-only", action="store_true",
+                    help="write the JSON overlay only — skip the typed .ts descriptor "
+                         "(the overlay alone already makes compile accept the fields; "
+                         "the A arm of the typed-vs-JSON study)")
+    args = ap.parse_args()
+
+    parent_fields = _parse_fields(args.field)
+    # Set when this run must NOT overwrite an already-prepared schema; see
+    # `_keep_prepared_schema`. Reported after the summary line, so the field
+    # count it explains has already been printed.
+    kept_schema: tuple[int, int] | None = None
+
+    # Discover the connection when the caller did not name one, and record it in
+    # bindings.json so the author never has to look up either key. This is the
+    # step that removes 4-7 tool calls per task: listing connections, filtering
+    # them, and then hunting Orchestrator for a folder key that was on the
+    # connection record all along.
+    if not args.connection_id:
+        try:
+            found = _connections.discover_connection(args.key, args.connection)
+        except _connections.ConnectionError_ as error:
+            sys.exit(f"prepare-connector: {error}")
+        args.connection_id = str(found["Id"])
+        print(f"  connection: {found.get('Name')} ({args.connection_id})")
+    else:
+        # An explicit id gets the same gate discovery applies. Without it a
+        # `State: Failed` connection went straight to `is resources describe`,
+        # which answers Success with NO request fields for a connection the
+        # tenant cannot reach — so the overlay was written with zero body
+        # inputs, reported as "0 input field(s)" success, and the next compile
+        # rejected every real field as unknown (skill-flow-ixp-routing-negative/
+        # sf-update: Salesforce update-record on a Failed connection, 0 fields;
+        # the Enabled connection carries 13, StageName among them).
+        try:
+            found = _connections.lookup_connection(args.key, args.connection_id)
+        except _connections.ConnectionError_ as error:
+            sys.exit(f"prepare-connector: {error}")
+        print(f"  connection: {found.get('Name')} ({args.connection_id})")
+
+    # Record the connection in bindings.json on BOTH routes. Until 3.30.5 only
+    # discovery wrote it: an explicit `--connection-id` — the one way past two
+    # connections that share a name — left the author hand-writing the id and
+    # folder key, and the hint below printed `<binding-name>` placeholders that
+    # went straight into source and bindings.json (measured on the eval corpus:
+    # angle-bracket and all-zero "GUIDs" in 16 archived bindings.json files).
+    if not args.no_bindings:
+        # Taken before the first write so a later refusal can undo exactly this
+        # command's changes, and only them.
+        _snapshot_bindings(args)
+        symbolic = args.bind_connection or args.key.rsplit("-", 1)[-1]
+        try:
+            wrote_conn, wrote_folder = _connections.merge_bindings(
+                args.bindings, found, symbolic, args.bind_folder)
+        except _connections.ConnectionError_ as error:
+            sys.exit(f"prepare-connector: {error}")
+        args._bound_connection = symbolic
+        args._bound_folder = args.bind_folder
+        for name, changed in ((symbolic, wrote_conn),
+                              (args.bind_folder, wrote_folder)):
+            if changed:
+                print(f"  bindings: {name} -> {args.bindings}")
+
+    gen.set_connection_id(args.connection_id)
+    gen.set_parent_fields(parent_fields)
+    gen.reset_failed_field_describes()
+    node_type = f"uipath.connector.{args.key}.{args.action}"
+
+    with tempfile.TemporaryDirectory() as tmp:
+        cache = os.path.join(tmp, "reg")
+        is_cache = os.path.join(tmp, "is")
+        os.makedirs(cache)
+        os.makedirs(is_cache)
+
+        path = gen.registry_get(node_type, cache, quiet=True)
+        if not path:
+            # Not an activity. Connector EVENTS live one namespace over —
+            # `uipath.connector.trigger.<key>.<event>` / `.event.<key>.<event>`
+            # — and their registry definition only answers with a connection,
+            # which this command has by now. Same loop, different twin pair.
+            if _prepare_event(args, tmp, cache):
+                return
+            sys.exit(_unresolved_action_message(args.key, args.action, node_type))
+        # The registry's own declaration of parent inputs, read while the file
+        # still exists: `path` lives in this temporary directory.
+        declared_parents = _declared_parents(path)
+        entry = gen.extract_canonical(path)
+        if not entry:
+            sys.exit(f"prepare-connector: no canonical entry for {node_type} (unexpected registry shape).")
+        if args.version:
+            entry["version"] = args.version
+        if parent_fields:
+            request = _object_action_request(path, parent_fields)
+            if not request:
+                expected = [
+                    ", ".join(fields)
+                    for _name, fields in _object_action_specs(path)
+                ]
+                expected_text = " or ".join(expected) or "<none advertised>"
+                sys.exit(
+                    "prepare-connector: parent-field names must match one "
+                    "api-type ObjectAction exactly. Given: "
+                    f"{', '.join(parent_fields)}. Expected: {expected_text}."
+                )
+            entry["operation"]["customFieldsRequestDetails"] = request
+
+        is_expandable_generic = (
+            entry["operation"].get("activityType") == "Generic"
+            and not gen._is_http_passthrough(entry)
+        )
+        if is_expandable_generic:
+            if not args.object and not args.all_objects:
+                sys.exit(
+                    "prepare-connector: this is a Generic action; pass "
+                    "--object <name> to prepare one object or --all-objects "
+                    "to prepare the full connected catalog."
+                )
+            templates = gen._generic_templates_by_op([entry]).get(args.key, {})
+            if args.object:
+                # The author's name, not necessarily the API's: `Company__C`
+                # from a prompt is `Company__c` in the catalog, and equality
+                # used to dead-end on exactly that. Match it deterministically
+                # BEFORE expansion — expansion re-reads the same file-cached
+                # catalog, so the match costs no extra network.
+                verb = next(iter(templates)) if len(templates) == 1 else None
+                requested = args.object
+                matched_row = _match_catalog_object(
+                    args.key, args.object, verb, is_cache
+                )
+                if matched_row is not None:
+                    args.object = matched_row.get("Name") or args.object
+                    args._object_requested = requested
+                    args._object_row = matched_row
+                    args._object_verb = verb
+            selected = None if args.all_objects else {args.object}
+            prepared_entries = gen.expand_generic_for_connector(
+                args.key, templates, is_cache, object_names=selected
+            )
+            if not prepared_entries:
+                operation = entry["operation"].get("name") or args.action
+                sys.exit(_missing_generic_schema_message(
+                    operation,
+                    None if args.all_objects else args.object,
+                ))
+        else:
+            if args.object or args.all_objects:
+                sys.exit(
+                    "prepare-connector: --object/--all-objects apply only to "
+                    "Generic connector actions."
+                )
+            gen.enrich_entry(entry, is_cache)  # full schema via --connection-id
+            prepared_entries = [entry]
+
+        tmplib = os.path.join(tmp, "lib")
+        gen.write_library(tmplib, prepared_entries, {entry["nodeType"]: path})
+        kept_schema = _keep_prepared_schema(
+            args, entry["nodeType"], tmplib, parent_fields,
+        )
+        if kept_schema is None:
+            merge_into(tmplib, args.out)
+
+    # The object decision is the FIRST resolution — recorded before any
+    # lookup rows, because it is their prerequisite: the schema the lookups
+    # were generated from is the one this match selected.
+    if getattr(args, "_object_row", None) is not None:
+        try:
+            ledger_path = _objects.record_object_resolution(
+                args.out, node_type, args._object_requested,
+                args._object_row, args._object_verb,
+            )
+        except _objects.LedgerError as error:
+            sys.exit(f"prepare-connector: {error}")
+        print(f"  object: {args._object_requested} -> {args.object} "
+              f"recorded in {ledger_path}")
+
+    if args.resolve:
+        _write_resolutions(args, node_type)
+
+    _regenerate_descriptors(args)
+    n_fields = _count_input_fields(args.out, entry["nodeType"], args.object)
+    n_variants = len(prepared_entries)
+    ts_note = "JSON overlay only" if args.json_only else f"overlay + {args.key}.ts"
+    field_note = _input_field_note(n_fields)
+    # The describe is the evidence, not the finished field count. A rejected
+    # parent set leaves `enrich_entry` returning the registry-DECLARED fields,
+    # so the overlay looks plausible (measured: project-only on Jira
+    # create-issue writes 3 declared fields) while the real answer was a
+    # Failure. Surface the CLI's own message instead of that quiet success.
+    failures = gen.failed_field_describes()
+    if args.field and (failures or n_fields == 0):
+        sys.exit(_rejected_parent_fields_message(args.field, failures))
+    print(
+        f"prepare-connector: {node_type} → {args.out}/ "
+        f"({ts_note}, {n_variants} variant(s), {field_note})"
+    )
+    if kept_schema is not None:
+        kept, discarded = kept_schema
+        print(
+            f"prepare-connector: kept the prepared schema for {args.action} "
+            f"({kept} input field(s)) — this run passed no -f, so its schema "
+            f"action did not run and the unresolved entry ({discarded} field(s)) "
+            f"would have replaced it. The resolutions above are recorded either "
+            f"way; re-run with -f to refresh the schema itself."
+        )
+    _print_lookup_vocabulary(args, node_type)
+    # Whether this operation has parent fields is answered by what we just
+    # prepared, not by a catalog flag: `extract_canonical` does not run the bulk
+    # discovery-marking pass, so `requiresConnectionForSchema` is still False
+    # here. A reference path carrying a {placeholder} IS the declaration.
+    parents, parent_only = _parent_fields(
+        args.out, entry["nodeType"], args.object
+    )
+    if parent_only and args.field:
+        # The set was SHAPED right (nothing was rejected) but resolved to
+        # nothing new, so at least one value does not exist on this connection.
+        sys.exit(
+            "prepare-connector: the parent-field values did not resolve — the "
+            "prepared schema is still parent-only (" + ", ".join(parents) +
+            f"). Given: {', '.join(args.field)}. The names were accepted, so a "
+            "VALUE is wrong for this connection: resolve each one against this "
+            "connection (ids are parent-scoped — a Jira issue-type id is valid "
+            "only inside its project) rather than reusing one from another "
+            "project, connection, or task."
+        )
+    # stdout is block-buffered under a pipe; flush so a `2>&1` reader sees the
+    # note after the overlay line it refers to, not before it.
+    sys.stdout.flush()
+    # Whether the schema action RAN is decided by its inputs, not by its
+    # output: every parent it names must have arrived as `-f`. Both earlier
+    # tests read the result instead, and between them let Jira's `create-issue`
+    # through silently — parent-only PLUS its own `key`, so "every field is a
+    # parent" was false and the registry declares no api-type ObjectAction for
+    # it either. The overlay then carried 3 of 19 inputs, `prepare` printed a
+    # clean "next:", and the author found out when `compile` refused `summary`.
+    # Union of both declaration sites so an overlay that omits `schemaAction`
+    # still gets the registry's answer.
+    action_parents = _schema_action_parents(args.out, entry["nodeType"], args.object)
+    action_parents += [
+        name for name in declared_parents if name not in action_parents
+    ]
+    missing = [name for name in action_parents if name not in parent_fields]
+    # Silent when the schema was KEPT: the note's premise is that the overlay
+    # now carries only the unresolved entry, and it does not — the richer one
+    # survived. Telling an author to "materialize the full field set" they are
+    # already holding sends them round a loop that changes nothing.
+    if missing and kept_schema is None:
+        # A schema parent IS a lookup: the id `--resolve` just recorded is the
+        # very value `-f` wants. The generic "resolve X and re-run" note made
+        # an agent run this prepare twice and hand-copy the id between the two
+        # commands (observed: 10732 retyped from the first run's output into
+        # the second run's -f). When every parent already has a recorded
+        # resolution, print the re-run ready to paste instead.
+        resolved_parents = _resolved_parent_values(args.out, node_type, action_parents)
+        given = " ".join(
+            f"-f {name}={parent_fields[name]}"
+            for name in action_parents
+            if name in parent_fields
+        )
+        if set(resolved_parents) == set(action_parents):
+            fields_arg = " ".join(
+                f"-f {name}={resolved_parents[name]}" for name in action_parents
+            )
+            print(
+                "prepare-connector: note: this operation resolves its fields "
+                "from the VALUES of parent inputs, and the resolutions above "
+                "ARE those values. Re-run to materialize the full field set:\n"
+                f"  npx flow-sdk registry prepare {args.key} {args.action} "
+                f"{fields_arg}",
+                file=sys.stderr,
+            )
+        else:
+            example = " ".join(
+                f"-f {name}={parent_fields.get(name, '<value>')}"
+                for name in action_parents
+            )
+            print(
+                "prepare-connector: note: this operation resolves its fields "
+                "from the VALUES of " + ", ".join(action_parents) +
+                " (its schema action), and " +
+                ("none were given" if len(missing) == len(action_parents)
+                 else f"{', '.join(missing)} " +
+                      ("was" if len(missing) == 1 else "were") + " not" +
+                      (f" (given: {given})" if given else "")) +
+                ", so the overlay above carries only the unresolved schema — a "
+                "body field the object declares is not there yet and compile "
+                "will refuse it as an unknown input. Re-run passing ALL of them "
+                "as -f NAME=VALUE (a partial set is rejected):\n"
+                f"  npx flow-sdk registry prepare {args.key} {args.action} {example}",
+                file=sys.stderr,
+            )
+    if not args.json_only:
+        # The hint printed the placeholders `<binding-name>` /
+        # `<folder-binding-name>` even when this run had just WRITTEN both
+        # bindings and knew their names. Print what it bound, so the last line
+        # of output is a call the reader can paste.
+        usage = _descriptor_usage(
+            args.out, args.key,
+            getattr(args, "_bound_connection", None) or "<binding-name>",
+            getattr(args, "_bound_folder", None) or "<folder-binding-name>",
+        )
+        repointed = _repoint_source(args, args.key)
+        if repointed and repointed[0].startswith("repointed "):
+            # The edit is DONE, so telling the author to make it is now false.
+            # Drop the import line and keep the rest, which still teaches the
+            # call shape and the resolved-identity rule.
+            usage = [line for line in usage if not line.startswith("import {")]
+        for line in repointed:
+            print(f"prepare-connector: {line}")
+        for line in usage:
+            print(f"prepare-connector: next: {line}")
+
+
+def _print_lookup_vocabulary(args, node_type: str) -> None:
+    """Print the lookup table for the operation just prepared.
+
+    The markdown catalog renders this table for BAKED schemas; a schema that
+    only exists because this command ran has no page to carry it, so the
+    command itself is where the vocabulary first becomes knowable. Without it
+    the author meets a custom object's lookup fields one `check` warning at a
+    time instead of all at once, here, beside the import line.
+    """
+    specs = _lookup_specs_from_overlay(args.out, node_type, args.object)
+    if not specs:
+        return
+    where = f" ({args.object})" if args.object else ""
+    print(f"prepare-connector: lookup fields on {args.action}{where} — "
+          "these hold ids; author lookup(...) and resolve, don't paste one:")
+    shown = list(specs.items())[:12]
+    for field, spec in shown:
+        by = " | ".join(spec.get("by") or []) or "?"
+        target = f"{spec.get('objectName') or spec.get('path') or '?'}.{spec.get('value') or 'id'}"
+        print(f"  {field} — matches on {by}, sends {target}")
+    if len(specs) > len(shown):
+        print(f"  … and {len(specs) - len(shown)} more")
+    field, spec = shown[0]
+    by = (spec.get("by") or ["id"])[0]
+    obj = f" --object {args.object}" if args.object else ""
+    print("prepare-connector: resolve with: "
+          f"npx flow-sdk registry prepare {args.key} {args.action}{obj} "
+          f"--resolve {field}:{by}=<value>")
+
+
+def _resolved_parent_values(out_dir: str, node_type: str, parents) -> dict:
+    """`{parent: resolved id}` for every parent with a recorded resolution.
+
+    Read from the ledger just written, so the paste-ready `-f` re-run carries
+    the ids THIS invocation resolved — never guessed, never retyped.
+    """
+    try:
+        ledger = _objects.read_ledger(out_dir)
+    except _objects.LedgerError:
+        return {}
+    wanted = set(parents)
+    out: dict = {}
+    for key, row in (ledger.get("resolutions") or {}).items():
+        try:
+            key_node, field, _by, _match = json.loads(key)
+        except (ValueError, TypeError):
+            continue
+        if key_node == node_type and field in wanted:
+            out[field] = row.get("value")
+    return {k: v for k, v in out.items() if v not in (None, "")}
+
+
+def _match_catalog_object(key: str, wanted: str, verb: str | None, is_cache: str):
+    """The catalog row `--object` names, matched by `_objects.match_object`.
+
+    Returns the row, or None when the catalog itself is unavailable — that
+    failure belongs to expansion, whose message already covers it. Every
+    refusal past the name rungs (zero matches, substring — unique or
+    ambiguous) is retried once against a refreshed catalog before it is
+    believed: the `uip is resources list` cache never invalidates itself, so
+    an object the tenant gained after the cache was written reads as
+    nonexistent (measured: 18 objects stale vs 864 fresh on
+    uipath-salesforce-sfdc). The one exception — which refusal is retriable is
+    the exception's call, not this loop's — is ambiguity WITHIN a name rung:
+    two case-variant names are a fact a refresh will not change.
+    """
+    rows = gen.is_resources_list(key, is_cache, operation=verb) or []
+    if not rows:
+        return None
+    for attempt in ("cached", "refreshed"):
+        try:
+            row, note = _objects.match_object(rows, wanted, verb)
+        except _objects.ObjectMatchError as error:
+            if attempt == "cached" and error.retriable:
+                rows = gen.is_resources_list(
+                    key, is_cache, operation=verb, refresh=True
+                ) or rows
+                continue
+            sys.exit(f"prepare-connector: {error}")
+        if note:
+            print(f"  object: {note}")
+        return row
+    return None
+
+
+def _refuse_unless_byoa_connection(args) -> None:
+    """Refuse a standard connection on an event object that requires BYOA.
+
+    V1 measured the failure this prevents: the trigger deploys and then faults
+    at runtime with a webhook error naming nothing about connections. The
+    requirement is knowable now, so it is refused now, with the connections
+    that WOULD work.
+
+    A refusal must leave nothing behind. Stage 0 has already written this
+    connection into `bindings.json` by the time the event's own metadata says
+    it is the wrong KIND of connection — the BYOA fact needs a connection to
+    discover — so the file is restored to exactly what it was before the
+    refusal is raised. Otherwise the overlay keeps pointing at a connection
+    this command just forbade.
+    """
+    try:
+        rows = _connections.byoa_connections(args.key)
+    except _connections.ConnectionError_ as error:
+        # A listing that FAILED is not a tenant with no BYOA connections; the
+        # remedies are opposite and confusing them sends the reader to create
+        # a connection they may already have.
+        _restore_bindings(args)
+        sys.exit(
+            f"prepare-connector: this event object requires a BYOA "
+            f"(bring-your-own-app) connection, and the BYOA listing needed to "
+            f"check {args.connection_id} against it failed: {error}"
+        )
+    if args.connection_id in {str(row.get("Id")) for row in rows}:
+        return
+    _restore_bindings(args)
+    sys.exit(
+        f"prepare-connector: this event object requires a BYOA "
+        f"(bring-your-own-app) connection, and {args.connection_id} is not "
+        f"one. A standard connection deploys and then faults at runtime with "
+        f"an unrelated-looking webhook error. BYOA {args.key} connections:\n"
+        f"{_connections.byoa_listing(rows, args.key)}"
+    )
+
+
+def _event_operation(operation: dict) -> str:
+    """The operation key every trigger API takes.
+
+    NOT `operation.name`: that is the object's CRUD verb (`Create` on outlook
+    `email-received`), while the event's own operation is `EMAIL_RECEIVED`,
+    which `extract_canonical` stamps as `eventOperation` from the manifest's
+    `model.context`. `name` happens to fall back to the same context value
+    when the manifest omits `connectorMethodInfo.operation`, so reading it
+    works or silently queries the WRONG operation depending on which fallback
+    rung a given connector's manifest exercises — and both generation passes
+    already key on `eventOperation`.
+    """
+    return str(operation.get("eventOperation") or operation.get("name") or "")
+
+
+def _snapshot_bindings(args) -> None:
+    """Remember `bindings.json` byte-for-byte, before stage 0 touches it."""
+    path = getattr(args, "bindings", None)
+    if not path:
+        return
+    try:
+        with open(path, "rb") as handle:
+            args._bindings_before = handle.read()
+    except OSError:
+        args._bindings_before = None      # the file did not exist
+
+
+def _restore_bindings(args) -> None:
+    """Put `bindings.json` back exactly as `_snapshot_bindings` found it."""
+    path = getattr(args, "bindings", None)
+    if not path or not hasattr(args, "_bindings_before"):
+        return
+    before = args._bindings_before
+    try:
+        if before is None:
+            if os.path.exists(path):
+                os.remove(path)
+        else:
+            with open(path, "wb") as handle:
+                handle.write(before)
+    except OSError as error:
+        print(f"  WARN: could not restore {path} after refusing the "
+              f"connection: {error}", file=sys.stderr)
+
+
+def _prepare_event(args, tmp: str, cache: str) -> bool:
+    """Prepare a connector EVENT — the trigger/wait twin of an activity.
+
+    Returns False when `<key> <action>` is not an event either, so the caller
+    can raise the ordinary unknown-action error. Everything else is handled
+    here: the overlay entry is stored under the WAIT form
+    (`uipath.connector.event.<key>.<action>`) because the registry only
+    enriches the START form and the library derives the start form from its
+    wait sibling (`deriveTriggerForm`) — one stored variant serves both node
+    roles.
+    """
+    trigger_nt = f"uipath.connector.trigger.{args.key}.{args.action}"
+    event_nt = f"uipath.connector.event.{args.key}.{args.action}"
+    path = gen.registry_get(trigger_nt, cache)
+    if not path:
+        return False
+    entry = gen.extract_canonical(path)
+    if not entry:
+        return False
+    if args.field:
+        sys.exit("prepare-connector: -f parent fields apply to activities; "
+                 "a connector event has none.")
+    if args.all_objects:
+        sys.exit("prepare-connector: --all-objects applies to Generic "
+                 "activities; prepare a generic EVENT for one --object.")
+    with open(path, encoding="utf-8") as handle:
+        raw = json.load(handle)
+    node = (raw.get("Data") or {}).get("Node") or raw.get("Node") or {}
+    op = entry["operation"]
+    operation = _event_operation(op)
+    generic = op.get("activityType") == "GenericTrigger"
+
+    # The objects listing is the generic catalog AND the per-object fact sheet
+    # (BYOA, webhook visibility, bucket-scoped Parameters). For a curated
+    # event it is advisory — the definition already carries the sections — so
+    # a listing failure degrades to a warning there and is fatal only where
+    # it is the only source of truth.
+    try:
+        rows = _events.triggers_objects(args.key, operation, args.connection_id)
+    except _events.EventDiscoveryError as error:
+        if generic:
+            sys.exit(f"prepare-connector: {error}")
+        rows = []
+        print(f"  WARN: {error}", file=sys.stderr)
+
+    describe = None
+    object_row = None
+    requested_object = None
+    if generic:
+        if not args.object:
+            sample = ", ".join(
+                str(row.get("Name")) for row in rows[:8] if row.get("Name"))
+            sys.exit(
+                f"prepare-connector: {args.action} is a Generic event — it "
+                f"fires for ONE object of the connection. Pass --object "
+                f"<name>. This connection's objects include: {sample}"
+                + (" …" if len(rows) > 8 else "")
+            )
+        # The author's name, not necessarily the API's — same ladder, same
+        # refusal semantics as a Generic activity. The listing is live (no
+        # CLI-side cache), so there is nothing to refresh on a miss.
+        try:
+            object_row, note = _objects.match_object(rows, args.object, operation)
+        except _objects.ObjectMatchError as error:
+            sys.exit(f"prepare-connector: {error}")
+        if note:
+            print(f"  object: {note}")
+        requested_object = args.object
+        args.object = object_row.get("Name") or args.object
+        try:
+            describe = _events.triggers_describe(
+                args.key, operation, args.object, args.connection_id)
+        except _events.EventDiscoveryError as error:
+            sys.exit(f"prepare-connector: {error}")
+        op["objectName"] = args.object
+        op["objectDisplayName"] = str(object_row.get("DisplayName") or "")
+    else:
+        if args.object:
+            sys.exit(
+                f"prepare-connector: --object applies to Generic events; "
+                f"{args.action}'s object is built in "
+                f"({op.get('objectName') or 'none'})."
+            )
+        baked = str(op.get("objectName") or "")
+        object_row = next(
+            (row for row in rows if str(row.get("Name")) == baked), None)
+        # `triggers describe` is the AUTHORITY for a curated event too, not
+        # just a generic one. The registry definition mirrors it and the
+        # mirror is lossy: measured on outlook `email-received`, describe
+        # returns 15 filter fields and the registry 14 — `isRead` is only in
+        # describe, and both agree on all 73 output fields. Reading the mirror
+        # would leave `check` REFUSING a filter on `isRead` as an unknown
+        # field, which is the one diagnostic here that is an error. Fall back
+        # to the definition's own sections when describe cannot answer (a
+        # baked object name the trigger catalog does not list) rather than
+        # failing the prepare — the mirror is still a usable vocabulary.
+        if baked:
+            try:
+                describe = _events.triggers_describe(
+                    args.key, operation, baked, args.connection_id)
+            except _events.EventDiscoveryError as error:
+                print(f"  WARN: {error}\n"
+                      f"  falling back to the registry definition's own "
+                      f"schema sections for {baked}", file=sys.stderr)
+
+    facts = _events.event_facts(node, object_row)
+    if facts["byoaConnection"]:
+        _refuse_unless_byoa_connection(args)
+
+    # One stored shape: the registry definition with the describe sections
+    # made true for this object (generic), or with the object row's
+    # Parameters unioned in (curated). `Library.eventParameterFields` reads
+    # `v1def.eventParameters.fields`, so the overlay v1def IS the store.
+    object_parameters = (object_row or {}).get("Parameters")
+    if describe is not None:
+        node = _events.merge_describe_into_node(node, describe, object_parameters)
+    else:
+        node = dict(node)
+        node["eventParameters"] = {"fields": _events.union_event_parameters(
+            (node.get("eventParameters") or {}).get("fields"),
+            object_parameters,
+        )}
+    if (node.get("outputResponseDefinition") or {}).get("fields"):
+        entry["outputSchema"] = {
+            "fields": node["outputResponseDefinition"]["fields"]}
+    node["nodeType"] = event_nt
+    entry["nodeType"] = event_nt
+
+    merged_path = os.path.join(tmp, "event-def.json")
+    with open(merged_path, "w", encoding="utf-8") as handle:
+        json.dump({"Data": {"Node": node}}, handle)
+
+    tmplib = os.path.join(tmp, "eventlib")
+    gen.write_library(tmplib, [entry], {event_nt: merged_path})
+    merge_into(tmplib, args.out)
+
+    if generic:
+        try:
+            ledger_path = _objects.record_object_resolution(
+                args.out, event_nt, requested_object, object_row, operation)
+        except _objects.LedgerError as error:
+            sys.exit(f"prepare-connector: {error}")
+        print(f"  object: {requested_object} -> {args.object} "
+              f"recorded in {ledger_path}")
+
+    if args.resolve:
+        _write_resolutions(args, event_nt)
+
+    _regenerate_descriptors(args)
+
+    where_fields = (node.get("eventParameters") or {}).get("fields") or []
+    filter_fields = (node.get("filterFields") or {}).get("fields") or []
+    mode = facts["eventMode"]
+    print(f"prepare-connector: {event_nt} → {args.out}/ (event overlay, "
+          f"{operation}, {mode}, {len(where_fields)} where-parameter(s), "
+          f"{len(filter_fields)} filter field(s))")
+    sys.stdout.flush()
+    _print_lookup_vocabulary(args, event_nt)
+    if filter_fields:
+        names = ", ".join(str(f.get("name")) for f in filter_fields[:8])
+        print(f"prepare-connector: filterable fields ({len(filter_fields)}): "
+              f"{names}" + (" …" if len(filter_fields) > 8 else ""))
+    if mode == "webhooks":
+        # Registration is an act on the external service — the one step this
+        # loop cannot make deterministic. Hand the author the connector's own
+        # words instead of leaving `uip is webhooks config` to be discovered.
+        print("prepare-connector: note: this event is WEBHOOK mode — it "
+              "cannot be debugged locally (deploy to test), and the webhook "
+              "URL must be registered on the external service"
+              + (":" if facts["textBlocks"] else
+                 " (retrieve it with `uip is webhooks config`)."),
+              file=sys.stderr)
+        for block in facts["textBlocks"]:
+            print(f"  {block}", file=sys.stderr)
+    connection_name = getattr(args, "_bound_connection", None) or "<connection>"
+    folder_name = getattr(args, "_bound_folder", None) or "shared"
+    subscription = (
+        f"{{ connector: '{args.key}', event: '{args.action}'"
+        + (f", object: '{args.object}'" if generic else "")
+        + f", connection: '{connection_name}', folder: '{folder_name}' }}"
+    )
+    print(f"prepare-connector: next: .trigger(onEvent({subscription})) to "
+          f"start the flow on this event — or .step('…', "
+          f"waitForEvent({subscription})) to pause mid-flow for it")
+    return True
+
+
+def _overlay_has_generic_expanded(out: str) -> bool:
+    """Does the overlay hold ANY `GenericExpanded` entry, from any prepare?"""
+    try:
+        with open(os.path.join(out, "index.json"), encoding="utf-8") as handle:
+            entries = json.load(handle).get("entries") or []
+    except (OSError, ValueError):
+        return False
+    return any(e.get("activityType") == "GenericExpanded" for e in entries)
+
+
+def _regenerate_descriptors(args) -> None:
+    """Rewrite the overlay's typed descriptors from the overlay's own JSON.
+
+    Both prepare paths end here. The EVENT path used not to: it wrote the JSON
+    overlay and returned, so a project whose only prepare was an event got no
+    `.ts` at all, and one that had prepared an action earlier kept that older
+    run's module — generated before the event's parameters were in the overlay,
+    so `where` was `Record<string, string>` and the trigger carried no
+    `lookups`. That is the module `prepare` tells the author to import, and
+    `--refresh-lookups` could not repair it, because nothing on the event path
+    regenerated TypeScript at all.
+
+    `--include-generic-expanded` is decided from the WHOLE overlay index rather
+    than the entries of this run: the generator rewrites every module under
+    `--output`, so reading one run would drop the descriptors an earlier
+    `GenericExpanded` prepare had written.
+    """
+    if args.json_only:
+        return
+    command = [
+        sys.executable, str(HERE / "generate_connectors_ts.py"),
+        "--library", args.out, "--output", args.out, "--import", args.imp,
+    ]
+    if _overlay_has_generic_expanded(args.out):
+        command.append("--include-generic-expanded")
+    subprocess.run(command, check=True)
+
+
+def _write_resolutions(args, node_type: str) -> None:
+    """Resolve every `--resolve` and merge the answers into the overlay.
+
+    A SEPARATE FILE from the schema overlay, deliberately. A prepared schema is
+    a fact about the connector; a resolution is a fact about one tenant's data,
+    so it ages differently and most consumers will want to gitignore it. Keeping
+    them apart is also what lets `--refresh-lookups` mean something later.
+
+    Existing entries STAND rather than being re-resolved. A resolved id is a
+    snapshot either way; re-resolving on every call would make an unrelated
+    `prepare` silently change an artifact, which is the opposite of what the
+    file is for. Re-resolving is a deliberate act with a visible diff.
+    """
+    specs = _lookup_specs_from_overlay(args.out, node_type, args.object)
+    requested = [_resolve.parse_resolve_flag(raw) for raw in args.resolve]
+
+    unknown = [f for f, _b, _v in requested if f not in specs]
+    if unknown:
+        known = ", ".join(sorted(specs)) or "(none)"
+        sys.exit(
+            f"prepare-connector: no lookup is declared for "
+            f"{', '.join(repr(f) for f in unknown)} on {node_type}. "
+            f"Fields with a lookup: {known}."
+        )
+
+    ordered = _resolve.order_resolutions(requested, specs)
+    path = os.path.join(args.out, "resolutions.json")
+    # Read and rewrite the WHOLE ledger, not just `resolutions`: the file also
+    # carries the `objects` section (the object decision recorded above), and
+    # rewriting only one section used to silently drop the other. A file that
+    # will not parse is REFUSED rather than reset — same rule as bindings.json.
+    try:
+        ledger = _objects.read_ledger(args.out)
+    except _objects.LedgerError as error:
+        sys.exit(f"prepare-connector: {error}")
+    existing = ledger.get("resolutions") or {}
+
+    resolved_values: dict[str, str] = {}
+    for field, by, value in ordered:
+        # COMPACT SEPARATORS, to match JavaScript exactly. `compile` computes
+        # this key with `JSON.stringify`, which emits no space after a comma;
+        # Python's default emits `", "`. The two encodings of the same tuple are
+        # different strings, so every resolution `prepare` wrote was invisible to
+        # the compile that had just asked for it — the command did the work,
+        # recorded it, and then refused to use it.
+        key = json.dumps([node_type, field, by, value], separators=(",", ":"))
+        if key in existing and not args.refresh_lookups:
+            resolved_values[field] = existing[key]["value"]
+            print(f"  {field}: {by}={value} -> {existing[key]['value']} (already resolved)")
+            continue
+        try:
+            got = _resolve.resolve_one(
+                args.key, specs[field], field, by, value,
+                args.connection_id, resolved_values,
+            )
+        except _resolve.ResolutionError as error:
+            sys.exit(f"prepare-connector: {error}")
+        resolved_values[field] = got
+        existing[key] = {
+            "nodeType": node_type, "field": field, "by": by,
+            "match": value, "value": got,
+        }
+        print(f"  {field}: {by}={value} -> {got}")
+
+    os.makedirs(args.out, exist_ok=True)
+    ledger["schemaVersion"] = "1"
+    ledger["resolutions"] = existing
+    with open(path, "w", encoding="utf-8") as handle:
+        json.dump(ledger, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+    print(f"  wrote {len(existing)} resolution(s) to {path}")
+
+
+def _lookup_specs_from_overlay(
+    out_dir: str, node_type: str, object_name: str | None = None,
+) -> dict:
+    """The prepared operation's lookup specs, from the overlay just written.
+
+    Read back from the overlay rather than recomputed, so a resolution is made
+    against the SAME schema the descriptors were generated from — including any
+    connection-resolved field that only exists because this `prepare` ran.
+    """
+    index_path = os.path.join(out_dir, "index.json")
+    if not os.path.exists(index_path):
+        return {}
+    with open(index_path, encoding="utf-8") as handle:
+        entries = json.load(handle).get("entries", [])
+    invariant = load_invariant_collections(out_dir)
+    for entry in entries:
+        if entry.get("nodeType") != node_type:
+            continue
+        # Generic object variants share a nodeType; without the object filter
+        # the FIRST variant answered for all of them, so a `--resolve` against
+        # the object just prepared read another object's lookup table.
+        if object_name and entry.get("objectName") not in ("", None, object_name):
+            continue
+        entry_path = os.path.join(out_dir, entry["path"])
+        v1_path = entry_path[:-5] + ".v1def.json"
+        if not os.path.exists(entry_path):
+            continue
+        with open(entry_path, encoding="utf-8") as handle:
+            canonical = json.load(handle)
+        v1def = {}
+        if os.path.exists(v1_path):
+            with open(v1_path, encoding="utf-8") as handle:
+                raw = json.load(handle)
+            v1def = raw[0] if isinstance(raw, list) else raw
+        # An EVENT's resolvable fields are its subscription parameters, and
+        # `v1def.eventParameters.fields` is the ONE authority for those — the
+        # same list the SDK, `check` and the descriptor generator read.
+        #
+        # This used to pick the source by testing whether `inputSchema` was
+        # empty, which was right only because the prepare path happens to
+        # leave `inputSchema` as the manifest wrote it while generation
+        # overwrites it. Either path changing flips the heuristic and the
+        # specs come from the manifest's message-BODY fields instead — the
+        # exact wrong list. The node kind is the fact being tested, so test
+        # it.
+        if node_type.startswith(("uipath.connector.event.",
+                                 "uipath.connector.trigger.")):
+            fields_source = {"inputSchema": {
+                "fields": (v1def.get("eventParameters") or {}).get("fields") or []
+            }}
+        else:
+            fields_source = canonical
+        specs = gen_ts.lookup_specs(fields_source, v1def, invariant)
+        # `filterPattern` is not on the descriptor spec (it is a retrieval
+        # detail, not an authoring one) but the resolver needs it.
+        catalog = {
+            f.get("name"): f["reference"]
+            for f in ((fields_source.get("inputSchema") or {}).get("fields") or [])
+            if isinstance(f.get("reference"), dict)
+        }
+        for field, spec in specs.items():
+            reference = catalog.get(field) or {}
+            if reference.get("filterPattern"):
+                spec["filterPattern"] = reference["filterPattern"]
+        return specs
+    return {}
+
+
+# `import … from "<specifier>"` — the specifier is group 3, quotes preserved.
+# Deliberately anchored to a real import STATEMENT: the instruction this
+# replaces became `sed 's|./connectors/|./connectors-local/|'` in practice,
+# which also rewrites the same text inside comments and inside the imports of
+# connectors this run did NOT prepare (#704).
+_IMPORT_RE = re.compile(
+    r"""(^\s*import\s[^;'"]*?\sfrom\s*)(['"])([^'"]+)(\2)""",
+    re.MULTILINE,
+)
+
+# Where a `.flow.ts` will not be: generated output and installed packages.
+_SOURCE_SKIP_DIRS = {"node_modules", "connectors", "connectors-local", ".git"}
+
+
+def _resolves_to(specifier: str, source: Path, target: Path) -> bool:
+    """Does `specifier`, read from `source`, name the file `target`?
+
+    Compared as RESOLVED paths, not as text, so `./connectors/x.ts` from the
+    project root and `../connectors/x.ts` from a nested source both match the
+    one file — and a same-named connector under a different root does not.
+    """
+    if not specifier.startswith("."):
+        return False                      # a bare package, never our overlay
+    try:
+        candidate = (source.parent / specifier).resolve()
+    except (OSError, ValueError):
+        return False
+    return candidate == target
+
+
+def _sources_importing(baked: Path, root: Path) -> list[Path]:
+    """Every `*.flow.ts` under `root` whose import resolves to `baked`.
+
+    Selection is by CONTENT rather than "the single flow in this directory":
+    a workspace with three flows, one of which uses this connector, has one
+    correct answer and this finds it.
+    """
+    found: list[Path] = []
+    for path in sorted(root.rglob("*.flow.ts")):
+        if _SOURCE_SKIP_DIRS & set(path.relative_to(root).parts[:-1]):
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        if any(_resolves_to(m.group(3), path, baked) for m in _IMPORT_RE.finditer(text)):
+            found.append(path)
+    return found
+
+
+def _repoint_import(source: Path, baked: Path, prepared: Path) -> str | None:
+    """Point `source`'s import at the prepared descriptor. The new specifier, or None.
+
+    Only the quoted path changes. The rest of the statement — the named
+    bindings, an `as` alias, the quote style — is carried through untouched,
+    which is the whole difference between this and the find-and-replace it
+    replaces.
+    """
+    try:
+        text = source.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    specifier = os.path.relpath(prepared, source.parent).replace(os.sep, "/")
+    if not specifier.startswith("."):
+        specifier = f"./{specifier}"
+    changed = False
+
+    def swap(match: "re.Match[str]") -> str:
+        nonlocal changed
+        if not _resolves_to(match.group(3), source, baked):
+            return match.group(0)
+        changed = True
+        return f"{match.group(1)}{match.group(2)}{specifier}{match.group(4)}"
+
+    rewritten = _IMPORT_RE.sub(swap, text)
+    if not changed or rewritten == text:
+        return None
+    source.write_text(rewritten, encoding="utf-8")
+    return specifier
+
+
+def _repoint_source(args, connector_key: str) -> list[str]:
+    """Repoint the author's import, or explain why it was left alone.
+
+    `prepare` already writes `bindings.json`, the overlay descriptor and
+    `resolutions.json`; the one thing it did NOT do was update the import
+    naming the descriptor it had just replaced. That left a mechanical edit —
+    one specifier, one file, exactly one right answer — to the caller, who has
+    strictly less information than this command does. Measured cost: an agent
+    reaches for `sed`, which repoints connectors that were never prepared and
+    breaks the flow with `Cannot find module`.
+
+    Ambiguity keeps today's behaviour. Zero candidates or several, and nothing
+    is written — the printed import line still tells the author what to do, so
+    the fallback is exactly the status quo and never worse.
+    """
+    prepared = (Path(args.out) / f"{connector_key}.ts").resolve()
+    if getattr(args, "no_source_rewrite", False) or not prepared.is_file():
+        return []
+    baked = (Path.cwd() / "connectors" / f"{connector_key}.ts").resolve()
+
+    if getattr(args, "source", None):
+        candidates = [Path(args.source).resolve()]
+        if not candidates[0].is_file():
+            return [f"--source {args.source} does not name a file; "
+                    f"left the import alone"]
+    else:
+        candidates = _sources_importing(baked, Path.cwd())
+
+    if not candidates:
+        return []
+    if len(candidates) > 1:
+        names = ", ".join(
+            c.relative_to(Path.cwd()).as_posix() for c in candidates)
+        return [f"{len(candidates)} sources import this connector ({names}); "
+                f"name one with --source to have it repointed"]
+
+    source = candidates[0]
+    specifier = _repoint_import(source, baked, prepared)
+    if specifier is None:
+        return []
+    return [f"repointed {source.relative_to(Path.cwd()).as_posix()} "
+            f"-> {specifier}"]
+
+
+def _descriptor_usage(out_dir: str, connector_key: str,
+                      bound_connection: str = "<binding-name>",
+                      bound_folder: str = "<folder-binding-name>") -> list[str]:
+    """Teach the author how to consume the connection-resolved descriptor.
+
+    The live registry may use a different action id than the baked catalog. The
+    generated descriptor is the authority for that resolved identity, so the
+    success message must carry the author across that boundary instead of
+    leaving them to reverse-engineer index.json.
+    """
+    source = Path(out_dir) / f"{connector_key}.ts"
+    try:
+        generated = source.read_text()
+        exports = re.findall(
+            r"^export const ([A-Za-z_$][A-Za-z0-9_$]*) = "
+            r"descriptor<([A-Za-z_$][A-Za-z0-9_$]*),",
+            generated,
+            flags=re.MULTILINE,
+        )
+    except OSError:
+        generated = ""
+        exports = []
+
+    import_path = os.path.relpath(source, Path.cwd()).replace(os.sep, "/")
+    if not import_path.startswith("."):
+        import_path = f"./{import_path}"
+    if len(exports) == 1:
+        descriptor_name, inputs_interface = exports[0]
+        required_fields = _required_interface_fields(
+            generated, inputs_interface
+        )
+        if required_fields is None:
+            return [
+                f'open "{source.as_posix()}" and import {descriptor_name}',
+                "read its generated inputs interface before calling connector; "
+                "the required-input skeleton is unavailable",
+            ]
+        inputs = "{}"
+        if required_fields:
+            placeholders = ", ".join(
+                f"{name}: /* {field_type}, required */"
+                for name, field_type in required_fields
+            )
+            inputs = f"{{ {placeholders} }}"
+        return [
+            f'import {{ {descriptor_name} }} from "{import_path}";',
+            f'connector({descriptor_name}, {inputs}, '
+            f'{{ connection: "{bound_connection}", folder: "{bound_folder}" }})',
+            "use this descriptor as generated: it carries the resolved live "
+            "operation and object identity even when the baked action id differs",
+        ]
+
+    return [
+        f'open "{source.as_posix()}" and import the descriptor for the object you need',
+        "use that descriptor with connector(descriptor, inputs, opts); do not "
+        "reconstruct its live operation/object identity from the baked catalog",
+    ]
+
+
+def _required_interface_fields(
+    generated: str, interface_name: str
+) -> list[tuple[str, str]] | None:
+    match = re.search(
+        rf"^export interface {re.escape(interface_name)} \{{(?P<body>.*?)^\}}",
+        generated,
+        flags=re.MULTILINE | re.DOTALL,
+    )
+    if not match:
+        return None
+
+    required: list[tuple[str, str]] = []
+    property_pattern = re.compile(
+        r'^  (?P<name>[A-Za-z_$][A-Za-z0-9_$]*|"(?:\\.|[^"\\])*")'
+        r'(?P<optional>\?)?: (?P<type>.+);$'
+    )
+    for line in match.group("body").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith(("/**", "*", "*/")):
+            continue
+        field = property_pattern.match(line)
+        if not field:
+            return None
+        if not field.group("optional"):
+            required.append((field.group("name"), _unwrap_value(field.group("type"))))
+    return required
+
+
+def _unwrap_value(ts_type: str) -> str:
+    """`ConnectorValue<string>` -> `string`, for the handoff skeleton.
+
+    The generated property type says what the field ACCEPTS — the literal or an
+    expression — which is the right thing for the compiler and the wrong thing
+    for a one-line "what goes here" hint. An author reading
+    `/* ConnectorValue<string>, required */` learns less than one reading
+    `/* string, required */`, and the wrapper is not something they type.
+    """
+    match = re.fullmatch(r"Connector(?:Lookup)?Value<(.+)>", ts_type.strip())
+    return match.group(1) if match else ts_type
+
+
+def _count_input_fields(
+    out_dir: str, node_type: str, object_name: str | None = None
+) -> int | None:
+    """Input-field count across matching overlay variants."""
+    try:
+        with open(os.path.join(out_dir, "index.json")) as index_file:
+            idx = json.load(index_file)
+        entries = idx["entries"]
+        if not isinstance(entries, list):
+            return None
+        total = 0
+        matched = False
+        for index_entry in entries:
+            if index_entry["nodeType"] != node_type:
+                continue
+            if object_name is not None and index_entry.get("objectName") != object_name:
+                continue
+            matched = True
+            with open(os.path.join(out_dir, index_entry["path"])) as entry_file:
+                descriptor = json.load(entry_file)
+            if not isinstance(descriptor, dict):
+                return None
+            input_schema = descriptor.get("inputSchema")
+            if not isinstance(input_schema, dict):
+                return None
+            fields = input_schema.get("fields")
+            if not isinstance(fields, list):
+                return None
+            total += len(fields)
+        return total if matched else None
+    except (OSError, json.JSONDecodeError, KeyError, TypeError):
+        return None
+
+
+def _declared_parents(registry_path: str) -> list[str]:
+    """Parent-input names the registry declares through api-type ObjectActions.
+
+    The second way an operation says "my fields depend on a value": not a
+    `{placeholder}` in a reference path (Jira), but a design-time action whose
+    rules name the inputs it reads (Data Fabric `create-entity-record` declares
+    `GenerateSchema` over `entityName`). `_object_action_specs` already reads
+    them for the replay request; this is the same list, flattened and in
+    declaration order, for the no-`-f` note.
+    """
+    names: list[str] = []
+    for _action, refs in _object_action_specs(registry_path):
+        for ref in refs:
+            if ref not in names:
+                names.append(ref)
+    return names
+
+
+def _schema_action_parents(
+    out_dir: str, node_type: str, object_name: str | None = None
+) -> list[str]:
+    """Parent inputs the PREPARED operation's own schema action names.
+
+    The third and most direct way an operation says "my fields depend on a
+    value", and the only one that is a PRECONDITION rather than a symptom: the
+    descriptor just written carries `operation.schemaAction.parents`, so with
+    any of those missing from `-f` the action cannot have run, whatever the
+    describe returned. `_parent_fields` and `_declared_parents` both read the
+    result or the registry instead, and each has a shape it cannot see:
+
+    - `_parent_fields` asks "is EVERY prepared field a parent?". Jira's
+      `create-issue` comes back parent-only PLUS `key` (its own issue key), so
+      that test reads an unresolved schema as resolved and says nothing while
+      `compile` is about to refuse `summary` as an unknown input — measured on
+      a real run that then fell back to the generic `insert-record`.
+    - `_declared_parents` reads the registry's api-type ObjectActions, which is
+      empty for that operation.
+
+    Order is the declaration's, which is also the resolution order (a Jira
+    issue-type id is valid only inside its project).
+    """
+    names: list[str] = []
+    try:
+        with open(os.path.join(out_dir, "index.json")) as index_file:
+            entries = json.load(index_file)["entries"]
+        for index_entry in entries:
+            if index_entry["nodeType"] != node_type:
+                continue
+            if object_name is not None and index_entry.get("objectName") != object_name:
+                continue
+            with open(os.path.join(out_dir, index_entry["path"])) as entry_file:
+                descriptor = json.load(entry_file)
+            action = ((descriptor.get("operation") or {}).get("schemaAction")) or {}
+            for name in action.get("parents") or []:
+                if name and name not in names:
+                    names.append(name)
+    except (OSError, KeyError, TypeError, ValueError):
+        return []
+    return names
+
+
+def _keep_prepared_schema(
+    args, node_type: str, staged: str, parent_fields: dict[str, str],
+) -> tuple[int, int] | None:
+    """`(kept, discarded)` when this run must not overwrite the overlay, else `None`.
+
+    `--resolve` records a lookup; `-f` supplies the value a schema action reads.
+    A run carrying only the former cannot have run the action, so what it has to
+    write is the UNRESOLVED entry — and `merge_into` replaces by variant key, so
+    it lands on top of a schema an earlier `-f` run resolved. Measured on Jira
+    `create-issue`: 21 fields down to 3, taking the live-only `fields.reporter.id`
+    and `fields.summary` out of `required` with it, after which `compile` accepts
+    a flow it had been refusing (#666).
+
+    The loop that provokes it is the documented one. `check` prints
+    `prepare … --resolve <field>:<by>=<value>` for every unresolved lookup, with
+    no `-f`, so an author who prepares with `-f`, authors against the live schema
+    and then does what `check` says destroys the schema they just authored
+    against. #685 made that run say so; it still wrote.
+
+    Three conditions, all necessary:
+
+    * the EXISTING overlay declares `schemaAction.parents` — read from
+      `args.out` before the merge, so this is the entry about to be replaced;
+    * none of those parents arrived as `-f`, which is what makes "the action did
+      not run" a fact about the inputs rather than a guess about the result;
+    * the staged entry has FEWER input fields than the one on disk.
+
+    The third keeps this a strict no-loss rule rather than a blanket skip: equal
+    or richer still merges, so a re-pulled library's fresher entry is never
+    pinned by a stale overlay, and a first `--resolve` on an operation with no
+    overlay writes normally (`_count_input_fields` answers `None`).
+    """
+    parents = _schema_action_parents(args.out, node_type, args.object)
+    if not parents or any(name in parent_fields for name in parents):
+        return None
+    existing = _count_input_fields(args.out, node_type, args.object)
+    incoming = _count_input_fields(staged, node_type, args.object)
+    if existing is None or incoming is None or existing <= incoming:
+        return None
+    return existing, incoming
+
+
+def _parent_fields(
+    out_dir: str, node_type: str, object_name: str | None = None
+) -> tuple[list[str], bool]:
+    """`(parent field names, whether the prepared schema is parent-ONLY)`.
+
+    A reference `path` carrying a `{placeholder}` is the declaration that an
+    operation is parent-driven: `"/project/{fields.project.key}/issuetypes"` on
+    `fields.issuetype.id` names the field whose value must be resolved first,
+    and so also fixes the resolution ORDER. (Only `path` is scanned;
+    `filterPattern` carries an unrelated `{filter}` template.)
+
+    The parent set is both halves of that relation — the placeholder names AND
+    the fields that declare them — because both must be passed as `-f`.
+    Reporting only the placeholders would name `fields.project.key` and omit
+    `fields.issuetype.id`, the very field that declared it.
+
+    "Parent-only" then means every prepared field is a parent: the describe gave
+    back nothing but the inputs that select the real schema. That is the
+    expected shape with no `-f`, and a silent failure WITH `-f` — values that do
+    not exist on the connection are accepted and resolve to exactly this.
+    A resolved schema keeps its parents (Jira's 19 still include both), so
+    subset-of-parents is the discriminator, not the presence of a placeholder.
+    """
+    names: list[str] = []
+    placeholders: set[str] = set()
+    declaring: set[str] = set()
+    try:
+        with open(os.path.join(out_dir, "index.json")) as index_file:
+            entries = json.load(index_file)["entries"]
+        for index_entry in entries:
+            if index_entry["nodeType"] != node_type:
+                continue
+            if object_name is not None and index_entry.get("objectName") != object_name:
+                continue
+            with open(os.path.join(out_dir, index_entry["path"])) as entry_file:
+                descriptor = json.load(entry_file)
+            for field in descriptor.get("inputSchema", {}).get("fields", []) or []:
+                name = field.get("name")
+                if name and name not in names:
+                    names.append(name)
+                path = ((field.get("reference") or {}).get("path")) or ""
+                found = re.findall(r"\{([^{}]+)\}", path)
+                if found:
+                    placeholders.update(found)
+                    if name:
+                        declaring.add(name)
+    except (OSError, KeyError, TypeError, ValueError):
+        return [], False
+
+    parents = placeholders | declaring
+    if not parents:
+        return [], False
+    ordered = [name for name in names if name in parents]
+    ordered += sorted(parents - set(ordered))
+    return ordered, set(names) <= parents
+
+
+def _parse_fields(pairs: list[str]) -> dict[str, str]:
+    """`['a=1', 'b=2']` → `{'a': '1', 'b': '2'}`, rejecting a missing `=`.
+
+    Values may themselves contain `=` (a Salesforce SOQL body token), so split
+    on the FIRST separator only.
+    """
+    parsed: dict[str, str] = {}
+    for pair in pairs:
+        name, sep, value = pair.partition("=")
+        if not sep or not name.strip():
+            sys.exit(
+                f"prepare-connector: --field expects NAME=VALUE, got {pair!r}."
+            )
+        parsed[name.strip()] = value
+    return parsed
+
+
+def _rejected_parent_fields_message(
+    pairs: list[str], failures: list[tuple] | None = None
+) -> str:
+    """Diagnose a rejected parent-field set, preserving the CLI's own message.
+
+    An incomplete or invalid set is refused outright — "No api-type ObjectAction
+    matched for fields [...] on operation 'Create'" — which already names the
+    fields it could not match. That message never reaches the caller on its own:
+    `is_describe_operation` maps the failure to `None` and enrichment falls back
+    to the registry-declared fields, so the overlay is written as though nothing
+    went wrong. Fail here, and quote the service.
+    """
+    given = ", ".join(pairs)
+    detail = ""
+    for failure in failures or []:
+        message = failure[-1]
+        if message:
+            detail = f" The service said: {message}"
+            break
+    return (
+        f"prepare-connector: the parent-field set was rejected: {given}.{detail} "
+        "Re-run with NO -f to list the parent fields this operation declares, "
+        "resolve a value for EVERY one of them, then pass them all together. "
+        "Values are connection- and parent-scoped (a Jira issue-type id is valid "
+        "only inside its project), so they cannot be copied from another "
+        "project, connection, or task."
+    )
+
+
+def _input_field_note(count: int | None) -> str:
+    return (
+        f"{count} input field(s)"
+        if count is not None
+        else "input fields: <unavailable>"
+    )
+
+
+if __name__ == "__main__":
+    main()