@uipath/maestro-builder-sdk 5.2.0

package/dist/core/binding-messages.d.ts

@@ -0,0 +1 @@
+export declare function bindingSelfNameMessage(where: string, name: string, attribute: 'connection' | 'folder'): string;

package/dist/core/binding-messages.js

@@ -0,0 +1,16 @@
+/**
+ * The refusal for a bindings.json entry that answers with its own name — shared by
+ * `serialize` (which throws it) and `check` (BINDING_SELF_NAME), so the author reads
+ * the same sentence from the inner loop as from compile. Before this, `check`
+ * printed `0 error(s)` for a source `compile` then refused (teams-decision,
+ * 2026-09-01, turn 22 → 23).
+ */
+import { prepareCommand } from './cli-spelling.js';
+export function bindingSelfNameMessage(where, name, attribute) {
+    return `${where}: binding "${name}" resolves to its own name, so the ${attribute} would compile to the `
+        + `literal string "${name}" and the run would fault with "'Connection' has an invalid GUID value: `
+        + `'${name}'". Set its "resourceKey" to the real id: \`${prepareCommand('<connector-key>', '<action>')}\` `
+        + `discovers the connection and writes both the connection and the folder entry into bindings.json; by hand, `
+        + `read Id and FolderKey from \`uip is connections list --all-folders --output json\` (the default listing `
+        + `shows only your own folder, so a connection shared from another folder is invisible without --all-folders).`;
+}

package/dist/core/bindings.d.ts

@@ -0,0 +1,12 @@
+export declare class Bindings {
+    private list;
+    constructor(file?: string);
+    /** Resolve by binding `name` or `id`; returns its resourceKey (or default). */
+    resolve(name?: string): string | undefined;
+    /** Every symbolic name the file declares — what an author CAN write in `connection:` / `folder:`. */
+    declared(): string[];
+    /** The full binding entry by `name` or `id` — for consumers that emit a binding
+     * registry + `=bindings.<id>` refs (the Case caseplan) rather than inlining the
+     * resourceKey (the Flow node). */
+    entry(name?: string): Record<string, unknown> | undefined;
+}

package/dist/core/bindings.js

@@ -0,0 +1,67 @@
+/**
+ * bindings — resolve symbolic connection/folder names to their resource keys
+ * from a bindings.json (same format the Flow Code arm uses).
+ */
+import { readFileSync, existsSync } from 'node:fs';
+export class Bindings {
+    list = [];
+    constructor(file) {
+        if (file && existsSync(file)) {
+            this.list = normalizeBindings(JSON.parse(readFileSync(file, 'utf8')));
+        }
+    }
+    /** Resolve by binding `name` or `id`; returns its resourceKey (or default). */
+    resolve(name) {
+        if (!name)
+            return undefined;
+        const b = this.list.find((x) => x.name === name || x.id === name);
+        if (!b)
+            return undefined;
+        return (b.resourceKey ?? b.default);
+    }
+    /** Every symbolic name the file declares — what an author CAN write in `connection:` / `folder:`. */
+    declared() {
+        const names = [];
+        for (const b of this.list) {
+            const n = (b?.name ?? b?.id);
+            if (typeof n === 'string' && !names.includes(n))
+                names.push(n);
+        }
+        return names;
+    }
+    /** The full binding entry by `name` or `id` — for consumers that emit a binding
+     * registry + `=bindings.<id>` refs (the Case caseplan) rather than inlining the
+     * resourceKey (the Flow node). */
+    entry(name) {
+        if (!name)
+            return undefined;
+        return this.list.find((x) => x.name === name || x.id === name);
+    }
+}
+/**
+ * Accept the shapes a real `bindings.json` turns up in, rather than assuming the array.
+ *
+ * The declared format is `{ bindings: [ { id, name, resourceKey, default, … } ] }`. But this
+ * file name is shared: the local BPMN engine's `--bindings` reads a NAME→VALUE MAP, either
+ * flat or under a `bindings` key, and anyone running a process locally writes one of those.
+ * The old code did `parsed.bindings ?? []` and then `.find(…)` on it, so a map crashed
+ * `compile` with `this.list.find is not a function` — no file named, no format explained. It
+ * cost real debugging time when a bindings.json written for a local run happened to sit in the
+ * compile directory, and an author told to write one for a live run can easily produce the map
+ * form.
+ *
+ * A map entry becomes `{ id, name, resourceKey, default }` with the value in all three
+ * key-ish slots, which is what `resolve`/`entry` read, so both formats behave the same.
+ */
+function normalizeBindings(parsed) {
+    if (parsed === null || typeof parsed !== 'object')
+        return [];
+    const inner = 'bindings' in parsed ? parsed.bindings : parsed;
+    if (Array.isArray(inner))
+        return inner;
+    if (inner === null || typeof inner !== 'object')
+        return [];
+    return Object.entries(inner)
+        .filter(([, value]) => typeof value === 'string')
+        .map(([id, value]) => ({ id, name: id, resourceKey: value, default: value }));
+}

package/dist/core/ceql.d.ts

@@ -0,0 +1,73 @@
+/**
+ * core/ceql — parse a CEQL filter expression into the canonical filter tree.
+ *
+ * ## Why a filter needs two representations
+ *
+ * An Integration Service list operation takes a server-side filter through a
+ * "FilterBuilder" parameter — usually named `where`, sometimes `q`. Two
+ * consumers read it, and they want different things:
+ *
+ * - the RUNTIME dials IS with a CEQL string, `inputs.detail.queryParameters.where`;
+ * - the Studio Web CANVAS renders the filter widget from a structured tree, at
+ *   `essentialConfiguration.savedFilterTrees.where` inside the node's
+ *   `=jsonString:`-encoded `inputs.detail.configuration`.
+ *
+ * A string cannot be reverse-engineered into the widget's model reliably, so the
+ * artifact carries both. Author only the string and the flow RUNS correctly while
+ * the FilterBuilder shows nothing when the activity is reopened — which is why
+ * product validation rejects a `queryParameters.<name>` with no matching
+ * `savedFilterTrees.<name>` (MST-9265), even though a debug run would pass.
+ *
+ * The v1 CLI solved this by making the TREE the input (`node configure
+ * --detail.filter`) and compiling the string from it. The builder SDK has no
+ * such command, so this goes the other way: authors write the CEQL they would
+ * write anyway, and the tree is DERIVED. One source of truth either way.
+ *
+ * ## Scope
+ *
+ * Deliberately a literal-only parser. A filter whose operand is a runtime
+ * expression compiles to a `{var_…}` placeholder plus `inputs.detail.filterVariables`
+ * on the v1 path; nothing here can produce that from a `=js:` string, and
+ * guessing would emit a tree that disagrees with the query. Such a filter keeps
+ * its runtime half and gets no tree — the same state as before this existed,
+ * rather than a wrong one.
+ */
+/** A leaf's comparison operator, in the canonical PascalCase the canvas stores. */
+export type CeqlOperator = 'Equals' | 'NotEquals' | 'LessThan' | 'LessThanOrEqual' | 'GreaterThan' | 'GreaterThanOrEqual' | 'Contains' | 'NotContains' | 'StartsWith' | 'NotStartsWith' | 'EndsWith' | 'NotEndsWith' | 'Like' | 'NotLike' | 'IsNull' | 'IsNotNull';
+/** One comparison — `<field> <operator> <value>`. */
+export interface CeqlFilter {
+    id: string;
+    operator: CeqlOperator;
+    value?: {
+        value: unknown;
+        rawString: string;
+        isLiteral: true;
+    };
+    uiId?: string;
+}
+/** A group of comparisons joined by one logical operator. Groups nest. */
+export interface CeqlTree {
+    /** 0 = And, 1 = Or — how this level's siblings combine. */
+    groupOperator: 0 | 1;
+    index: number;
+    filters: CeqlFilter[];
+    groups: CeqlTree[];
+    uuId?: string;
+}
+/** Raised when an expression is not CEQL this parser can represent. */
+export declare class CeqlParseError extends Error {
+    readonly expression: string;
+    constructor(message: string, expression: string);
+}
+/**
+ * Parse a CEQL filter expression into the canvas's filter tree.
+ *
+ * `seed` makes the tree's ids deterministic — recompiling an unchanged flow must
+ * be byte-identical, so the node id and parameter name are folded in rather than
+ * minting random uuids the way the designer does.
+ *
+ * Throws {@link CeqlParseError} with the reason when the expression is not CEQL
+ * this can represent. That is the point: the alternative is a tenant-side
+ * `[102003] Integration Services bad request` with nothing naming the step.
+ */
+export declare function parseCeql(expression: string, seed: string): CeqlTree;

package/dist/core/ceql.js

@@ -0,0 +1,272 @@
+/**
+ * core/ceql — parse a CEQL filter expression into the canonical filter tree.
+ *
+ * ## Why a filter needs two representations
+ *
+ * An Integration Service list operation takes a server-side filter through a
+ * "FilterBuilder" parameter — usually named `where`, sometimes `q`. Two
+ * consumers read it, and they want different things:
+ *
+ * - the RUNTIME dials IS with a CEQL string, `inputs.detail.queryParameters.where`;
+ * - the Studio Web CANVAS renders the filter widget from a structured tree, at
+ *   `essentialConfiguration.savedFilterTrees.where` inside the node's
+ *   `=jsonString:`-encoded `inputs.detail.configuration`.
+ *
+ * A string cannot be reverse-engineered into the widget's model reliably, so the
+ * artifact carries both. Author only the string and the flow RUNS correctly while
+ * the FilterBuilder shows nothing when the activity is reopened — which is why
+ * product validation rejects a `queryParameters.<name>` with no matching
+ * `savedFilterTrees.<name>` (MST-9265), even though a debug run would pass.
+ *
+ * The v1 CLI solved this by making the TREE the input (`node configure
+ * --detail.filter`) and compiling the string from it. The builder SDK has no
+ * such command, so this goes the other way: authors write the CEQL they would
+ * write anyway, and the tree is DERIVED. One source of truth either way.
+ *
+ * ## Scope
+ *
+ * Deliberately a literal-only parser. A filter whose operand is a runtime
+ * expression compiles to a `{var_…}` placeholder plus `inputs.detail.filterVariables`
+ * on the v1 path; nothing here can produce that from a `=js:` string, and
+ * guessing would emit a tree that disagrees with the query. Such a filter keeps
+ * its runtime half and gets no tree — the same state as before this existed,
+ * rather than a wrong one.
+ */
+import { stableId } from './stable-id.js';
+/** Raised when an expression is not CEQL this parser can represent. */
+export class CeqlParseError extends Error {
+    expression;
+    constructor(message, expression) {
+        super(message);
+        this.expression = expression;
+        this.name = 'CeqlParseError';
+    }
+}
+/**
+ * Word operators, longest first so `Not Contains` wins over `Contains` and
+ * `Is Not Null` over `Is Null`. Matched case-insensitively with flexible inner
+ * spacing, because the platform's own rendering is `Starts With` but authors
+ * write `startswith` as often as not.
+ */
+const WORD_OPERATORS = [
+    [/^is\s+not\s+null\b/i, 'IsNotNull'],
+    [/^is\s+null\b/i, 'IsNull'],
+    [/^not\s+starts\s*with\b/i, 'NotStartsWith'],
+    [/^not\s+ends\s*with\b/i, 'NotEndsWith'],
+    [/^not\s+contains\b/i, 'NotContains'],
+    [/^not\s+like\b/i, 'NotLike'],
+    [/^starts\s*with\b/i, 'StartsWith'],
+    [/^ends\s*with\b/i, 'EndsWith'],
+    [/^contains\b/i, 'Contains'],
+    [/^like\b/i, 'Like'],
+];
+/** Symbol operators, longest first so `<=` wins over `<` and `!=` over `=`. */
+const SYMBOL_OPERATORS = [
+    ['>=', 'GreaterThanOrEqual'],
+    ['<=', 'LessThanOrEqual'],
+    ['!=', 'NotEquals'],
+    ['>', 'GreaterThan'],
+    ['<', 'LessThan'],
+    ['=', 'Equals'],
+];
+/**
+ * The OData spellings CEQL rejects. Named explicitly because the failure is
+ * otherwise a `[102003] Integration Services bad request` from the tenant, with
+ * nothing pointing at the operator.
+ */
+const ODATA_ALIASES = {
+    eq: '=', ne: '!=', gt: '>', ge: '>=', lt: '<', le: '<=',
+};
+class Scanner {
+    src;
+    pos = 0;
+    constructor(src) {
+        this.src = src;
+    }
+    get rest() { return this.src.slice(this.pos); }
+    skipSpace() {
+        while (this.pos < this.src.length && /\s/.test(this.src[this.pos]))
+            this.pos++;
+    }
+    /** Consume `text` (case-insensitive) when it is next; report whether it was. */
+    eat(text) {
+        this.skipSpace();
+        if (this.src.slice(this.pos, this.pos + text.length).toLowerCase() !== text.toLowerCase())
+            return false;
+        // A word must not be consumed out of the middle of an identifier.
+        if (/\w$/.test(text)) {
+            const after = this.src[this.pos + text.length];
+            if (after !== undefined && /[\w.]/.test(after))
+                return false;
+        }
+        this.pos += text.length;
+        return true;
+    }
+    atEnd() { this.skipSpace(); return this.pos >= this.src.length; }
+}
+/** `displayName`, `user.department` — bare, never quoted (a quoted token is a value). */
+function readField(s) {
+    s.skipSpace();
+    const m = /^[A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)*/.exec(s.rest);
+    if (!m) {
+        if (/^['"]/.test(s.rest)) {
+            throw new CeqlParseError(`quoted field name at "${s.rest.slice(0, 24)}" — CEQL reads a quoted token as a value, `
+                + 'so write the field bare: `displayName = \'active\'`, never `\'displayName\' = \'active\'`.', s.src);
+        }
+        throw new CeqlParseError(`expected a field name at "${s.rest.slice(0, 24) || '<end>'}"`, s.src);
+    }
+    s.pos += m[0].length;
+    return m[0];
+}
+function readOperator(s) {
+    s.skipSpace();
+    for (const [pattern, op] of WORD_OPERATORS) {
+        const m = pattern.exec(s.rest);
+        if (m) {
+            s.pos += m[0].length;
+            return op;
+        }
+    }
+    const alias = /^([A-Za-z]+)\b/.exec(s.rest);
+    if (alias && ODATA_ALIASES[alias[1].toLowerCase()]) {
+        const wrong = alias[1];
+        throw new CeqlParseError(`\`${wrong}\` is an OData operator; CEQL uses \`${ODATA_ALIASES[wrong.toLowerCase()]}\`.`, s.src);
+    }
+    for (const [text, op] of SYMBOL_OPERATORS) {
+        if (s.src.startsWith(text, s.pos)) {
+            s.pos += text.length;
+            return op;
+        }
+    }
+    throw new CeqlParseError(`expected an operator at "${s.rest.slice(0, 24) || '<end>'}"`, s.src);
+}
+/** A single-quoted string, a number, or a boolean. Doubled `''` escapes a quote. */
+function readValue(s) {
+    s.skipSpace();
+    if (s.rest.startsWith("'")) {
+        let i = 1;
+        let text = '';
+        for (;;) {
+            if (i >= s.rest.length)
+                throw new CeqlParseError('unterminated string value', s.src);
+            const ch = s.rest[i];
+            if (ch === "'") {
+                if (s.rest[i + 1] === "'") {
+                    text += "'";
+                    i += 2;
+                    continue;
+                }
+                i++;
+                break;
+            }
+            text += ch;
+            i++;
+        }
+        s.pos += i;
+        return { value: text, rawString: JSON.stringify(text) };
+    }
+    if (s.rest.startsWith('"')) {
+        throw new CeqlParseError('double-quoted value — CEQL reads a double-quoted token as a COLUMN reference, not a string. '
+            + "Single-quote it: `accountNumber = 'ACC123'`.", s.src);
+    }
+    const bool = /^(true|false)\b/i.exec(s.rest);
+    if (bool) {
+        s.pos += bool[0].length;
+        const value = bool[0].toLowerCase() === 'true';
+        return { value, rawString: String(value) };
+    }
+    const num = /^-?\d+(?:\.\d+)?/.exec(s.rest);
+    if (num) {
+        s.pos += num[0].length;
+        return { value: Number(num[0]), rawString: num[0] };
+    }
+    throw new CeqlParseError(`expected a quoted string, number, or boolean at "${s.rest.slice(0, 24) || '<end>'}"`, s.src);
+}
+function readComparison(s, seed, ordinal) {
+    const id = readField(s);
+    const operator = readOperator(s);
+    const uiId = stableId(`${seed}:${id}:${ordinal}`);
+    if (operator === 'IsNull' || operator === 'IsNotNull')
+        return { id, operator, uiId };
+    const { value, rawString } = readValue(s);
+    return { id, operator, value: { value, rawString, isLiteral: true }, uiId };
+}
+/**
+ * One level: comparisons and parenthesised sub-groups joined by a SINGLE logical
+ * operator.
+ *
+ * Mixing `AND` and `OR` at one level is refused rather than guessed. The tree has
+ * exactly one `groupOperator` per level, so `a = 1 AND b = 2 OR c = 3` has no
+ * faithful representation — and picking a precedence would silently emit a tree
+ * that filters differently from the string beside it, which is the one outcome
+ * worse than not supporting it. Parenthesise to say which was meant.
+ */
+function readGroup(s, seed, index, depth) {
+    if (depth > 32)
+        throw new CeqlParseError('filter nests too deeply', s.src);
+    const filters = [];
+    const groups = [];
+    let groupOperator;
+    let ordinal = 0;
+    for (;;) {
+        s.skipSpace();
+        if (s.rest.startsWith('(')) {
+            s.pos++;
+            groups.push(readGroup(s, `${seed}:g${groups.length}`, groups.length, depth + 1));
+            s.skipSpace();
+            if (!s.eat(')'))
+                throw new CeqlParseError('unbalanced parenthesis', s.src);
+        }
+        else {
+            filters.push(readComparison(s, seed, ordinal++));
+        }
+        const before = s.pos;
+        if (s.eat('AND')) {
+            if (groupOperator === 1) {
+                s.pos = before;
+                throw new CeqlParseError('AND and OR are mixed at one level. A filter tree carries one operator per level, so '
+                    + 'parenthesise the intent: `(a AND b) OR c`.', s.src);
+            }
+            groupOperator = 0;
+            continue;
+        }
+        if (s.eat('OR')) {
+            if (groupOperator === 0) {
+                s.pos = before;
+                throw new CeqlParseError('AND and OR are mixed at one level. A filter tree carries one operator per level, so '
+                    + 'parenthesise the intent: `(a OR b) AND c`.', s.src);
+            }
+            groupOperator = 1;
+            continue;
+        }
+        break;
+    }
+    return { groupOperator: groupOperator ?? 0, index, filters, groups, uuId: stableId(`${seed}:group`) };
+}
+/**
+ * Parse a CEQL filter expression into the canvas's filter tree.
+ *
+ * `seed` makes the tree's ids deterministic — recompiling an unchanged flow must
+ * be byte-identical, so the node id and parameter name are folded in rather than
+ * minting random uuids the way the designer does.
+ *
+ * Throws {@link CeqlParseError} with the reason when the expression is not CEQL
+ * this can represent. That is the point: the alternative is a tenant-side
+ * `[102003] Integration Services bad request` with nothing naming the step.
+ */
+export function parseCeql(expression, seed) {
+    const trimmed = expression.trim();
+    if (trimmed === '')
+        throw new CeqlParseError('empty filter expression', expression);
+    const s = new Scanner(trimmed);
+    const tree = readGroup(s, seed, 0, 0);
+    if (!s.atEnd()) {
+        throw new CeqlParseError(`unexpected "${s.rest.slice(0, 24)}" after the filter`, expression);
+    }
+    // A lone parenthesised expression parses as a group holding one group. Lift it,
+    // so `(a = 1)` and `a = 1` produce the same tree.
+    if (tree.filters.length === 0 && tree.groups.length === 1) {
+        return { ...tree.groups[0], index: tree.index, uuId: tree.uuId };
+    }
+    return tree;
+}

package/dist/core/cli-spelling.d.ts

@@ -0,0 +1,39 @@
+/**
+ * core/cli-spelling — naming the CLI the user is actually holding.
+ *
+ * Every remedy `check` prints is a command meant to be pasted. Which binary
+ * spells it depends on how the SDK was reached, and the SDK cannot see that:
+ * `@uipath/cli` resolves the workspace SDK and spawns `dist/cli/index.js`, so
+ * by the time this code runs, `process.argv[1]` is the SDK's own bin either
+ * way. The caller knows, and passes it down in `FLOW_SDK_INVOKED_AS`.
+ *
+ * The default stays `npx flow-sdk`, which is what a workspace with no `uip`
+ * needs and what the original hard-coding was protecting.
+ */
+/** The spelling used when nothing says otherwise. */
+export declare const DEFAULT_CLI_SPELLING = "npx flow-sdk";
+/** Just the variable this module reads — see {@link cliSpelling} for why. */
+export interface CliSpellingEnv {
+    FLOW_SDK_INVOKED_AS?: string | undefined;
+}
+/**
+ * How to spell the CLI in a printed remedy.
+ *
+ * @param env - Environment to read; defaults to the ambient `process.env`.
+ * @returns `uip maestro` when the caller said so, else `npx flow-sdk`.
+ */
+export declare function cliSpelling(env?: CliSpellingEnv): string;
+/**
+ * A `registry prepare` command line, spelled for whoever is driving.
+ *
+ * @param args - Everything after `registry prepare`, e.g. the connector key and action.
+ * @returns The full command, no trailing newline.
+ *
+ * @example
+ * ```ts
+ * prepareCommand('uipath-salesforce-slack', 'send-message-to-user');
+ * // -> "npx flow-sdk registry prepare uipath-salesforce-slack send-message-to-user"
+ * // -> "uip maestro registry prepare …" when FLOW_SDK_INVOKED_AS="uip maestro"
+ * ```
+ */
+export declare function prepareCommand(...args: string[]): string;

package/dist/core/cli-spelling.js

@@ -0,0 +1,62 @@
+/**
+ * core/cli-spelling — naming the CLI the user is actually holding.
+ *
+ * Every remedy `check` prints is a command meant to be pasted. Which binary
+ * spells it depends on how the SDK was reached, and the SDK cannot see that:
+ * `@uipath/cli` resolves the workspace SDK and spawns `dist/cli/index.js`, so
+ * by the time this code runs, `process.argv[1]` is the SDK's own bin either
+ * way. The caller knows, and passes it down in `FLOW_SDK_INVOKED_AS`.
+ *
+ * The default stays `npx flow-sdk`, which is what a workspace with no `uip`
+ * needs and what the original hard-coding was protecting.
+ */
+/** The spelling used when nothing says otherwise. */
+export const DEFAULT_CLI_SPELLING = 'npx flow-sdk';
+/**
+ * Lowercase words, single-spaced, at most three.
+ *
+ * The value is interpolated into a command a human is invited to paste into a
+ * shell, so it is validated rather than trusted: an unset-but-inherited or
+ * malformed value must degrade to the default, not travel into someone's
+ * terminal. `npx flow-sdk` and `uip maestro` both satisfy it.
+ */
+const SPELLING = /^[a-z][a-z0-9-]*(?: [a-z][a-z0-9-]*){0,2}$/;
+/**
+ * `process.env`, read through `globalThis` so this module needs no Node types.
+ *
+ * `core/lookups.ts` imports this one, and the generated connector modules are
+ * type-checked against the SDK SOURCE under `strict` with no `@types/node`
+ * (see `tests/connectors.test.ts`). Naming `NodeJS.ProcessEnv` or a bare
+ * `process` here fails that check, which is a real constraint and not a
+ * formality: it is the same graph an author's `tsc` walks.
+ */
+function ambientEnv() {
+    const global = globalThis;
+    return global.process?.env ?? {};
+}
+/**
+ * How to spell the CLI in a printed remedy.
+ *
+ * @param env - Environment to read; defaults to the ambient `process.env`.
+ * @returns `uip maestro` when the caller said so, else `npx flow-sdk`.
+ */
+export function cliSpelling(env = ambientEnv()) {
+    const hint = (env.FLOW_SDK_INVOKED_AS ?? '').trim();
+    return SPELLING.test(hint) ? hint : DEFAULT_CLI_SPELLING;
+}
+/**
+ * A `registry prepare` command line, spelled for whoever is driving.
+ *
+ * @param args - Everything after `registry prepare`, e.g. the connector key and action.
+ * @returns The full command, no trailing newline.
+ *
+ * @example
+ * ```ts
+ * prepareCommand('uipath-salesforce-slack', 'send-message-to-user');
+ * // -> "npx flow-sdk registry prepare uipath-salesforce-slack send-message-to-user"
+ * // -> "uip maestro registry prepare …" when FLOW_SDK_INVOKED_AS="uip maestro"
+ * ```
+ */
+export function prepareCommand(...args) {
+    return [cliSpelling(), 'registry', 'prepare', ...args.filter(Boolean)].join(' ');
+}

package/dist/core/connector-raw-node.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Why a `rawNode` may not carry a connector node type, or `undefined` when the
+ * type is not a connector's.
+ *
+ * Every entry of the connector library is `uipath.connector.<key>.<action>`
+ * (7,455 of 7,455 measured), and every one of them needs what only
+ * {@link connector} produces: `inputs.detail` routed by field location plus the
+ * flow-level connection/folder bindings. A raw node renders the author's inputs
+ * as they are, so the artifact compiles, `validate` merely warns that the
+ * connector "is not configured", and the run has no connection to call. Measured
+ * on the eval archive: 4 of 4 Data Fabric flows authored this way failed their
+ * checker, each after `compile` had refused an input the static library does not
+ * carry — the raw node was the escape hatch around that refusal.
+ *
+ * Event and trigger types (`uipath.connector.event.*`, `uipath.connector.trigger.*`)
+ * are named separately: they belong to {@link onEvent}, not to a step.
+ *
+ * @param nodeType - The definition's `nodeType`, as passed to {@link rawNode}.
+ * @returns The refusal to report, or `undefined` for a non-connector type.
+ */
+export declare function connectorRawNodeRefusal(nodeType: string): string | undefined;

package/dist/core/connector-raw-node.js

@@ -0,0 +1,47 @@
+/**
+ * Internal: the one rule that keeps `rawNode` from standing in for `connector()`.
+ * Not re-exported from the package entry point.
+ */
+import { prepareCommand } from './cli-spelling.js';
+/**
+ * Why a `rawNode` may not carry a connector node type, or `undefined` when the
+ * type is not a connector's.
+ *
+ * Every entry of the connector library is `uipath.connector.<key>.<action>`
+ * (7,455 of 7,455 measured), and every one of them needs what only
+ * {@link connector} produces: `inputs.detail` routed by field location plus the
+ * flow-level connection/folder bindings. A raw node renders the author's inputs
+ * as they are, so the artifact compiles, `validate` merely warns that the
+ * connector "is not configured", and the run has no connection to call. Measured
+ * on the eval archive: 4 of 4 Data Fabric flows authored this way failed their
+ * checker, each after `compile` had refused an input the static library does not
+ * carry — the raw node was the escape hatch around that refusal.
+ *
+ * Event and trigger types (`uipath.connector.event.*`, `uipath.connector.trigger.*`)
+ * are named separately: they belong to {@link onEvent}, not to a step.
+ *
+ * @param nodeType - The definition's `nodeType`, as passed to {@link rawNode}.
+ * @returns The refusal to report, or `undefined` for a non-connector type.
+ */
+export function connectorRawNodeRefusal(nodeType) {
+    if (typeof nodeType !== 'string' || !nodeType.startsWith('uipath.connector.'))
+        return undefined;
+    const rest = nodeType.slice('uipath.connector.'.length);
+    const isTrigger = rest.startsWith('event.') || rest.startsWith('trigger.');
+    if (isTrigger) {
+        return (`rawNode("${nodeType}") names a connector event, which cannot be placed as a step and cannot be `
+            + `authored raw: use onEvent(...) as the flow's trigger (or waitForEvent(...) mid-flow) so the `
+            + `subscription and its connection binding are emitted.`);
+    }
+    const dot = rest.lastIndexOf('.');
+    const key = dot > 0 ? rest.slice(0, dot) : rest;
+    const action = dot > 0 ? rest.slice(dot + 1) : '<action>';
+    return (`rawNode("${nodeType}") names a connector operation. A raw node keeps its inputs verbatim, so the `
+        + `emitted node would have no inputs.detail and no connection binding: \`validate\` only warns `
+        + `("Connector is not configured") and the run can never reach Integration Service. `
+        + `Author it as connector('${key}', '${action}', { ...inputs }, { connection: '<binding>', folder: '<binding>' }). `
+        + `If compile then refuses an input the static library does not carry, run `
+        + `\`${prepareCommand(key, action)}\` — it discovers the connection, writes bindings.json `
+        + `and loads the connection-resolved fields into ./connectors-local/ (add \`-f <parent>=<value>\`, e.g. `
+        + `\`-f entityName=<Entity>\`, when the operation's fields depend on a parent input).`);
+}