@uipath/maestro-builder-sdk 6.8.5 → 6.9.0

package/dist/registry/uip/envelope.d.ts

@@ -1,12 +1,4 @@
-/**
- * Reading what `uip … --output json` prints.
- *
- * The CLI is chatty: an update banner, a tool-version warning and a
- * `ManifestClient` diagnostic can precede the JSON document, and the document
- * itself is a `{ Result, Data, Message, … }` envelope whose key casing has
- * varied between tools. Three Python callers each had their own loop for
- * finding the document; this is the one loop, and the one accessor.
- */
+import type { UipResult } from "./client.js";
 /** The shape every `uip` JSON response shares, read case-insensitively. */
 export interface UipEnvelope {
     Result?: unknown;
@@ -35,3 +27,46 @@ export declare function isSuccess(envelope: UipEnvelope | undefined): boolean;
 export declare function dataItems(envelope: UipEnvelope | undefined): unknown[];
 /** The last `limit` characters of a stream, for a message. */
 export declare function tail(text: string, limit?: number): string;
+/**
+ * Why a `uip` call failed, as text a message can quote after a colon. Never empty.
+ *
+ * `uip … --output json` prints its FAILURE envelope on stdout, not stderr:
+ * `OutputFormatter.error` hands it to `logOutput`, which writes through
+ * `sink.writeOut` (uipath-cli `packages/common/src/formatter.ts:1657-1688` and
+ * `:654-675`). For example, `registry get` of a node the catalog does not serve
+ * exits 1 with this on stdout:
+ *
+ * ```json
+ * { "Result": "Failure", "Message": "Node not found",
+ *   "Instructions": "No node found with node type: uipath.connector.trigger.…" }
+ * ```
+ *
+ * and, on stderr, nothing, or a `[ManifestClient] fetchDynamicNodes ok: …`
+ * diagnostic, or a self-update banner. Callers that quoted stderr printed
+ * `registry get failed for <nodeType>: ` with nothing after the colon (2026-09-23
+ * eval, `skill-flow-datafabric-trigger-lifecycle`, v2 command 33).
+ *
+ * So the envelope is read first. The order is:
+ *
+ *  1. a call the client refused (`OfflineUipClient`): no process ran, and its
+ *     stderr already says so (`offline: refused to run …`), so that text is kept;
+ *  2. a call killed by its timeout: `timed out`, whatever partial output it left;
+ *  3. a non-Success envelope on stdout (found past any banner, keys read
+ *     case-insensitively): `<Message>: <Instructions>`, or whichever is present;
+ *  4. the end of stderr, then the end of stdout;
+ *  5. `no output`.
+ */
+export declare function failureReason(result: UipResult): string;
+/**
+ * True when a failed `registry get` answered the CLI's own "not in the catalog"
+ * envelope, `Message: "Node not found"` (uipath-cli
+ * `packages/maestro-sdk/src/registry/command.ts:595-600`).
+ *
+ * Only that answer says the node is ABSENT. Every other failure — `Error
+ * retrieving node` (`command.ts:586-591`, which carries the thrown error in
+ * `Instructions`), a refusal, a timeout, output that is not JSON — says the
+ * lookup did not work, which is a different fact with a different remedy. The
+ * `Message` is the discriminator because the envelope's `ErrorCode` is the
+ * generic `unknown_error` for both (`formatter.ts:1490-1502`).
+ */
+export declare function isNodeNotFound(result: UipResult): boolean;

package/dist/registry/uip/envelope.js

@@ -6,7 +6,12 @@
  * itself is a `{ Result, Data, Message, … }` envelope whose key casing has
  * varied between tools. Three Python callers each had their own loop for
  * finding the document; this is the one loop, and the one accessor.
+ *
+ * It is also the one place that decides why a call FAILED ({@link failureReason}).
+ * Callers outside `registry/uip/` do not read a result's stderr themselves;
+ * `tests/uip-stderr-gate.test.ts` holds them to that.
  */
+import { pyStrip } from "../compat/pystr.js";
 /**
  * The first JSON document in `text`, or `undefined`.
  *
@@ -82,3 +87,78 @@ export function dataItems(envelope) {
 export function tail(text, limit = 300) {
     return text.length <= limit ? text : text.slice(text.length - limit);
 }
+/** A non-empty trimmed string, or `undefined`. */
+function said(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const text = pyStrip(value);
+    return text === "" ? undefined : text;
+}
+/**
+ * Why a `uip` call failed, as text a message can quote after a colon. Never empty.
+ *
+ * `uip … --output json` prints its FAILURE envelope on stdout, not stderr:
+ * `OutputFormatter.error` hands it to `logOutput`, which writes through
+ * `sink.writeOut` (uipath-cli `packages/common/src/formatter.ts:1657-1688` and
+ * `:654-675`). For example, `registry get` of a node the catalog does not serve
+ * exits 1 with this on stdout:
+ *
+ * ```json
+ * { "Result": "Failure", "Message": "Node not found",
+ *   "Instructions": "No node found with node type: uipath.connector.trigger.…" }
+ * ```
+ *
+ * and, on stderr, nothing, or a `[ManifestClient] fetchDynamicNodes ok: …`
+ * diagnostic, or a self-update banner. Callers that quoted stderr printed
+ * `registry get failed for <nodeType>: ` with nothing after the colon (2026-09-23
+ * eval, `skill-flow-datafabric-trigger-lifecycle`, v2 command 33).
+ *
+ * So the envelope is read first. The order is:
+ *
+ *  1. a call the client refused (`OfflineUipClient`): no process ran, and its
+ *     stderr already says so (`offline: refused to run …`), so that text is kept;
+ *  2. a call killed by its timeout: `timed out`, whatever partial output it left;
+ *  3. a non-Success envelope on stdout (found past any banner, keys read
+ *     case-insensitively): `<Message>: <Instructions>`, or whichever is present;
+ *  4. the end of stderr, then the end of stdout;
+ *  5. `no output`.
+ */
+export function failureReason(result) {
+    if (result.refused === true)
+        return said(result.stderr) ?? "not run (offline client refused the call)";
+    if (result.timedOut === true)
+        return "timed out (the call was killed before it answered)";
+    const envelope = parseEnvelope(result.stdout);
+    if (envelope !== undefined && !isSuccess(envelope)) {
+        const parts = [said(getCI(envelope, "Message")), said(getCI(envelope, "Instructions"))].filter((part) => part !== undefined);
+        if (parts.length > 0)
+            return parts.join(": ");
+    }
+    const stderr = said(result.stderr);
+    if (stderr !== undefined)
+        return tail(stderr);
+    const stdout = said(result.stdout);
+    if (stdout !== undefined)
+        return tail(stdout);
+    return "no output";
+}
+/**
+ * True when a failed `registry get` answered the CLI's own "not in the catalog"
+ * envelope, `Message: "Node not found"` (uipath-cli
+ * `packages/maestro-sdk/src/registry/command.ts:595-600`).
+ *
+ * Only that answer says the node is ABSENT. Every other failure — `Error
+ * retrieving node` (`command.ts:586-591`, which carries the thrown error in
+ * `Instructions`), a refusal, a timeout, output that is not JSON — says the
+ * lookup did not work, which is a different fact with a different remedy. The
+ * `Message` is the discriminator because the envelope's `ErrorCode` is the
+ * generic `unknown_error` for both (`formatter.ts:1490-1502`).
+ */
+export function isNodeNotFound(result) {
+    if (result.code === 0 || result.refused === true || result.timedOut === true)
+        return false;
+    const envelope = parseEnvelope(result.stdout);
+    if (envelope === undefined || isSuccess(envelope))
+        return false;
+    return said(getCI(envelope, "Message"))?.toLowerCase() === "node not found";
+}

package/dist/serialize.js

@@ -13,6 +13,7 @@ import { dirname, join } from 'node:path';
 import { Expr, toExpr, SCHEDULE_PRESETS, DELAY_PRESETS, parseIxpProjectType, flatNameOf, flatNameSegmentsOf } from './flow-sdk.js';
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
+import { dataFabricUnknownInputs } from './core/typed-raw-node.js';
 import { bindingSelfNameMessage } from './core/binding-messages.js';
 import { OUTCOME_HANDLE_NODE_TYPES, assertHitlExitInvariant, hitlExitModel, hitlExitViolation, outcomeSlug } from './core/hitl-routing.js';
 import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
@@ -3928,7 +3929,14 @@ export function serialize(built, opts = {}) {
             display: { label, ...(def?.display?.icon ? { icon: def.display.icon } : {}) },
         };
         col++;
-        if (def?.model)
+        // A Data Fabric node gets no node-level `model`, whichever path emits it
+        // (the typed verbs, or a rawNode through emitContribution). Studio Web
+        // never writes one (flow-core node.ts: "`node.model` is never written";
+        // canvas `nodeToInstance` omits it), and export seeds it from the
+        // definition (services bpmn-to-xml.ts), so a copy here can only go stale.
+        // `outputs` stay: the canvas persists them (`source: '=response'`), and
+        // `variables.nodes[]` is derived from them.
+        if (def?.model && !type.startsWith('core.datafabric.'))
             node.model = subNodeId(clone(def.model), id);
         if (def?.outputDefinition)
             node.outputs = subNodeId(clone(def.outputDefinition), id);
@@ -4170,6 +4178,12 @@ export function serialize(built, opts = {}) {
         const connectorRefusal = connectorRawNodeRefusal(def.nodeType);
         if (connectorRefusal)
             throw new Error(`${where}: ${connectorRefusal}`);
+        // A Data Fabric key the product never reads (`_sortOptions`) is refused for
+        // every contribution, whichever class or SDK copy made it: `validate`
+        // cannot see it, and the node would ignore it at run time.
+        const unknownInput = dataFabricUnknownInputs(def.nodeType, def.version, contribution.inputs);
+        if (unknownInput?.severity === 'error')
+            throw new Error(`${where}: ${unknownInput.message}`);
         const id = stepUid(scope, stepName);
         const node = makeNode(def.nodeType, id, stepName, { parentId, def, requestedVersion });
         node.inputs = renderDeep(contribution.inputs ?? {}, scope.rename);
@@ -4382,7 +4396,7 @@ export function serialize(built, opts = {}) {
                 ...(s.guardrails === undefined ? {} : { guardrails: s.guardrails }),
                 // The two DESCRIPTOR ARRAYS. `agentInputVariables` entries carry the
                 // binding expression; `agentOutputVariables` entries are name + type only,
-                // and a runner coerces the model's completion to exactly these keys.
+                // and the runtime's structured final call fills exactly these keys.
                 //
                 // `id` is the FLAT NAME, not the author's — the platform re-derives this
                 // array from the node's prompts and keeps a pre-existing entry only when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.8.5",
+  "version": "6.9.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "07d7820cfddf1603444213859a340b4e9dbe643e"
+  "gitref": "b7baf691c4126ec18eb3388d0d0a70b09301f24d"
 }