@uipath/maestro-builder-sdk 6.16.14 → 6.17.1

package/dist/core/cli-library.js

@@ -16,7 +16,7 @@
  */
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { Library } from './library.js';
+import { ConnectorResolveError, Library } from './library.js';
 import { resolveLibraryDir } from './library-cache.js';
 import { flagValue } from '../cli-run.js';
 import { defaultOverlayDir } from '../workdir.js';
@@ -41,19 +41,28 @@ export function openCliLibrary(argv) {
  * The connector half of a family's check options, from a library the CLI already
  * opened.
  *
- * Every callback fails OPEN: an entry the library cannot resolve, or no library
- * at all, means "unknown", and an unknown fact fires no rule. That is what lets
- * `check` stay the fast inner-loop rung — a process with no connectors needs no
- * library, and one whose connector is absent from the library is `compile`'s
- * business to name, not this pass's to guess at.
+ * Every fact callback fails OPEN: no library at all, or an entry the library
+ * cannot resolve, means "unknown", and an unknown fact fires no rule. That is
+ * what lets `check` stay the fast inner-loop rung — a process with no
+ * connectors needs no library. The one exception is the resolution itself:
+ * `connectorResolveError` reports the refusal `compile` would throw for an
+ * action, the way `eventResolveError` does for an event, so `check` never
+ * passes a connector step `compile` refuses (#948).
+ *
+ * `inputErrors` is the family's field-contract validator. The default speaks
+ * the `=`-expression dialect BPMN uses; Flow passes its own, which renders its
+ * expressions (see `flowCheckOpts` in `../cli-library.ts`).
  *
  * The `resolutions` are the overlay's: without them every lookup already
  * recorded by `registry prepare --resolve` would be reported as still owed,
  * telling the author to re-run a prepare they already ran.
  */
-export function connectorCheckOpts(library, bindings) {
+export function connectorCheckOpts(library, bindings, inputErrors = (rc, inputs, resolutions, lookups) => connectorInputErrors(rc, inputs, resolutions, lookups, { dialect: EQUALS_EXPR_DIALECT })) {
     if (!library)
         return bindings ? { bindings } : {};
+    // One memoized resolve per connector step, shared by `connectorResolveError`
+    // and `connectorInputs`, so the second hook does not resolve again.
+    const resolve = connectorResolver(library);
     return {
         eventResolveError: eventResolveErrorFor(library),
         ...byoaCheckOpts(library),
@@ -85,26 +94,51 @@ export function connectorCheckOpts(library, bindings) {
                 return undefined;
             }
         },
+        // The refusal compile throws for an operation it cannot resolve, with its
+        // code and text: CONNECTOR_NOT_IN_LIBRARY, CONNECTOR_OBJECT_REQUIRED,
+        // CONNECTOR_OBJECT_NOT_GENERIC.
+        connectorResolveError: (spec) => {
+            const r = resolve(spec);
+            return 'error' in r ? r.error : undefined;
+        },
         // The field contract compile enforces, from the same validator, so the inner
         // loop and the emit rung cannot disagree about a missing required field, an
-        // unknown key or a mistyped value. An operation the library cannot resolve is
-        // compile's business to name — here it just means "unknown".
-        //
-        // The `=`-expression dialect, because this bag serves the families that spell
-        // an expression that way. Flow binds its own `connectorInputErrors` in
-        // `serialize.ts`, which carries `renderDeep` with it, and overrides this.
+        // unknown key or a mistyped value. An unresolvable operation is
+        // `connectorResolveError`'s to report; here it just means "unknown".
         connectorInputs: (spec, inputs) => {
-            try {
-                const rc = library.resolve(spec.key, spec.action, spec.version, spec.object);
-                return connectorInputErrors(rc, inputs, library.lookupResolutions ?? {}, library.lookupSpecs(spec.key, spec.action, spec.version, spec.object) ?? {}, { dialect: EQUALS_EXPR_DIALECT });
-            }
-            catch {
+            const r = resolve(spec);
+            if (!('rc' in r))
                 return undefined;
-            }
+            return inputErrors(r.rc, inputs, library.lookupResolutions ?? {}, library.lookupSpecs(spec.key, spec.action, spec.version, spec.object) ?? {});
         },
         ...(bindings ? { bindings } : {}),
     };
 }
+/**
+ * `library.resolve` for one connector step, memoized per step for the life of
+ * one check's options. A {@link ConnectorResolveError} is the refusal compile
+ * throws and becomes `error`; anything else thrown is not a verdict about the
+ * author's source and stays "unknown", as before.
+ */
+function connectorResolver(library) {
+    const memo = new Map();
+    return (spec) => {
+        const id = JSON.stringify([spec.key, spec.action, spec.version ?? null, spec.object ?? null]);
+        let r = memo.get(id);
+        if (!r) {
+            try {
+                r = { rc: library.resolve(spec.key, spec.action, spec.version, spec.object) };
+            }
+            catch (error) {
+                r = error instanceof ConnectorResolveError
+                    ? { error: { code: error.code, message: error.message } }
+                    : { unknown: true };
+            }
+            memo.set(id, r);
+        }
+        return r;
+    };
+}
 /**
  * `check`'s EVENT_UNKNOWN verdict: the message `library.resolveEvent` throws
  * for a subscription, or `undefined` when it resolves.

package/dist/core/comment-text.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Text that is safe inside a generated `//` or `/* … *\/` comment.
+ *
+ * A decompiler or generator that splices an input string into a comment hands that
+ * string the rest of the comment: a line terminator ends a `//` comment, `*\/` ends a
+ * block, and whatever follows is CODE in a file `compile` later executes. Those are the
+ * only two ways out of a JavaScript comment, so replacing both (line terminators — LF,
+ * CR, U+2028, U+2029 — with one space, `*\/` with `* /`) is complete, not a denylist.
+ * The replacements are the ones registry/generators already used, so their output keeps
+ * its bytes. FB006 holds every comment interpolation to this function.
+ *
+ * The result is ONE line: a multi-line value is flattened, which is right for a `//`
+ * line or a single ` * ` body line. To keep a value's line breaks, use `commentLines`
+ * (one escaped, prefixed line per input line) or `docComment` (a whole `/** … *\/`).
+ */
+export declare function commentText(value: string | number): string;
+/**
+ * `value` split on its line terminators, each line escaped by `commentText` and
+ * given `prefix` (`'// '`, `' * '`), trailing whitespace trimmed so a blank line is
+ * a bare `//` or ` *`. The lines are joined with `\n` by the caller, so a value's
+ * paragraph breaks survive and none of them can end the comment.
+ */
+export declare function commentLines(value: string | number, prefix?: string): string[];
+/**
+ * A JSDoc comment holding `value`, at `indent`. A one-line value keeps the
+ * one-line form, `/** value *\/`, so its bytes do not change; a multi-line value
+ * gets an open block with one ` * ` line per input line.
+ */
+export declare function docComment(value: string | number, indent?: string): string[];

package/dist/core/comment-text.js

@@ -0,0 +1,40 @@
+/** The line terminators (LF, CR, CRLF, U+2028, U+2029): the one way out of a `//` comment. */
+const LINE_BREAK = /\r\n?|[\n\u2028\u2029]/g;
+/**
+ * Text that is safe inside a generated `//` or `/* … *\/` comment.
+ *
+ * A decompiler or generator that splices an input string into a comment hands that
+ * string the rest of the comment: a line terminator ends a `//` comment, `*\/` ends a
+ * block, and whatever follows is CODE in a file `compile` later executes. Those are the
+ * only two ways out of a JavaScript comment, so replacing both (line terminators — LF,
+ * CR, U+2028, U+2029 — with one space, `*\/` with `* /`) is complete, not a denylist.
+ * The replacements are the ones registry/generators already used, so their output keeps
+ * its bytes. FB006 holds every comment interpolation to this function.
+ *
+ * The result is ONE line: a multi-line value is flattened, which is right for a `//`
+ * line or a single ` * ` body line. To keep a value's line breaks, use `commentLines`
+ * (one escaped, prefixed line per input line) or `docComment` (a whole `/** … *\/`).
+ */
+export function commentText(value) {
+    return String(value).replace(LINE_BREAK, ' ').replaceAll('*/', '* /');
+}
+/**
+ * `value` split on its line terminators, each line escaped by `commentText` and
+ * given `prefix` (`'// '`, `' * '`), trailing whitespace trimmed so a blank line is
+ * a bare `//` or ` *`. The lines are joined with `\n` by the caller, so a value's
+ * paragraph breaks survive and none of them can end the comment.
+ */
+export function commentLines(value, prefix = '') {
+    return String(value).split(LINE_BREAK).map((line) => `${prefix}${commentText(line)}`.trimEnd());
+}
+/**
+ * A JSDoc comment holding `value`, at `indent`. A one-line value keeps the
+ * one-line form, `/** value *\/`, so its bytes do not change; a multi-line value
+ * gets an open block with one ` * ` line per input line.
+ */
+export function docComment(value, indent = '') {
+    const body = commentLines(value);
+    if (body.length === 1)
+        return [`${indent}/** ${commentText(value)} */`];
+    return [`${indent}/**`, ...body.map((line) => `${indent} * ${line}`.trimEnd()), `${indent} */`];
+}

package/dist/core/connector-checks.d.ts

@@ -113,6 +113,21 @@ export interface ConnectorCheckOpts {
     resolutions?: LookupResolutions;
     /** Whether a connector step's schema is materialized locally. */
     schemaReadiness?: (connector: string, action: string, version?: string, object?: string) => SchemaReadiness | undefined;
+    /**
+     * Why `compile` could not resolve this operation at all (`library.resolve`
+     * throws), or `undefined` when it resolves. Checked before
+     * {@link ConnectorCheckOpts.connectorInputs}, which answers `undefined` for an
+     * unresolvable operation and so cannot tell "not in the library" from "no facts".
+     */
+    connectorResolveError?: (spec: {
+        key: string;
+        action: string;
+        version?: string;
+        object?: string;
+    }) => {
+        code: string;
+        message: string;
+    } | undefined;
     /** What `compile` would refuse these inputs with, or `undefined` when it would accept them. */
     connectorInputs?: (spec: {
         key: string;
@@ -157,9 +172,10 @@ export declare function checkConnectorLookups(where: string, spec: ConnectorSpec
  */
 export declare function checkConnectorSchema(where: string, spec: ConnectorSpec, opts: ConnectorCheckOpts, dialect: ExprDialect, report: ReportConnector): void;
 /**
- * The field contract and the binding names `compile` enforces, reported here first.
+ * The operation, its field contract and the binding names `compile` enforces,
+ * reported here first.
  *
- * Both rules run only with the facts in hand (a library for the fields, a
+ * Each rule runs only with the facts in hand (a library for the operation and its fields, a
  * bindings.json for the names); without them `check` stays a pure function of the
  * built model and says nothing, as before.
  */

package/dist/core/connector-checks.js

@@ -321,18 +321,28 @@ export function checkConnectorSchema(where, spec, opts, dialect, report) {
     }
 }
 /**
- * The field contract and the binding names `compile` enforces, reported here first.
+ * The operation, its field contract and the binding names `compile` enforces,
+ * reported here first.
  *
- * Both rules run only with the facts in hand (a library for the fields, a
+ * Each rule runs only with the facts in hand (a library for the operation and its fields, a
  * bindings.json for the names); without them `check` stays a pure function of the
  * built model and says nothing, as before.
  */
 export function checkConnectorContract(where, spec, opts, report, 
 /** The activity's own id, for {@link connectionConnectorConflicts}; omit to record nothing. */
 id) {
-    const inputErr = opts.connectorInputs?.({ key: spec.key, action: spec.action, version: spec.version, object: spec.object }, spec.inputs ?? {});
-    if (inputErr) {
-        report({ level: 'error', code: 'CONNECTOR_INPUT', message: `${where}: ${inputErr}` });
+    const target = { key: spec.key, action: spec.action, version: spec.version, object: spec.object };
+    // The operation itself first: an operation compile cannot resolve has no field
+    // contract to check, and `connectorInputs` answers "unknown" for it.
+    const unresolved = opts.connectorResolveError?.(target);
+    if (unresolved) {
+        report({ level: 'error', code: unresolved.code, message: `${where}: ${unresolved.message}` });
+    }
+    else {
+        const inputErr = opts.connectorInputs?.(target, spec.inputs ?? {});
+        if (inputErr) {
+            report({ level: 'error', code: 'CONNECTOR_INPUT', message: `${where}: ${inputErr}` });
+        }
     }
     checkBindingLabels(where, spec, opts, (code, message) => report({ level: 'error', code, message }), { key: spec.key, action: spec.action }, id === undefined ? undefined : { id, connector: spec.key });
 }

package/dist/core/contribution-bindings.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The `bindings[]` entries a contribution-lowered node needs and did not supply
+ * (flow-builder-sdk#942).
+ *
+ * A definition's `model.context` names its resource through `<bindings.NAME>`
+ * placeholders, and declares each NAME in `model.bindings.values`. The typed
+ * emitters (rpa, api-workflow, queue, ixp, connector) close those names by hand.
+ * A `rawNode` or a hand-written `FlowAction` returns a definition and inputs, and
+ * usually no `bindings` — so before this, nothing closed them, and compile failed
+ * at `BINDING_PLACEHOLDER_UNRESOLVED` while `check` passed.
+ *
+ * For instance, the manifest `registry get --local` returns for a sibling Flow:
+ *
+ * ```json
+ * "model": { "bindings": { "resource": "process", "resourceSubType": "Flow", "resourceKey": "k1",
+ *   "values": [{ "name": "name", "default": "Notifier" }, { "name": "folderPath", "default": "" }] },
+ *   "context": [{ "name": "name", "value": "<bindings.name>" }, { "name": "folderPath", "value": "<bindings.folderPath>" }] }
+ * ```
+ *
+ * needs two `process` entries keyed `k1`: `name` = "Notifier" and `folderPath` = "".
+ * {@link planContributionBindings} reads exactly those facts off the definition.
+ *
+ * `connection` resources are out of scope: a connector definition's entries are
+ * keyed by the tenant connection id, which the definition does not carry. A raw
+ * connector node is refused for that reason (`connector-raw-node.ts`).
+ *
+ * Pure: `serialize` lowers with it, and `check` runs it dry so the two agree.
+ */
+/** One `bindings[]` entry, as the flow file carries it. */
+export interface PlannedBinding {
+    name: string;
+    type: string;
+    resource: string;
+    resourceKey: string;
+    default?: string;
+    propertyAttribute: string;
+    resourceSubType?: string;
+}
+/** What one definition needs: the entries to build, and the names it cannot close. */
+export interface ContributionBindingPlan {
+    /** The resource kind (`model.bindings.resource`), when it is one this plan closes. */
+    resource?: string;
+    /** The resource key every entry carries (`model.bindings.resourceKey`). */
+    resourceKey?: string;
+    /** One entry per referenced name the contribution did not supply. */
+    entries: PlannedBinding[];
+    /** One sentence per referenced name that cannot be closed, and why. Empty when every name closes. */
+    problems: string[];
+}
+/** The `<bindings.NAME>` names a definition's `model.context` references, in order, once each. */
+export declare function referencedBindingNames(model: any): string[];
+/**
+ * Plan the entries a contribution-lowered node needs: for each `<bindings.NAME>`
+ * its definition's `model.context` references and `supplied` does not cover, one
+ * entry built from the definition — `resource`, `resourceKey`, `resourceSubType`
+ * from `model.bindings`, and `name`, `default`, `propertyAttribute` from the
+ * matching `model.bindings.values` row.
+ *
+ * A supplied entry covers a name when it has the same `resource` and `name`: the
+ * contributor's own bindings win, as they always did.
+ *
+ * A name is a problem (not an entry) when the definition declares no
+ * `values` row for it, or carries no `resourceKey` — a per-tenant template such
+ * as the bundled `core.action.queue.create` (`resourceKey: ""`), which only a
+ * typed factory can fill.
+ *
+ * @param def - The resolved definition.
+ * @param supplied - The bindings the contribution returned.
+ */
+export declare function planContributionBindings(def: any, supplied?: readonly {
+    resource?: string;
+    name?: string;
+}[]): ContributionBindingPlan;

package/dist/core/contribution-bindings.js

@@ -0,0 +1,105 @@
+/**
+ * The `bindings[]` entries a contribution-lowered node needs and did not supply
+ * (flow-builder-sdk#942).
+ *
+ * A definition's `model.context` names its resource through `<bindings.NAME>`
+ * placeholders, and declares each NAME in `model.bindings.values`. The typed
+ * emitters (rpa, api-workflow, queue, ixp, connector) close those names by hand.
+ * A `rawNode` or a hand-written `FlowAction` returns a definition and inputs, and
+ * usually no `bindings` — so before this, nothing closed them, and compile failed
+ * at `BINDING_PLACEHOLDER_UNRESOLVED` while `check` passed.
+ *
+ * For instance, the manifest `registry get --local` returns for a sibling Flow:
+ *
+ * ```json
+ * "model": { "bindings": { "resource": "process", "resourceSubType": "Flow", "resourceKey": "k1",
+ *   "values": [{ "name": "name", "default": "Notifier" }, { "name": "folderPath", "default": "" }] },
+ *   "context": [{ "name": "name", "value": "<bindings.name>" }, { "name": "folderPath", "value": "<bindings.folderPath>" }] }
+ * ```
+ *
+ * needs two `process` entries keyed `k1`: `name` = "Notifier" and `folderPath` = "".
+ * {@link planContributionBindings} reads exactly those facts off the definition.
+ *
+ * `connection` resources are out of scope: a connector definition's entries are
+ * keyed by the tenant connection id, which the definition does not carry. A raw
+ * connector node is refused for that reason (`connector-raw-node.ts`).
+ *
+ * Pure: `serialize` lowers with it, and `check` runs it dry so the two agree.
+ */
+/** The `<bindings.NAME>` names a definition's `model.context` references, in order, once each. */
+export function referencedBindingNames(model) {
+    const names = [];
+    for (const row of Array.isArray(model?.context) ? model.context : []) {
+        const name = typeof row?.value === 'string' ? /^<bindings\.(.+)>$/.exec(row.value)?.[1] : undefined;
+        if (name !== undefined && !names.includes(name))
+            names.push(name);
+    }
+    return names;
+}
+/**
+ * Plan the entries a contribution-lowered node needs: for each `<bindings.NAME>`
+ * its definition's `model.context` references and `supplied` does not cover, one
+ * entry built from the definition — `resource`, `resourceKey`, `resourceSubType`
+ * from `model.bindings`, and `name`, `default`, `propertyAttribute` from the
+ * matching `model.bindings.values` row.
+ *
+ * A supplied entry covers a name when it has the same `resource` and `name`: the
+ * contributor's own bindings win, as they always did.
+ *
+ * A name is a problem (not an entry) when the definition declares no
+ * `values` row for it, or carries no `resourceKey` — a per-tenant template such
+ * as the bundled `core.action.queue.create` (`resourceKey: ""`), which only a
+ * typed factory can fill.
+ *
+ * @param def - The resolved definition.
+ * @param supplied - The bindings the contribution returned.
+ */
+export function planContributionBindings(def, supplied = []) {
+    const model = def?.model;
+    const names = referencedBindingNames(model);
+    const resource = model?.bindings?.resource;
+    // Connection (or undeclared) resources are keyed by a tenant connection id the
+    // definition does not carry; the connector paths own them.
+    if (names.length === 0 || typeof resource !== 'string' || !resource || resource === 'connection') {
+        return { entries: [], problems: [] };
+    }
+    const open = names.filter((n) => !supplied.some((b) => b?.resource === resource && b?.name === n));
+    if (open.length === 0)
+        return { resource, entries: [], problems: [] };
+    const label = `${def?.nodeType}@${def?.version}`;
+    const resourceKey = model.bindings.resourceKey;
+    if (typeof resourceKey !== 'string' || !resourceKey) {
+        return {
+            resource,
+            entries: [],
+            problems: open.map((n) => `${label} references "<bindings.${n}>", and its model.bindings carries no resourceKey, so no `
+                + `"${resource}" binding can be built for it. This definition is a per-tenant template, not a resolved `
+                + `manifest: use the typed factory for the family, or the manifest \`uip maestro flow registry get `
+                + `${def?.nodeType}\` returns for a real resource, or return the bindings from contribute().`),
+        };
+    }
+    const values = Array.isArray(model.bindings.values) ? model.bindings.values : [];
+    const subType = model.bindings.resourceSubType;
+    const entries = [];
+    const problems = [];
+    for (const n of open) {
+        const row = values.find((r) => r?.name === n);
+        if (!row) {
+            problems.push(`${label} references "<bindings.${n}>", but its model.bindings.values declares no "${n}" row, so `
+                + `there is no default to bind it to. Pass the manifest exactly as \`uip maestro flow registry get\` `
+                + `returns it, or return the "${n}" binding from contribute().`);
+            continue;
+        }
+        entries.push({
+            name: n,
+            type: typeof row.type === 'string' && row.type ? row.type : 'string',
+            resource,
+            resourceKey,
+            ...(typeof row.default === 'string' ? { default: row.default } : {}),
+            propertyAttribute: typeof row.propertyAttribute === 'string' && row.propertyAttribute
+                ? row.propertyAttribute : n,
+            ...(typeof subType === 'string' && subType ? { resourceSubType: subType } : {}),
+        });
+    }
+    return { resource, resourceKey, entries, problems };
+}

package/dist/core/error-port.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Does a node definition have an `error` port? One answer for `check` and
+ * `serialize` (flow-builder-sdk#943).
+ *
+ * The product's rule, read from @uipath/flow-core and @uipath/flow-tool:
+ *
+ *  - the manifest client injects an `error` source handle into every served
+ *    definition with `supportsErrorHandling: true` that does not declare one
+ *    (`withErrorHandles` / `nodeSupportsErrorHandling`);
+ *  - `uip maestro flow validate` does the same when it checks edge handles
+ *    (`validateEdgeHandlesAgainstCurrentManifests`: `supportsErrorHandling ===
+ *    true` adds `error` to the node's source handles).
+ *
+ * So the flag alone grants the port. For instance, the manifest
+ * `registry get --local` returns for a sibling Flow or RPA project
+ * (`buildNodeManifest`) has `supportsErrorHandling: true` and only `input` +
+ * `output` handles, and an `error` edge from it is valid. A definition that
+ * declares an `error` source handle without the flag counts too.
+ */
+export declare function definitionHasErrorPort(def: any): boolean;
+/**
+ * The ONERROR_NO_ERROR_PORT sentence for a definition-backed node, naming its
+ * node type. Shared with serialize, which throws it for the same node.
+ */
+export declare function errorPortRefusal(stepName: string, def: any): string;

package/dist/core/error-port.js

@@ -0,0 +1,36 @@
+/**
+ * Does a node definition have an `error` port? One answer for `check` and
+ * `serialize` (flow-builder-sdk#943).
+ *
+ * The product's rule, read from @uipath/flow-core and @uipath/flow-tool:
+ *
+ *  - the manifest client injects an `error` source handle into every served
+ *    definition with `supportsErrorHandling: true` that does not declare one
+ *    (`withErrorHandles` / `nodeSupportsErrorHandling`);
+ *  - `uip maestro flow validate` does the same when it checks edge handles
+ *    (`validateEdgeHandlesAgainstCurrentManifests`: `supportsErrorHandling ===
+ *    true` adds `error` to the node's source handles).
+ *
+ * So the flag alone grants the port. For instance, the manifest
+ * `registry get --local` returns for a sibling Flow or RPA project
+ * (`buildNodeManifest`) has `supportsErrorHandling: true` and only `input` +
+ * `output` handles, and an `error` edge from it is valid. A definition that
+ * declares an `error` source handle without the flag counts too.
+ */
+export function definitionHasErrorPort(def) {
+    if (def?.supportsErrorHandling === true)
+        return true;
+    const groups = Array.isArray(def?.handleConfiguration) ? def.handleConfiguration : [];
+    return groups.some((g) => (Array.isArray(g?.handles) ? g.handles : [])
+        .some((h) => h?.id === 'error' && h?.type === 'source'));
+}
+/**
+ * The ONERROR_NO_ERROR_PORT sentence for a definition-backed node, naming its
+ * node type. Shared with serialize, which throws it for the same node.
+ */
+export function errorPortRefusal(stepName, def) {
+    return `Step "${stepName}" is a ${def?.nodeType}@${def?.version} node, and its definition has no error port: `
+        + `it does not set supportsErrorHandling: true and declares no "error" source handle, so the edge would leave a `
+        + `handle the node does not have. Handle the failure downstream instead, or pass the definition exactly as `
+        + `\`uip maestro flow registry get\` returns it.`;
+}

package/dist/core/expr-check.js

@@ -29,7 +29,7 @@
  * and gets back diagnostics with no location. The caller stamps the location
  * (which node / task / field) it came from.
  */
-import * as ts from 'typescript';
+import { typescript } from './typescript-module.js';
 /**
  * A JSONPath wildcard/filter step — the spelling that reaches for JavaScript and
  * misses. Used only to add a suggestion; the parse decides.
@@ -47,15 +47,18 @@ const JSONPATH_WILDCARD = /\[\s*(?:\*|\?|'[^']*'|"[^"]*")\s*\]|\.\.[A-Za-z_$]/;
  * `ts.createSourceFile` is a parse, not an evaluation — nothing in `expr` runs.
  * TypeScript is already a runtime dependency of this package (see
  * `core/script-return.ts`, which infers a script's return type the same way), so
- * this adds no dependency.
+ * this adds no dependency. It is loaded on the first check, not at import
+ * (`core/typescript-module.ts`).
  */
 function syntaxError(expr) {
+    const ts = typescript();
     const problems = parseExpression(expr).problems;
     if (problems.length === 0)
         return undefined;
     return ts.flattenDiagnosticMessageText(problems[0].messageText, ' ');
 }
 function parseExpression(expr) {
+    const ts = typescript();
     const source = ts.createSourceFile('expression.ts', `(${expr}\n)`, ts.ScriptTarget.ES2020, 
     /* setParentNodes */ false);
     // `parseDiagnostics` is where the scanner records syntax problems. It is not on
@@ -77,6 +80,7 @@ function retype(expr, escapes, keepCooked) {
 }
 /** The value a leaf denotes — a name, or a literal's value (a regular expression's is its source). */
 function leafValue(node) {
+    const ts = typescript();
     if (ts.isIdentifier(node) || ts.isPrivateIdentifier(node))
         return node.text;
     // NumericLiteral … TemplateTail: every literal and template piece carries `.text`.
@@ -86,6 +90,7 @@ function leafValue(node) {
     return undefined;
 }
 function children(node) {
+    const ts = typescript();
     const out = [];
     ts.forEachChild(node, (c) => { out.push(c); });
     return out;

package/dist/core/expr.d.ts

@@ -145,8 +145,8 @@ export declare function ran(step: string): Expr;
  * The first five are what every error-capable node's definition declares
  * (`outputDefinition.error.schema`, `required`, `additionalProperties: false`).
  * `response` and `element` are NOT declared and are present at run time anyway —
- * measured on every family probed (2026-09-10), `element` carrying the id of the
- * step that failed. They are typed here because a field that exists should be
+ * measured on every family probed (2026-09-10), `element` carrying the label of
+ * the step that failed. They are typed here because a field that exists should be
  * readable; the declared five stay first because those are the contract.
  */
 export type ErrorEnvelopeField = 'code' | 'message' | 'detail' | 'category' | 'status' | 'response' | 'element';
@@ -166,15 +166,21 @@ export type ErrorEnvelopeField = 'code' | 'message' | 'detail' | 'category' | 's
  * | `category` | string | `'User'` |
  * | `status` | number | `404` |
  * | `response` | unknown | undeclared; `null` in every probe |
- * | `element` | string | undeclared; the id of the step that failed |
+ * | `element` | string | undeclared; the failing step's label |
  *
  * The last two resolve at run time — measured, a container handler reading
- * `element` came back with the failing body step's id — but they are absent from
- * the declared schema, so `uip maestro flow validate` reports
+ * `element` came back with the failing body step's label — but they are absent
+ * from the declared schema, so `uip maestro flow validate` reports
  * `EXPRESSION_DIAGNOSTIC: Property 'element' does not exist on type
  * '<Step>_Error'` for them. Valid, and noisy: prefer the declared five unless you
  * specifically need one of these.
  *
+ * **`element` is the step's canvas label (`display.label`), not its node id.** The
+ * label defaults to the step name, so it matches the name (not always the node
+ * id) only while no `label` is set: `.step('failA', …, { label: 'Fail A' })`
+ * failing gives `element: 'Fail A'`. Route on `code` / `message`, never on
+ * `element`.
+ *
  * **Which VARIABLE holds it is per node family, and this helper owns that.**
  * Measured on the product (2026-09-10), one debug run per family:
  *

package/dist/core/expr.js

@@ -179,15 +179,21 @@ export function ran(step) {
  * | `category` | string | `'User'` |
  * | `status` | number | `404` |
  * | `response` | unknown | undeclared; `null` in every probe |
- * | `element` | string | undeclared; the id of the step that failed |
+ * | `element` | string | undeclared; the failing step's label |
  *
  * The last two resolve at run time — measured, a container handler reading
- * `element` came back with the failing body step's id — but they are absent from
- * the declared schema, so `uip maestro flow validate` reports
+ * `element` came back with the failing body step's label — but they are absent
+ * from the declared schema, so `uip maestro flow validate` reports
  * `EXPRESSION_DIAGNOSTIC: Property 'element' does not exist on type
  * '<Step>_Error'` for them. Valid, and noisy: prefer the declared five unless you
  * specifically need one of these.
  *
+ * **`element` is the step's canvas label (`display.label`), not its node id.** The
+ * label defaults to the step name, so it matches the name (not always the node
+ * id) only while no `label` is set: `.step('failA', …, { label: 'Fail A' })`
+ * failing gives `element: 'Fail A'`. Route on `code` / `message`, never on
+ * `element`.
+ *
  * **Which VARIABLE holds it is per node family, and this helper owns that.**
  * Measured on the product (2026-09-10), one debug run per family:
  *

package/dist/core/json-file.d.ts

@@ -0,0 +1 @@
+export declare function writeJsonFile(path: string, value: unknown): void;

package/dist/core/json-file.js

@@ -0,0 +1,12 @@
+/**
+ * Write `value` as an emitted JSON artifact: 2-space indent and a trailing newline.
+ *
+ * Every emitted `.flow`, caseplan, entry-points, bindings_v2 and library file is
+ * byte-locked, and twelve call sites each spelled this out by hand; a copy that dropped
+ * the `'\n'` would break byte-lock on that one artifact only. FB007 holds pretty-printed
+ * JSON writes to this function. Creating the parent directory stays the caller's job.
+ */
+import { writeFileSync } from 'node:fs';
+export function writeJsonFile(path, value) {
+    writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
+}

package/dist/core/library.d.ts

@@ -218,6 +218,25 @@ export interface LibraryOpts {
      */
     overlayDir?: string;
 }
+/** Why {@link Library.resolve} refused a connector action. */
+export type ConnectorResolveCode = 
+/** The library carries no such operation (or no such connector, or not at that version). */
+'CONNECTOR_NOT_IN_LIBRARY'
+/** A GENERIC operation (one entry per object) named without an `object`. */
+ | 'CONNECTOR_OBJECT_REQUIRED'
+/** An `object` on a single, non-generic operation. */
+ | 'CONNECTOR_OBJECT_NOT_GENERIC';
+/**
+ * The refusal {@link Library.resolve} throws, with a `code` for each reason.
+ *
+ * Typed so a caller can tell a refusal from a bug without matching on message
+ * text: `check` reports it under this code with this message, and a compile
+ * that throws it carries the same code into its `--json` diagnostics (#948).
+ */
+export declare class ConnectorResolveError extends Error {
+    readonly code: ConnectorResolveCode;
+    constructor(code: ConnectorResolveCode, message: string);
+}
 export declare class Library {
     private layers;
     /** The LIST-ENVELOPE LEDGER, overlay first so a prepared entry can add a row. */