@uipath/maestro-builder-sdk 6.11.2 → 6.11.4

package/README.md

@@ -115,7 +115,7 @@ network calls. That is what `prepare` is for: it is the one verb that does talk
 to the tenant. Run what `check` named, both fields at once:
 
 ```bash
-npx flow-sdk registry pull    # once per machine: the connector library
+uip maestro registry pull     # once per machine: the connector library
 
 npx flow-sdk registry prepare uipath-salesforce-slack --action send-message-to-user \
   --resolve channel:profile.email=ada@example.com \
@@ -289,7 +289,7 @@ Keeping the names symbolic is what lets one flow move between connections: the
 code says `slack`, and only `bindings.json` knows which Slack.
 
 Discover ops and input shapes from the connector library that
-`npx flow-sdk registry pull` downloads and caches. A field the library does not
+`uip maestro registry pull` downloads and caches. A field the library does not
 carry is connection-specific — that is the `prepare` case from the quick start.
 
 The package also exposes the low-level materializer used by the UiPath CLI to
@@ -302,7 +302,7 @@ flow-registry-materialize \
   --connectors ./connectors
 ```
 
-Most callers want `npx flow-sdk registry pull`, which downloads the published
+Most callers want `uip maestro registry pull`, which downloads the published
 archive, verifies its checksum and then runs this transform. The low-level
 command is for SDK development, build pipelines, and troubleshooting: it only
 transforms local files that are already on disk.
@@ -322,7 +322,7 @@ The step-by-step authoring guides — `SKILL.md` for Flow, `SKILL-case.md`,
 UiPath authoring skills catalog rather than here, so a coding agent and a human
 read the same copy. The worked examples named by those guides travel with them.
 
-The connector library is not bundled: `npx flow-sdk registry pull` downloads it
+The connector library is not bundled: `uip maestro registry pull` downloads it
 and caches it per machine. The package does carry the curated overlay that pull
 applies on top — corrections and the definitions the raw registry dump omits.
 

package/dist/check.js

@@ -11,8 +11,9 @@ import { isLookupToken, resolvedValue, unresolvedLookupMessage, } from './core/l
 import { EVENT_FILTER_OPERATORS, readEventFilter, eventFilterProblem } from './event-filters.js';
 import { extractRefs } from './core/expr-check.js';
 import { bindingSelfNameMessage, bindingUndeclaredMessage, undeclaredBinding } from './core/binding-messages.js';
+import { isAnswerField } from './core/hitl-answers.js';
 import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome } from './core/hitl-routing.js';
-import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
+import { childStepLists, declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
 import { prepareCommand, resolveFlagArg } from './core/cli-spelling.js';
@@ -1141,7 +1142,8 @@ function checkFlow(built, ancestors, opts = {}) {
                     code: 'MOCK_HAS_NO_OUTPUT',
                     message: `Placeholder "${name}" publishes nothing, but "$vars.${name}${field ? '.' + field : ''}" reads it in "${step}". `
                         + 'A mock() is a marker for a node that does not exist yet — its output is null at run time, always. '
-                        + 'Replace it with the real step before reading it.',
+                        + 'Keep the placeholder while the real node does not exist, and have the reader use a value you supply instead (a flow input, as example/ClaimScaffold.flow.ts does). '
+                        + 'Replace the placeholder only with the real node, once `registry search` finds it; a script returning fixed values is not the real node.',
                     step,
                 });
                 continue;
@@ -1644,20 +1646,7 @@ function checkLoopListEnvelope(loop, connectors, opts, diags) {
 }
 /** True if any step on THIS flow's own tree is a `.return()`. */
 function hasReturn(steps) {
-    for (const s of steps) {
-        if (s.kind === 'return')
-            return true;
-        if (s.kind === 'branch' && (hasReturn(s.then) || hasReturn(s.otherwise)))
-            return true;
-        if (s.kind === 'switch'
-            && (s.cases.some((c) => hasReturn(c.body)) || hasReturn(s.default ?? [])))
-            return true;
-        if (s.kind === 'parallel' && s.arms.some(hasReturn))
-            return true;
-        if ((s.kind === 'loop' || s.kind === 'doWhile') && hasReturn(s.body))
-            return true;
-    }
-    return false;
+    return steps.some((s) => s.kind === 'return' || childStepLists(s).some(hasReturn));
 }
 /**
  * Closest of `candidates` to `name`: same word ignoring case, one contained in
@@ -4777,9 +4766,9 @@ function checkHitl(step, inputs, diags) {
                 + `gets a text box and the value comes back as a string. Valid: `
                 + `${FORM_FIELD_TYPES.join(', ')}.`, nearest !== undefined ? `type: '${nearest}'` : `type: 'text'`);
         }
+        if (isAnswerField(f))
+            answers++; // an `output`, or an `inOut` whose reviewed value comes back
         if (f?.direction === 'input' || f?.direction === 'inOut') {
-            if (f.direction === 'inOut')
-                answers++; // the reviewed value comes back
             const value = f.value;
             if (value === undefined || value === null) {
                 at('HITL_FIELD_NO_VALUE', `Human task "${step}" shows the form field "${id}" to the reviewer but gives it no value, `
@@ -4800,10 +4789,7 @@ function checkHitl(step, inputs, diags) {
                     + `Compute it in a script step first and point the field at that step's output.`, `value: out('<scriptStep>')`);
             }
         }
-        else if (f?.direction === 'output') {
-            answers++;
-        }
-        else {
+        else if (f?.direction !== 'output') {
             at('HITL_FIELD_DIRECTION', `Human task "${step}" gives the form field "${id}" the direction `
                 + `${JSON.stringify(f?.direction)}. A field is shown to the `
                 + `reviewer ('input'), filled in by them ('output'), or pre-filled and editable ('inOut'); `
@@ -4926,7 +4912,7 @@ function checkHitlRead(name, field, rest, form, step, diags) {
     if (answer === 'Action')
         return; // which outcome was pressed.
     const answers = (form?.fields ?? [])
-        .filter((f) => f?.direction === 'output' && typeof f?.id === 'string')
+        .filter((f) => isAnswerField(f) && typeof f?.id === 'string')
         .map((f) => f.id);
     if (answers.includes(answer))
         return;
@@ -4938,7 +4924,7 @@ function checkHitlRead(name, field, rest, form, step, diags) {
         level: 'error',
         code: 'HITL_READ_UNKNOWN_FIELD',
         message: `Human task "${name}" has no answer "${answer}" (read as "$vars.${name}.output.${answer}" in `
-            + `"${step}"). Its result carries only the fields the reviewer FILLS IN`
+            + `"${step}"). Its result carries only the fields the reviewer FILLS IN or EDITS`
             + `${answers.length > 0 ? ` (${answers.join(', ')})` : ' (it declares none)'} plus "Action". `
             + (shown.includes(answer)
                 ? `"${answer}" is a field the reviewer only reads, so it is not part of the answer — read the `

package/dist/core/hitl-answers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which form fields of a human task come back in its answer object — the one
+ * rule `serialize` (the emitted `outputs.output.properties`) and `check` (the
+ * answer count and every `out('<task>', '<field>')` read) all use, so they
+ * cannot drift. They did drift (UV-16855): `serialize` emitted `inOut` fields
+ * as answers and `check` counted them as answers, but the read check listed
+ * `output` fields only, so the documented read of an editable field —
+ * `out('review', 'comment')` for `{ id: 'comment', direction: 'inOut', … }` —
+ * failed `check` and blocked `compile`.
+ *
+ * - `output` — the reviewer fills it in; the value comes back.
+ * - `inOut` — pre-filled and editable; the (possibly changed) value comes back.
+ * - `input` — shown only; NOT an answer. Read the value bound to it instead.
+ */
+export type AnswerDirection = 'output' | 'inOut';
+/** True when the field's value comes back in the task's answer object. */
+export declare function isAnswerField(field: {
+    direction?: unknown;
+} | null | undefined): boolean;

package/dist/core/hitl-answers.js

@@ -0,0 +1,4 @@
+/** True when the field's value comes back in the task's answer object. */
+export function isAnswerField(field) {
+    return field?.direction === 'output' || field?.direction === 'inOut';
+}

package/dist/core/step-ports.d.ts

@@ -42,4 +42,16 @@ export declare function hasExits(r: DeclaredExit[] | NoExits): r is DeclaredExit
  * `.parallel` join waiting: a terminate ends the run, join included.
  */
 export declare function stopsAtEnd(steps: readonly Step[]): boolean;
+/**
+ * The step lists nested DIRECTLY inside `step` — the bodies a walk over this
+ * flow's own tree must descend into. Exhaustive over `Step['kind']`, so a new
+ * container kind fails to compile here instead of being silently skipped by
+ * every walker. That is how `check`'s return scan came to miss `.stepSwitch`
+ * arms and `.stepToList` / `.onError` bodies, and warned NO_RETURN on flows
+ * whose every path ends in `.return()` (UV-16855).
+ *
+ * A subflow's child flow is deliberately NOT a child here: it is another
+ * flow's tree, and its returns say nothing about whether THIS flow ends.
+ */
+export declare function childStepLists(step: Step): readonly Step[][];
 export {};

package/dist/core/step-ports.js

@@ -107,3 +107,40 @@ export function stopsAtEnd(steps) {
         || (st.kind === 'switch' && st.default !== undefined && has(st.default, kinds)));
     return has(steps, new Set(['return'])) && !has(steps, new Set(['terminate', 'break']));
 }
+/**
+ * The step lists nested DIRECTLY inside `step` — the bodies a walk over this
+ * flow's own tree must descend into. Exhaustive over `Step['kind']`, so a new
+ * container kind fails to compile here instead of being silently skipped by
+ * every walker. That is how `check`'s return scan came to miss `.stepSwitch`
+ * arms and `.stepToList` / `.onError` bodies, and warned NO_RETURN on flows
+ * whose every path ends in `.return()` (UV-16855).
+ *
+ * A subflow's child flow is deliberately NOT a child here: it is another
+ * flow's tree, and its returns say nothing about whether THIS flow ends.
+ */
+export function childStepLists(step) {
+    switch (step.kind) {
+        case 'branch':
+            return [step.then, step.otherwise];
+        case 'switch':
+            return [...step.cases.map((c) => c.body), ...(step.default ? [step.default] : [])];
+        case 'stepSwitch':
+            return step.cases.map((c) => c.body);
+        case 'loop':
+        case 'doWhile':
+        case 'stepToList':
+            return [step.body];
+        case 'parallel':
+            return step.arms;
+        case 'action':
+        case 'break':
+        case 'terminate':
+        case 'stepToRef':
+        case 'return':
+            return [];
+        default: {
+            const unhandled = step;
+            throw new Error(`childStepLists: unhandled step kind ${JSON.stringify(unhandled.kind)}`);
+        }
+    }
+}

package/dist/registry/cache.d.ts

@@ -21,6 +21,15 @@
 export declare const LIBRARY_JSON_DIR = "library-json";
 export declare const LIBRARY_MARKDOWN_DIR = "library-md";
 export declare const CURRENT_LINK = "current";
+/**
+ * The command a message tells a person or agent to run when the cache is
+ * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
+ * pull` runs this package's pull and fills the same cache, and it is the one
+ * command the authoring skill teaches. Each message used to spell the command
+ * out by hand, so they kept naming the SDK's own entry point after the skill
+ * moved to `uip`. Name it here once.
+ */
+export declare const PULL_COMMAND = "uip maestro registry pull";
 /**
  * Root of the library cache. `UIP_FLOW_SDK_LIBRARY_CACHE` overrides it.
  *

package/dist/registry/cache.js

@@ -24,6 +24,15 @@ import { join } from "node:path";
 export const LIBRARY_JSON_DIR = "library-json";
 export const LIBRARY_MARKDOWN_DIR = "library-md";
 export const CURRENT_LINK = "current";
+/**
+ * The command a message tells a person or agent to run when the cache is
+ * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
+ * pull` runs this package's pull and fills the same cache, and it is the one
+ * command the authoring skill teaches. Each message used to spell the command
+ * out by hand, so they kept naming the SDK's own entry point after the skill
+ * moved to `uip`. Name it here once.
+ */
+export const PULL_COMMAND = "uip maestro registry pull";
 /**
  * Root of the library cache. `UIP_FLOW_SDK_LIBRARY_CACHE` overrides it.
  *

package/dist/registry/path-cli.js

@@ -1,6 +1,6 @@
 import { reportResult } from '../cli-result.js';
 import { join } from "node:path";
-import { CURRENT_LINK, currentEntrySha, libraryCacheRoot, resolveCachedLibrary, resolveCachedMarkdown, } from "./cache.js";
+import { CURRENT_LINK, PULL_COMMAND, currentEntrySha, libraryCacheRoot, resolveCachedLibrary, resolveCachedMarkdown, } from "./cache.js";
 /**
  * Say where the connector library is.
  *
@@ -34,7 +34,7 @@ export async function run(argv) {
     const single = (field, value) => {
         reportResult({ [field]: value ?? null });
         if (!value) {
-            console.error("No connector library in the cache yet. Run `flow-sdk registry pull`.");
+            console.error(`No connector library in the cache yet. Run \`${PULL_COMMAND}\`.`);
             return 1;
         }
         console.log(value);

package/dist/registry/search-cli.js

@@ -1,6 +1,6 @@
 import { reportResult } from '../cli-result.js';
 import { readFile, stat } from "node:fs/promises";
-import { resolveLibraryDir } from "./cache.js";
+import { PULL_COMMAND, resolveLibraryDir } from "./cache.js";
 import { dirname, join } from "node:path";
 export const DEFAULT_SEARCH_LIMIT = 20;
 const USAGE = "Usage: flow-sdk registry search [query] [--library <dir>] [--library-md <dir>] [--connector <key>] [--limit <n>]";
@@ -52,7 +52,7 @@ export async function searchRegistryOperations(options) {
         content = await readFile(indexPath, "utf-8");
     }
     catch {
-        throw new Error(`Could not read ${indexPath}. Run \`flow-sdk registry pull\`, or point` +
+        throw new Error(`Could not read ${indexPath}. Run \`${PULL_COMMAND}\`, or point` +
             " --library at an extracted connector library.");
     }
     let parsed;
@@ -120,6 +120,10 @@ export async function run(argv) {
     // verbs defaulted it was the inconsistency an author hit first.
     const libraryPath = resolveLibraryDir(value(argv, "--library"));
     if (!libraryPath) {
+        // Say why. A bare usage line here read as "no match" to an agent deciding
+        // between a connector and http(): it took the failed search for a miss.
+        console.error(`No connector library is cached. Run \`${PULL_COMMAND}\`, or pass` +
+            " --library <dir>.");
         console.error(USAGE);
         return 2;
     }

package/dist/serialize.js

@@ -14,6 +14,7 @@ import { Expr, toExpr, SCHEDULE_PRESETS, DELAY_PRESETS, parseIxpProjectType, fla
 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 { isAnswerField } from './core/hitl-answers.js';
 import { BindingRefusal, GUID_RE, bindingSelfNameMessage, bindingUndeclaredMessage, undeclaredBinding } 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';
@@ -2800,7 +2801,7 @@ function hitlInputs(inputs, nodeId, flowId, label, rename) {
     const properties = {};
     for (const f of inputs?.fields ?? []) {
         // inOut fields land in the answers too — their reviewed value flows back.
-        if (f.direction !== 'output' && f.direction !== 'inOut')
+        if (!isAnswerField(f))
             continue;
         properties[f.id] = { ...FORM_FIELD_JSON_TYPE[f.type] };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.11.2",
+  "version": "6.11.4",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "0e144a44d84cd717eaec74c8c43fe864026e7339"
+  "gitref": "8c18e5efb6f8dd4b2599f9591cabdff42feaf275"
 }