@uipath/maestro-builder-sdk 6.4.0 → 6.5.1

package/dist/registry/prepare/connections.d.ts

@@ -0,0 +1,181 @@
+import { Refusal } from "../errors.js";
+import type { UipClient } from "../uip/client.js";
+/** One row of `uip is connections list`: `Id`, `Name`, `ConnectorKey`, `State`, `Folder`, `FolderKey`, … */
+export type ConnectionRow = Record<string, unknown>;
+/** Which listing the candidates came from, as the refusals name it. */
+export type ConnectionScope = "your folder" | "the tenant";
+/** No usable connection, with the reason and the way forward (`_connections.ConnectionError_`). */
+export declare class ConnectionRefusal extends Refusal {
+    constructor(message: string, code: string);
+}
+/**
+ * `uip is connections list --output json`, as rows.
+ *
+ * A non-zero exit and a non-JSON reply are both refusals, never an empty list:
+ * "you have no connection" and "the listing failed" have opposite remedies.
+ */
+export declare function listConnections(client: UipClient, options: {
+    allFolders: boolean;
+    byoa?: boolean;
+}): Promise<ConnectionRow[]>;
+/**
+ * The rows for `connectorKey` that can serve a request, optionally by `Name`.
+ *
+ * A Failed connection is listed like any other and cannot serve a request;
+ * selecting one produces an error about the operation rather than about the
+ * connection, which sends the reader the wrong way.
+ */
+export declare function enabledConnections(rows: readonly ConnectionRow[], connectorKey: string, name?: string): ConnectionRow[];
+/**
+ * The candidates, one pasteable `--connection-id` line each
+ * (`_connections.candidate_listing`): `<indent><Name>  --connection-id <Id>  (folder: <Folder>)`.
+ */
+export declare function candidateListing(rows: readonly ConnectionRow[], indent?: string): string;
+/**
+ * The one enabled connection for `connectorKey` among `rows`, or throw.
+ *
+ * Pure: `rows` is whatever listing the caller fetched, and `scope` is how the
+ * refusal names it. Several candidates is a refusal that lists every one with
+ * its id — a NAME is not a key on a tenant. The eval tenant holds three Slack
+ * connections all named `is-sandboxes` (two Enabled, in different folders), so
+ * the old remedy — "name the one you want with --connection <name>" — handed
+ * back the very flag the caller had just used, and the doc-following author
+ * dead-ended (placeholder GUIDs hand-written into bindings.json, 401 at the
+ * Slack node).
+ */
+export declare function selectConnection(rows: readonly ConnectionRow[], connectorKey: string, name?: string, scope?: ConnectionScope): ConnectionRow;
+/**
+ * The one enabled connection for `connectorKey`, fetched, or throw.
+ *
+ * Tries the DEFAULT listing first and only widens to `--all-folders` if that
+ * finds nothing. That order matters and is not just politeness to the API: the
+ * default listing is the caller's own folder, which on a real tenant is one
+ * connection where the tenant-wide view is many. Widening first would turn an
+ * unambiguous case into an ambiguous one.
+ */
+export declare function discoverConnection(client: UipClient, connectorKey: string, name?: string): Promise<ConnectionRow>;
+/**
+ * Every enabled connection for `connectorKey`, own folder FIRST
+ * (`_connections.candidate_connections`).
+ *
+ * {@link discoverConnection} answers "which one" and stops at the first
+ * non-empty scope, which is right for picking a connection and wrong for
+ * retrying one: when the own-folder listing holds exactly one, the tenant-wide
+ * connections are never even looked at. So a lookup that exhausts the
+ * personal-workspace connection reports a bad VALUE while the record sits in
+ * another folder's connection (flow-builder-sdk#744, measured on two Jira
+ * connections where only the second carried project `TS`).
+ *
+ * Ordering is the same preference discovery encodes — the caller's own folder
+ * is the likeliest and is tried first — but nothing is dropped. Deduplicated
+ * by `Id`, because the tenant-wide listing repeats the own-folder rows; a row
+ * with no `Id` is never deduplicated, as the Python's `if identifier and …`
+ * did not.
+ *
+ * This does NOT decide anything, and in particular does not throw on several
+ * matches: choosing among them is the caller's job, and the only honest way to
+ * choose is evidence (a lookup that resolves on exactly one). That keeps this
+ * module's rule intact — ambiguity is never resolved by guessing.
+ */
+export declare function candidateConnections(client: UipClient, connectorKey: string, name?: string): Promise<ConnectionRow[]>;
+/** The enabled connections for `connectorKey`, one per line, pasteable. */
+export declare function enabledListing(rows: readonly ConnectionRow[], connectorKey: string): string;
+/**
+ * The record for an explicitly named connection among `rows`, or throw unless it can serve.
+ *
+ * An explicit `--connection-id` used to skip every check discovery applies, and
+ * that skip is where a whole class of silent failures came from. A connection
+ * in `State: Failed` is listed like any other, and `uip is resources describe`
+ * against it answers `Result: Success` with NO request fields — the tenant has
+ * no schema to give for a connection it cannot reach. `prepare` then wrote an
+ * overlay with zero body inputs, printed "0 input field(s)" as a success, and
+ * the next `compile` rejected every real field as unknown. Measured on the eval
+ * tenant (Salesforce `Opportunity` / `Update`): the Failed connection returned
+ * 0 request fields, the Enabled one 13.
+ *
+ * So: resolve the id against the listing, and refuse — naming the state found
+ * and the enabled alternatives — rather than describe through it.
+ */
+export declare function checkConnection(rows: readonly ConnectionRow[], connectorKey: string, connectionId: string): ConnectionRow;
+/** {@link checkConnection} against the tenant-wide listing — the id may live in another folder. */
+export declare function lookupConnection(client: UipClient, connectorKey: string, connectionId: string): Promise<ConnectionRow>;
+/**
+ * The enabled BYOA connections for `connectorKey`.
+ *
+ * THROWS on a failed listing rather than answering an empty list. The
+ * difference is the whole point: "you have no BYOA connection" tells the caller
+ * to go create one, and a listing that failed says nothing of the kind.
+ * Answering [] for both turns a broken call into confident, wrong advice.
+ */
+export declare function byoaConnections(client: UipClient, connectorKey: string): Promise<ConnectionRow[]>;
+/** The BYOA candidates, one pasteable line each, or why there are none. */
+export declare function byoaListing(rows: readonly ConnectionRow[], connectorKey: string): string;
+/** `bindings.json` as this module reads and writes it; rows are the author's and stay loose. */
+export type BindingsJson = Record<string, unknown> & {
+    schemaVersion?: unknown;
+    bindings: unknown[];
+};
+export interface BindingsMerge {
+    document: BindingsJson;
+    /** True when the connection row's `resourceKey` changed (or the row was added). */
+    wroteConnection: boolean;
+    /** True when the folder row's `resourceKey` changed (or the row was added). */
+    wroteFolder: boolean;
+}
+/**
+ * Add connection + folder entries to a parsed `bindings.json`, without touching the input.
+ *
+ * ADDITIVE AND IDEMPOTENT. An existing entry under the same symbolic name (its
+ * `name` or `id`) is updated, never duplicated, and every other entry is left
+ * exactly as it was — `bindings.json` is an authored file that may already
+ * carry bindings for connectors this run knows nothing about. An updated row
+ * keeps its key order and gains any missing key at the end; a new row is
+ * written `id, name, resource, resourceKey, default, propertyAttribute`.
+ *
+ * `document` is what the file parsed to, or `undefined` when there was no file.
+ * As in the Python, a parsed value that is not an object is replaced by the
+ * default document.
+ */
+export declare function mergeBindingsDocument(document: unknown, symbolicConnection: string, symbolicFolder: string, connection: ConnectionRow): BindingsMerge;
+/**
+ * `json.dump(document, indent=2)` + newline: the bytes `bindings.json` is written in.
+ *
+ * `allowIntegerKeys` for the same reason the ledger passes it (`objects.ts`):
+ * `bindings.json` is the author's file and may carry an integer-like key
+ * anywhere in a row this module never looks at. `json.dump` wrote such a file
+ * back; refusing it here left the file untouched and the connection unbound,
+ * with an error about a key the author did not know they had. The one thing
+ * that cannot be kept is that key's position — `JSON.parse` has already
+ * hoisted it to the front of its object — which Python preserved.
+ */
+export declare function formatBindings(document: BindingsJson): string;
+/**
+ * Add connection + folder entries to `bindings.json` at `path`, in place.
+ *
+ * Returns `[wroteConnection, wroteFolder]` describing what changed, so the
+ * caller can report the specific thing rather than "updated bindings". The file
+ * is always rewritten, as the Python did. A file that will not parse is REFUSED,
+ * not overwritten: it is the author's, and not ours to discard.
+ */
+export declare function mergeBindings(path: string, symbolicConnection: string, symbolicFolder: string, connection: ConnectionRow): [wroteConnection: boolean, wroteFolder: boolean];
+/**
+ * Remember `bindings.json` byte-for-byte, before a stage that writes it.
+ *
+ * `undefined` means the file could not be read — normally that it did not
+ * exist — and {@link restoreBindings} will remove whatever was written since.
+ */
+export declare function snapshotBindings(path: string | undefined): Uint8Array | undefined;
+/**
+ * Put `bindings.json` back exactly as {@link snapshotBindings} found it.
+ *
+ * A refusal must leave `bindings.json` as it was: the BYOA fact needs a
+ * connection to discover, so stage 0 has already written one by the time the
+ * event says it is the wrong KIND — without the rollback the overlay keeps
+ * pointing at a connection the tool just forbade. A failure to restore is
+ * reported through `warn` (stderr by default), never thrown: the refusal being
+ * delivered is the message that matters.
+ *
+ * `shown` is the path as the caller typed it (`args.bindings`), which is what
+ * the Python printed; `path` is where the file actually is.
+ */
+export declare function restoreBindings(path: string | undefined, snapshot: Uint8Array | undefined, warn?: (message: string) => void, shown?: string | undefined): void;

package/dist/registry/prepare/connections.js

@@ -0,0 +1,399 @@
+/**
+ * Find the connection for a connector, and write its bindings.
+ *
+ * `prepare` already knows which connector it is preparing. Making the author go
+ * and find that connector's connection id by hand — and then its folder key, and
+ * then hand-write `bindings.json` around both — is work the command can do
+ * itself from information it already has. Measured on the eval corpus, that
+ * hand-work was 4 to 7 tool calls per task.
+ *
+ * THE ONE THING THIS MUST NOT DO IS GUESS. A tenant can carry several
+ * connections for the same connector — the test tenant has five for Slack — and
+ * they are not interchangeable: a user who exists in one workspace does not
+ * exist in another, so picking the wrong one makes a lookup unresolvable for a
+ * reason that points nowhere near the actual mistake. That failure was observed
+ * directly (`skill-flow-slack-dm-lookup` named the wrong workspace and burned
+ * its whole turn budget), which is why ambiguity here is an error listing the
+ * candidates and never a silent choice.
+ *
+ * Ported from `integrations/scripts/_connections.py`. The decisions are pure
+ * functions over an already-fetched listing; the `async` wrappers fetch through
+ * a {@link UipClient} and hand the rows to them. Every refusal's text is kept
+ * verbatim — agents read these messages and follow them.
+ */
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { pyJsonStringify } from "../codecs/pyjson.js";
+import { pyStrip } from "../compat/pystr.js";
+import { Refusal, messageOf } from "../errors.js";
+import { isConnectionsList } from "../uip/commands.js";
+import { dataItems, parseEnvelope } from "../uip/envelope.js";
+import { isPlainObject, notJsonReason, pyGet, pyOr, pyRepr, pyStrAny, pyTruthy } from "./support.js";
+/** No usable connection, with the reason and the way forward (`_connections.ConnectionError_`). */
+export class ConnectionRefusal extends Refusal {
+    constructor(message, code) {
+        super(message, code);
+        this.name = "ConnectionRefusal";
+    }
+}
+/**
+ * `uip is connections list --output json`, as rows.
+ *
+ * A non-zero exit and a non-JSON reply are both refusals, never an empty list:
+ * "you have no connection" and "the listing failed" have opposite remedies.
+ */
+export async function listConnections(client, options) {
+    const result = await client.run(isConnectionsList({ allFolders: options.allFolders, byoa: options.byoa }));
+    if (result.code !== 0) {
+        throw new ConnectionRefusal(`listing connections failed: ${pyStrip(result.stderr) || "no output"}`, "CONNECTION_LISTING_FAILED");
+    }
+    const envelope = parseEnvelope(result.stdout);
+    if (envelope === undefined) {
+        throw new ConnectionRefusal(`connection listing was not JSON: ${notJsonReason(result.stdout)}`, "CONNECTION_LISTING_NOT_JSON");
+    }
+    return dataItems(envelope).filter(isPlainObject);
+}
+/**
+ * The rows for `connectorKey` that can serve a request, optionally by `Name`.
+ *
+ * A Failed connection is listed like any other and cannot serve a request;
+ * selecting one produces an error about the operation rather than about the
+ * connection, which sends the reader the wrong way.
+ */
+export function enabledConnections(rows, connectorKey, name) {
+    let out = rows.filter((row) => row.ConnectorKey === connectorKey && pyStrAny(pyGet(row, "State", "")).toLowerCase() === "enabled");
+    if (name)
+        out = out.filter((row) => row.Name === name);
+    return out;
+}
+/**
+ * The candidates, one pasteable `--connection-id` line each
+ * (`_connections.candidate_listing`): `<indent><Name>  --connection-id <Id>  (folder: <Folder>)`.
+ */
+export function candidateListing(rows, indent = "    ") {
+    return rows
+        .map((row) => `${indent}${pyStrAny(row.Name)}  --connection-id ${pyStrAny(row.Id)}  (folder: ${pyStrAny(row.Folder)})`)
+        .join("\n");
+}
+/** {@link candidateListing} at the refusals' four-space indent. */
+function candidateLines(rows) {
+    return candidateListing(rows);
+}
+/**
+ * The one enabled connection for `connectorKey` among `rows`, or throw.
+ *
+ * Pure: `rows` is whatever listing the caller fetched, and `scope` is how the
+ * refusal names it. Several candidates is a refusal that lists every one with
+ * its id — a NAME is not a key on a tenant. The eval tenant holds three Slack
+ * connections all named `is-sandboxes` (two Enabled, in different folders), so
+ * the old remedy — "name the one you want with --connection <name>" — handed
+ * back the very flag the caller had just used, and the doc-following author
+ * dead-ended (placeholder GUIDs hand-written into bindings.json, 401 at the
+ * Slack node).
+ */
+export function selectConnection(rows, connectorKey, name, scope = "the tenant") {
+    const matched = enabledConnections(rows, connectorKey, name);
+    if (matched.length === 0) {
+        const qualifier = name ? ` named ${pyRepr(name)}` : "";
+        throw new ConnectionRefusal(`no enabled ${connectorKey} connection${qualifier} found in ${scope}. ` +
+            "List what exists with:\n" +
+            "  uip is connections list --all-folders", "CONNECTION_NONE");
+    }
+    if (matched.length > 1) {
+        const listed = candidateLines(matched);
+        const names = new Set(matched.map((row) => pyStrAny(row.Name)));
+        // Python tested `name is not None`: an empty-string name takes this branch too.
+        const remedy = (name !== undefined && name !== null) || names.size < matched.length
+            ? "They share a name, so --connection <name> cannot pick one; pass " +
+                "the id of the one in the folder you mean with --connection-id:"
+            : "Name the one you want with --connection <name>, or pass its id " +
+                "with --connection-id:";
+        throw new ConnectionRefusal(`${matched.length} enabled ${connectorKey} connections in ${scope}, and they ` +
+            "are not interchangeable — a record that exists in one workspace need " +
+            `not exist in another. ${remedy}\n${listed}`, "CONNECTION_AMBIGUOUS");
+    }
+    return matched[0];
+}
+/**
+ * The one enabled connection for `connectorKey`, fetched, or throw.
+ *
+ * Tries the DEFAULT listing first and only widens to `--all-folders` if that
+ * finds nothing. That order matters and is not just politeness to the API: the
+ * default listing is the caller's own folder, which on a real tenant is one
+ * connection where the tenant-wide view is many. Widening first would turn an
+ * unambiguous case into an ambiguous one.
+ */
+export async function discoverConnection(client, connectorKey, name) {
+    let rows = enabledConnections(await listConnections(client, { allFolders: false }), connectorKey, name);
+    let scope = "your folder";
+    if (rows.length === 0) {
+        rows = enabledConnections(await listConnections(client, { allFolders: true }), connectorKey, name);
+        scope = "the tenant";
+    }
+    return selectConnection(rows, connectorKey, name, scope);
+}
+/**
+ * Every enabled connection for `connectorKey`, own folder FIRST
+ * (`_connections.candidate_connections`).
+ *
+ * {@link discoverConnection} answers "which one" and stops at the first
+ * non-empty scope, which is right for picking a connection and wrong for
+ * retrying one: when the own-folder listing holds exactly one, the tenant-wide
+ * connections are never even looked at. So a lookup that exhausts the
+ * personal-workspace connection reports a bad VALUE while the record sits in
+ * another folder's connection (flow-builder-sdk#744, measured on two Jira
+ * connections where only the second carried project `TS`).
+ *
+ * Ordering is the same preference discovery encodes — the caller's own folder
+ * is the likeliest and is tried first — but nothing is dropped. Deduplicated
+ * by `Id`, because the tenant-wide listing repeats the own-folder rows; a row
+ * with no `Id` is never deduplicated, as the Python's `if identifier and …`
+ * did not.
+ *
+ * This does NOT decide anything, and in particular does not throw on several
+ * matches: choosing among them is the caller's job, and the only honest way to
+ * choose is evidence (a lookup that resolves on exactly one). That keeps this
+ * module's rule intact — ambiguity is never resolved by guessing.
+ */
+export async function candidateConnections(client, connectorKey, name) {
+    const ordered = [];
+    const seen = new Set();
+    for (const allFolders of [false, true]) {
+        for (const row of enabledConnections(await listConnections(client, { allFolders }), connectorKey, name)) {
+            const identifier = pyStrAny(pyGet(row, "Id", ""));
+            if (identifier && seen.has(identifier))
+                continue;
+            seen.add(identifier);
+            ordered.push(row);
+        }
+    }
+    return ordered;
+}
+/** The enabled connections for `connectorKey`, one per line, pasteable. */
+export function enabledListing(rows, connectorKey) {
+    const enabled = enabledConnections(rows, connectorKey);
+    if (enabled.length === 0) {
+        return (`    (none — this tenant has no Enabled ${connectorKey} connection; ` +
+            "repair or create one in Integration Service first)");
+    }
+    return candidateLines(enabled);
+}
+/**
+ * The record for an explicitly named connection among `rows`, or throw unless it can serve.
+ *
+ * An explicit `--connection-id` used to skip every check discovery applies, and
+ * that skip is where a whole class of silent failures came from. A connection
+ * in `State: Failed` is listed like any other, and `uip is resources describe`
+ * against it answers `Result: Success` with NO request fields — the tenant has
+ * no schema to give for a connection it cannot reach. `prepare` then wrote an
+ * overlay with zero body inputs, printed "0 input field(s)" as a success, and
+ * the next `compile` rejected every real field as unknown. Measured on the eval
+ * tenant (Salesforce `Opportunity` / `Update`): the Failed connection returned
+ * 0 request fields, the Enabled one 13.
+ *
+ * So: resolve the id against the listing, and refuse — naming the state found
+ * and the enabled alternatives — rather than describe through it.
+ */
+export function checkConnection(rows, connectorKey, connectionId) {
+    const match = rows.find((row) => pyStrAny(pyGet(row, "Id", "")) === pyStrAny(connectionId));
+    const alternatives = enabledListing(rows, connectorKey);
+    const remedy = "Or omit --connection-id and prepare selects the connection itself.";
+    if (match === undefined) {
+        throw new ConnectionRefusal(`connection ${connectionId} is not in this tenant's listing ` +
+            `(\`uip is connections list --all-folders\`). Enabled ${connectorKey} ` +
+            `connections:\n${alternatives}\n` +
+            remedy, "CONNECTION_UNKNOWN_ID");
+    }
+    const actualKey = match.ConnectorKey;
+    if (pyTruthy(actualKey) && actualKey !== connectorKey) {
+        throw new ConnectionRefusal(`connection ${pyStrAny(match.Name)} (${connectionId}) belongs to connector ` +
+            `${pyStrAny(actualKey)}, not ${connectorKey}. Enabled ${connectorKey} ` +
+            `connections:\n${alternatives}\n` +
+            remedy, "CONNECTION_WRONG_CONNECTOR");
+    }
+    const state = pyStrAny(pyOr(pyGet(match, "State", ""), ""));
+    if (state.toLowerCase() !== "enabled") {
+        const shown = state || "in an unknown state";
+        throw new ConnectionRefusal(`connection ${pyStrAny(match.Name)} (${connectionId}) is ${shown}, not ` +
+            "Enabled. A connection that is not Enabled answers field discovery " +
+            "with an EMPTY schema, so the overlay would carry no fields and the " +
+            "next compile would still reject every input as unknown. Enabled " +
+            `${connectorKey} connections:\n${alternatives}\n` +
+            remedy, "CONNECTION_NOT_ENABLED");
+    }
+    return match;
+}
+/** {@link checkConnection} against the tenant-wide listing — the id may live in another folder. */
+export async function lookupConnection(client, connectorKey, connectionId) {
+    return checkConnection(await listConnections(client, { allFolders: true }), connectorKey, connectionId);
+}
+/**
+ * The enabled BYOA connections for `connectorKey`.
+ *
+ * THROWS on a failed listing rather than answering an empty list. The
+ * difference is the whole point: "you have no BYOA connection" tells the caller
+ * to go create one, and a listing that failed says nothing of the kind.
+ * Answering [] for both turns a broken call into confident, wrong advice.
+ */
+export async function byoaConnections(client, connectorKey) {
+    return enabledConnections(await listConnections(client, { allFolders: true, byoa: true }), connectorKey);
+}
+/** The BYOA candidates, one pasteable line each, or why there are none. */
+export function byoaListing(rows, connectorKey) {
+    if (rows.length === 0) {
+        return (`    (none — this tenant has no enabled BYOA ${connectorKey} ` +
+            "connection; create one in Integration Service with your own " +
+            "OAuth app, then re-run)");
+    }
+    return candidateLines(rows);
+}
+function requiredKey(connection, key) {
+    if (!Object.prototype.hasOwnProperty.call(connection, key)) {
+        throw new Error(`connection record has no ${pyRepr(key)}`); // Python: KeyError
+    }
+    return pyStrAny(connection[key]);
+}
+/**
+ * Add connection + folder entries to a parsed `bindings.json`, without touching the input.
+ *
+ * ADDITIVE AND IDEMPOTENT. An existing entry under the same symbolic name (its
+ * `name` or `id`) is updated, never duplicated, and every other entry is left
+ * exactly as it was — `bindings.json` is an authored file that may already
+ * carry bindings for connectors this run knows nothing about. An updated row
+ * keeps its key order and gains any missing key at the end; a new row is
+ * written `id, name, resource, resourceKey, default, propertyAttribute`.
+ *
+ * `document` is what the file parsed to, or `undefined` when there was no file.
+ * As in the Python, a parsed value that is not an object is replaced by the
+ * default document.
+ */
+export function mergeBindingsDocument(document, symbolicConnection, symbolicFolder, connection) {
+    let out;
+    if (isPlainObject(document)) {
+        const copy = { ...document };
+        if (!Object.prototype.hasOwnProperty.call(copy, "schemaVersion"))
+            copy.schemaVersion = "1";
+        if (!Object.prototype.hasOwnProperty.call(copy, "bindings"))
+            copy.bindings = [];
+        if (!Array.isArray(copy.bindings)) {
+            throw new TypeError(`bindings.json: "bindings" is not a list`); // Python: TypeError iterating it
+        }
+        copy.bindings = copy.bindings.map((entry) => (isPlainObject(entry) ? { ...entry } : entry));
+        out = copy;
+    }
+    else {
+        out = { schemaVersion: "1", bindings: [] };
+    }
+    const bindings = out.bindings;
+    const upsert = (symbolic, key, attribute) => {
+        for (const entry of bindings) {
+            if (!isPlainObject(entry))
+                continue;
+            if (entry.name === symbolic || entry.id === symbolic) {
+                const changed = entry.resourceKey !== key;
+                Object.assign(entry, {
+                    id: pyGet(entry, "id", symbolic),
+                    name: symbolic,
+                    resource: "Connection",
+                    resourceKey: key,
+                    default: key,
+                    propertyAttribute: attribute,
+                });
+                return changed;
+            }
+        }
+        bindings.push({
+            id: symbolic,
+            name: symbolic,
+            resource: "Connection",
+            resourceKey: key,
+            default: key,
+            propertyAttribute: attribute,
+        });
+        return true;
+    };
+    const wroteConnection = upsert(symbolicConnection, requiredKey(connection, "Id"), "ConnectionId");
+    const wroteFolder = upsert(symbolicFolder, requiredKey(connection, "FolderKey"), "FolderKey");
+    return { document: out, wroteConnection, wroteFolder };
+}
+/**
+ * `json.dump(document, indent=2)` + newline: the bytes `bindings.json` is written in.
+ *
+ * `allowIntegerKeys` for the same reason the ledger passes it (`objects.ts`):
+ * `bindings.json` is the author's file and may carry an integer-like key
+ * anywhere in a row this module never looks at. `json.dump` wrote such a file
+ * back; refusing it here left the file untouched and the connection unbound,
+ * with an error about a key the author did not know they had. The one thing
+ * that cannot be kept is that key's position — `JSON.parse` has already
+ * hoisted it to the front of its object — which Python preserved.
+ */
+export function formatBindings(document) {
+    return `${pyJsonStringify(document, { indent: 2, allowIntegerKeys: true })}\n`;
+}
+/**
+ * Add connection + folder entries to `bindings.json` at `path`, in place.
+ *
+ * Returns `[wroteConnection, wroteFolder]` describing what changed, so the
+ * caller can report the specific thing rather than "updated bindings". The file
+ * is always rewritten, as the Python did. A file that will not parse is REFUSED,
+ * not overwritten: it is the author's, and not ours to discard.
+ */
+export function mergeBindings(path, symbolicConnection, symbolicFolder, connection) {
+    let loaded = undefined;
+    if (existsSync(path)) {
+        try {
+            loaded = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            throw new ConnectionRefusal(`${path} exists but is not readable JSON. Fix or remove it; ` +
+                "this command will not overwrite a file it cannot parse.", "BINDINGS_UNREADABLE");
+        }
+    }
+    const merged = mergeBindingsDocument(loaded, symbolicConnection, symbolicFolder, connection);
+    writeFileSync(path, formatBindings(merged.document), "utf8");
+    return [merged.wroteConnection, merged.wroteFolder];
+}
+/**
+ * Remember `bindings.json` byte-for-byte, before a stage that writes it.
+ *
+ * `undefined` means the file could not be read — normally that it did not
+ * exist — and {@link restoreBindings} will remove whatever was written since.
+ */
+export function snapshotBindings(path) {
+    if (!path)
+        return undefined;
+    try {
+        return new Uint8Array(readFileSync(path));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Put `bindings.json` back exactly as {@link snapshotBindings} found it.
+ *
+ * A refusal must leave `bindings.json` as it was: the BYOA fact needs a
+ * connection to discover, so stage 0 has already written one by the time the
+ * event says it is the wrong KIND — without the rollback the overlay keeps
+ * pointing at a connection the tool just forbade. A failure to restore is
+ * reported through `warn` (stderr by default), never thrown: the refusal being
+ * delivered is the message that matters.
+ *
+ * `shown` is the path as the caller typed it (`args.bindings`), which is what
+ * the Python printed; `path` is where the file actually is.
+ */
+export function restoreBindings(path, snapshot, warn = (message) => process.stderr.write(`${message}\n`), shown = path) {
+    if (!path)
+        return;
+    try {
+        if (snapshot === undefined) {
+            if (existsSync(path))
+                rmSync(path);
+        }
+        else {
+            writeFileSync(path, snapshot);
+        }
+    }
+    catch (error) {
+        warn(`  WARN: could not restore ${shown} after refusing the connection: ${messageOf(error)}`);
+    }
+}

package/dist/registry/prepare/event.d.ts

@@ -0,0 +1,96 @@
+import { type BuildContext } from "../library-build/context.js";
+import { type EventFacts } from "../library-build/events.js";
+import { type Dict } from "../library-build/py.js";
+import type { LibraryEntry } from "../model/library.js";
+import type { UipClient } from "../uip/client.js";
+/**
+ * `_event_operation`: 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 `extractCanonical` stamps as `eventOperation` from the manifest's
+ * `model.context`. `name` happens to fall back to the same value when the
+ * manifest omits `connectorMethodInfo.operation`, so reading it works or
+ * silently queries the WRONG operation depending on which fallback rung a
+ * connector's manifest exercises.
+ */
+export declare function eventOperation(operation: Record<string, unknown>): string;
+/** The START and WAIT node types of one event. */
+export declare function eventNodeTypes(connectorKey: string, action: string): {
+    trigger: string;
+    event: string;
+};
+/** The stored definition and its library entry, both re-keyed to the WAIT form. */
+export interface EventDefinition {
+    node: Dict;
+    entry: LibraryEntry;
+}
+/**
+ * The one stored shape (see the module comment): the definition with the
+ * describe folded in, or with the object row's `Parameters` unioned into its
+ * own `eventParameters`; the entry's `outputSchema` taken from the definition's
+ * `outputResponseDefinition` when that has fields. Pure — copies of both inputs.
+ */
+export declare function assembleEventDefinition(node: Dict, entry: LibraryEntry, describe: Dict | undefined, objectRow: Record<string, unknown> | undefined, eventNodeType: string): EventDefinition;
+/** What stage 0 wrote to `bindings.json`, so a refusal here can undo exactly that. */
+export interface BindingsRollback {
+    path: string;
+    /** The file before stage 0 touched it; `undefined` when it did not exist. */
+    snapshot: Uint8Array | undefined;
+    /** `path` as the caller typed `--bindings`, for the lines that name it; defaults to `path`. */
+    shown?: string;
+}
+/**
+ * `_refuse_unless_byoa_connection`: 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 — and the requirement is knowable now.
+ *
+ * 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, so the file is restored first. A listing that FAILED is
+ * not a tenant with no BYOA connections; the remedies are opposite.
+ */
+export declare function refuseUnlessByoaConnection(client: UipClient, connectorKey: string, connectionId: string, rollback: BindingsRollback | undefined, warn: (line: string) => void): Promise<void>;
+export interface EventPrepareOptions {
+    connectorKey: string;
+    action: string;
+    connectionId: string;
+    /** `--object`: the ONE object a Generic event fires for. */
+    objectName?: string | null;
+    allObjects?: boolean;
+    /** The raw `-f` flags — an event has no parent fields, so any is a refusal. */
+    fields?: readonly string[];
+    resolve?: readonly string[];
+    refreshLookups?: boolean;
+    /** The overlay directory to write (resolved). */
+    out: string;
+    /** `out` as the caller spelled `--out`; every printed line names this, as the Python printed `args.out`. Defaults to `out`. */
+    outShown?: string;
+    importSpecifier: string;
+    jsonOnly?: boolean;
+    /** The symbolic names stage 0 bound, for the `next:` subscription. */
+    boundConnection?: string | null;
+    boundFolder?: string | null;
+    bindings?: BindingsRollback;
+    /** How the pasteable `registry prepare` is spelled in the vocabulary print. */
+    prepareCommand?: string;
+}
+export interface EventPrepareResult {
+    eventNodeType: string;
+    operation: string;
+    generic: boolean;
+    /** The API's spelling of the object, for a generic event. */
+    objectName?: string;
+    facts: EventFacts;
+    whereFields: unknown[];
+    filterFields: unknown[];
+    definition: EventDefinition;
+}
+/**
+ * `_prepare_event`. Returns `undefined` when `<key> <action>` is not an event
+ * either, so the caller can raise the ordinary unknown-action refusal;
+ * everything else is handled here, refusals included. `ctx.connectionId` must
+ * already be the connection: the trigger definition only answers with one.
+ */
+export declare function prepareEvent(ctx: BuildContext, options: EventPrepareOptions): Promise<EventPrepareResult | undefined>;