@uipath/maestro-builder-sdk 6.19.0 → 6.20.1

package/dist/core/context-index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A context-grounding index's node type, both ways.
+ *
+ * The platform names an index's resource node
+ * `uipath.agent.resource.context.index.<slug>.<uuid>`: the slug is derived from
+ * the index's display name, and the uuid is the index's id. Serialize builds the
+ * type from an author's `{ name, id }`; decompile reads `{ slug, id }` back out
+ * of a file's type. Keeping both directions here is what keeps them inverses.
+ */
+/** The type prefix every context-index resource node shares. */
+export declare const CONTEXT_INDEX_TYPE_PREFIX = "uipath.agent.resource.context.index.";
+/**
+ * The slug for an index name: lower-cased, with every run of non-alphanumerics
+ * collapsed to a single `-`. Measured against the platform's own type for
+ * "Billing Dispute SOP Index" → `billing-dispute-sop-index`, and pinned by a
+ * test, because a derived identifier that disagrees with the registry's is a
+ * node type the tenant has never heard of. A slug never contains a `.`.
+ */
+export declare function contextIndexSlug(name: string): string;
+/** The node type for an index: `…context.index.<slug>.<uuid>`. */
+export declare function contextIndexType(spec: {
+    name: string;
+    id: string;
+}): string;
+/**
+ * The `{ slug, id }` a context-index node type carries, or `undefined` when the
+ * type is not one. The id is everything after the LAST `.`, because a slug has
+ * no dot in it. Either part can be `''` (the SDK once wrote `…<slug>.` for an
+ * index with no id).
+ */
+export declare function parseContextIndexType(type: string): {
+    slug: string;
+    id: string;
+} | undefined;

package/dist/core/context-index.js

@@ -0,0 +1,38 @@
+/**
+ * A context-grounding index's node type, both ways.
+ *
+ * The platform names an index's resource node
+ * `uipath.agent.resource.context.index.<slug>.<uuid>`: the slug is derived from
+ * the index's display name, and the uuid is the index's id. Serialize builds the
+ * type from an author's `{ name, id }`; decompile reads `{ slug, id }` back out
+ * of a file's type. Keeping both directions here is what keeps them inverses.
+ */
+/** The type prefix every context-index resource node shares. */
+export const CONTEXT_INDEX_TYPE_PREFIX = 'uipath.agent.resource.context.index.';
+/**
+ * The slug for an index name: lower-cased, with every run of non-alphanumerics
+ * collapsed to a single `-`. Measured against the platform's own type for
+ * "Billing Dispute SOP Index" → `billing-dispute-sop-index`, and pinned by a
+ * test, because a derived identifier that disagrees with the registry's is a
+ * node type the tenant has never heard of. A slug never contains a `.`.
+ */
+export function contextIndexSlug(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/** The node type for an index: `…context.index.<slug>.<uuid>`. */
+export function contextIndexType(spec) {
+    return `${CONTEXT_INDEX_TYPE_PREFIX}${contextIndexSlug(spec.name)}.${spec.id}`;
+}
+/**
+ * The `{ slug, id }` a context-index node type carries, or `undefined` when the
+ * type is not one. The id is everything after the LAST `.`, because a slug has
+ * no dot in it. Either part can be `''` (the SDK once wrote `…<slug>.` for an
+ * index with no id).
+ */
+export function parseContextIndexType(type) {
+    if (!type.startsWith(CONTEXT_INDEX_TYPE_PREFIX))
+        return undefined;
+    const tail = type.slice(CONTEXT_INDEX_TYPE_PREFIX.length);
+    const dot = tail.lastIndexOf('.');
+    return dot < 0 ? { slug: tail, id: '' } : { slug: tail.slice(0, dot), id: tail.slice(dot + 1) };
+}

package/dist/core/definitionless-node-types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Node types that never have a `definitions[]` row.
+ *
+ * A `.flow` file pairs every node's `(type, typeVersion)` with a definition —
+ * except these. The platform special-cases them ahead of definition resolution:
+ * a sticky note has no manifest, `flow validate` skips it, BPMN conversion skips
+ * it, and an edge that touches one is dropped. So "this node pins a pair no
+ * definition covers" is a real defect for every other type and the normal state
+ * for these.
+ */
+/** The wire type of a canvas sticky note. */
+export declare const STICKY_NOTE_TYPE = "stickyNote";
+/** The `typeVersion` Studio Web stamps on a sticky note. The type has no manifest to take it from. */
+export declare const STICKY_NOTE_TYPE_VERSION = "1.0.0";
+/** Node types that carry no definition by design. */
+export declare const DEFINITIONLESS_NODE_TYPES: ReadonlySet<string>;

package/dist/core/definitionless-node-types.js

@@ -0,0 +1,16 @@
+/**
+ * Node types that never have a `definitions[]` row.
+ *
+ * A `.flow` file pairs every node's `(type, typeVersion)` with a definition —
+ * except these. The platform special-cases them ahead of definition resolution:
+ * a sticky note has no manifest, `flow validate` skips it, BPMN conversion skips
+ * it, and an edge that touches one is dropped. So "this node pins a pair no
+ * definition covers" is a real defect for every other type and the normal state
+ * for these.
+ */
+/** The wire type of a canvas sticky note. */
+export const STICKY_NOTE_TYPE = 'stickyNote';
+/** The `typeVersion` Studio Web stamps on a sticky note. The type has no manifest to take it from. */
+export const STICKY_NOTE_TYPE_VERSION = '1.0.0';
+/** Node types that carry no definition by design. */
+export const DEFINITIONLESS_NODE_TYPES = new Set([STICKY_NOTE_TYPE]);

package/dist/core/form-field-type.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The product's spellings of the form-field types the SDK models.
+ *
+ * A quick form's field `type` is read by the product through
+ * `@uipath/hitl-schema-types` `normalizeFieldType`. Its canonical stored values
+ * are `string`, `number`, `boolean`, `datetime`, … and it accepts aliases for
+ * each: `text` is an alias of `string`, `date-time` of `datetime`, and .NET
+ * names such as `System.String` resolve too. The designer saves the canonical
+ * value, so a canvas-built form says `"string"`; the SDK (like flow-v1's
+ * serializer and `uip maestro flow hitl add`) writes `text`.
+ *
+ * So `"string"` and `"text"` are the same field on the wire. This table maps
+ * each product spelling of the four types {@link FormFieldType} models to the
+ * SDK's spelling, so decompile hands the author source `check` accepts.
+ * A type the SDK does not model (`integer`, `date`,
+ * `file`, …) has no entry: it stays as written, and `check` reports it.
+ *
+ * Mirrors `resolveFieldType` in `@uipath/hitl-schema-types` 1.1.6, restricted
+ * to the groups that resolve to `string`, `number`, `boolean` and `datetime`
+ * (minus `singleSelect` / `enum` / `union` / …, which resolve to `string` but
+ * are not a plain text box).
+ */
+import type { FormFieldType } from './actions.js';
+/**
+ * The SDK's spelling of a wire form-field type, or `undefined` when the SDK
+ * does not model that type.
+ *
+ * @example
+ * sdkFormFieldType('string')   // 'text'
+ * sdkFormFieldType('datetime') // 'date-time'
+ * sdkFormFieldType('integer')  // undefined
+ */
+export declare function sdkFormFieldType(wire: unknown): FormFieldType | undefined;

package/dist/core/form-field-type.js

@@ -0,0 +1,30 @@
+const PRODUCT_SPELLINGS = {
+    text: 'text',
+    string: 'text',
+    String: 'text',
+    'System.String': 'text',
+    'System.Char': 'text',
+    Char: 'text',
+    number: 'number',
+    Number: 'number',
+    boolean: 'boolean',
+    Boolean: 'boolean',
+    'System.Boolean': 'boolean',
+    'date-time': 'date-time',
+    datetime: 'date-time',
+    dateTime: 'date-time',
+    DateTime: 'date-time',
+    'System.DateTime': 'date-time',
+};
+/**
+ * The SDK's spelling of a wire form-field type, or `undefined` when the SDK
+ * does not model that type.
+ *
+ * @example
+ * sdkFormFieldType('string')   // 'text'
+ * sdkFormFieldType('datetime') // 'date-time'
+ * sdkFormFieldType('integer')  // undefined
+ */
+export function sdkFormFieldType(wire) {
+    return typeof wire === 'string' && Object.hasOwn(PRODUCT_SPELLINGS, wire) ? PRODUCT_SPELLINGS[wire] : undefined;
+}

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

@@ -79,6 +79,14 @@ import type { HitlInputs } from './actions.js';
  * nothing else recognises.
  */
 export declare function outcomeSlug(name: unknown, index: number): string;
+/**
+ * The id an outcome is emitted with: the author's `id` when the object form
+ * carries one (a decompiled flow keeps the canvas's ids, for example
+ * `outcome-1778015958049`), else {@link outcomeSlug} of its name. Every reader
+ * of outcome ids goes through this, so the `outcome-<id>` port an edge leaves
+ * from and the id `schema.outcomes[]` declares cannot disagree (#1130).
+ */
+export declare function outcomeIdOf(outcome: unknown, index: number): string;
 /** One outcome's exit. */
 export interface HitlOutcomeExit {
     /** The outcome NAME — what `.stepSwitch` arms and `out('<step>', 'Action')` compare against. */

package/dist/core/hitl-routing.js

@@ -14,6 +14,22 @@ export function outcomeSlug(name, index) {
         .replace(/^-+|-+$/g, '');
     return slug || `outcome-${index + 1}`;
 }
+/**
+ * The id an outcome is emitted with: the author's `id` when the object form
+ * carries one (a decompiled flow keeps the canvas's ids, for example
+ * `outcome-1778015958049`), else {@link outcomeSlug} of its name. Every reader
+ * of outcome ids goes through this, so the `outcome-<id>` port an edge leaves
+ * from and the id `schema.outcomes[]` declares cannot disagree (#1130).
+ */
+export function outcomeIdOf(outcome, index) {
+    if (outcome !== null && typeof outcome === 'object') {
+        const { id, name } = outcome;
+        if (typeof id === 'string' && id !== '')
+            return id;
+        return outcomeSlug(name, index);
+    }
+    return outcomeSlug(outcome, index);
+}
 /**
  * The two human-task node types whose exits the product derives from
  * `inputs.schema.outcomes`. Keyed on TYPE, never on whether `schema.outcomes` is
@@ -33,7 +49,7 @@ export function hitlExitModel(inputs, pinnedVersion) {
         const name = typeof o === 'string' ? o : o?.name;
         return {
             value: String(name ?? ''),
-            port: `outcome-${outcomeSlug(name, i)}`,
+            port: `outcome-${outcomeIdOf(o, i)}`,
             endsProcess: typeof o !== 'string' && o?.action === 'End',
         };
     });

package/dist/core/process-resource-sort-order.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The palette `sortOrder` of a process-resource node (an RPA workflow, API
+ * workflow, function, agent, or agentic process, published or in-solution),
+ * derived the way the platform derives it.
+ *
+ * flow-core's `buildNodeManifest` (`@uipath/flow-core/manifest`) does not keep a
+ * per-family number. It writes `categorySortOrders[baseCategory] +
+ * DYNAMIC_NODE_SORT_OFFSET`, where `baseCategory` is the resource type's category
+ * (`agent`, `flow`, …) before any `published` / `in-solution` listing suffix. So
+ * this module keeps the same two inputs and the same sum, not five literals.
+ *
+ * The base values are flow-core 0.115.4's `baseCategorySortOrders` for these
+ * categories (read 2026-10-08). They match what the platform writes today:
+ * `registry get` on alpha/codereval returns agent 510, flow 600, agentic-process
+ * 610, case-management 620, rpa-workflow 630, api-workflow 640, function 650, and
+ * 54 of 54 v1 in-solution agent `.flow` files (09-01 to 10-08) carry 510.
+ *
+ * flow-core renumbered these once already (agent was 5, api-workflow 10,
+ * rpa-workflow 30). `tests/process-resource-sort-order.test.ts` compares this
+ * table with a local flow-core when one is present, so the next renumber shows
+ * up as a red test rather than as a silent diff.
+ */
+export declare const PROCESS_RESOURCE_CATEGORY_SORT_ORDERS: {
+    readonly agent: 10;
+    readonly flow: 100;
+    readonly 'agentic-process': 110;
+    readonly 'case-management': 120;
+    readonly 'rpa-workflow': 130;
+    readonly 'api-workflow': 140;
+    readonly function: 150;
+};
+/** flow-core's `DYNAMIC_NODE_SORT_OFFSET`: every tenant-built node sorts after every static one. */
+export declare const DYNAMIC_NODE_SORT_OFFSET = 500;
+/** A process-resource node category, e.g. `'agent'` or `'rpa-workflow'`. */
+export type ProcessResourceCategory = keyof typeof PROCESS_RESOURCE_CATEGORY_SORT_ORDERS;
+/**
+ * The `sortOrder` the platform writes for a process-resource node of this
+ * category. For instance `resourceNodeSortOrder('agent')` is 510.
+ */
+export declare function resourceNodeSortOrder(category: ProcessResourceCategory): number;

package/dist/core/process-resource-sort-order.js

@@ -0,0 +1,44 @@
+import { ownEntry } from './own-entry.js';
+/**
+ * The palette `sortOrder` of a process-resource node (an RPA workflow, API
+ * workflow, function, agent, or agentic process, published or in-solution),
+ * derived the way the platform derives it.
+ *
+ * flow-core's `buildNodeManifest` (`@uipath/flow-core/manifest`) does not keep a
+ * per-family number. It writes `categorySortOrders[baseCategory] +
+ * DYNAMIC_NODE_SORT_OFFSET`, where `baseCategory` is the resource type's category
+ * (`agent`, `flow`, …) before any `published` / `in-solution` listing suffix. So
+ * this module keeps the same two inputs and the same sum, not five literals.
+ *
+ * The base values are flow-core 0.115.4's `baseCategorySortOrders` for these
+ * categories (read 2026-10-08). They match what the platform writes today:
+ * `registry get` on alpha/codereval returns agent 510, flow 600, agentic-process
+ * 610, case-management 620, rpa-workflow 630, api-workflow 640, function 650, and
+ * 54 of 54 v1 in-solution agent `.flow` files (09-01 to 10-08) carry 510.
+ *
+ * flow-core renumbered these once already (agent was 5, api-workflow 10,
+ * rpa-workflow 30). `tests/process-resource-sort-order.test.ts` compares this
+ * table with a local flow-core when one is present, so the next renumber shows
+ * up as a red test rather than as a silent diff.
+ */
+export const PROCESS_RESOURCE_CATEGORY_SORT_ORDERS = {
+    agent: 10,
+    flow: 100,
+    'agentic-process': 110,
+    'case-management': 120,
+    'rpa-workflow': 130,
+    'api-workflow': 140,
+    function: 150,
+};
+/** flow-core's `DYNAMIC_NODE_SORT_OFFSET`: every tenant-built node sorts after every static one. */
+export const DYNAMIC_NODE_SORT_OFFSET = 500;
+/**
+ * The `sortOrder` the platform writes for a process-resource node of this
+ * category. For instance `resourceNodeSortOrder('agent')` is 510.
+ */
+export function resourceNodeSortOrder(category) {
+    const base = ownEntry(PROCESS_RESOURCE_CATEGORY_SORT_ORDERS, category);
+    if (base === undefined)
+        throw new Error(`no sortOrder for process-resource category '${category}'`);
+    return base + DYNAMIC_NODE_SORT_OFFSET;
+}

package/dist/core/wire-expr.d.ts

@@ -0,0 +1,27 @@
+/**
+ * core/wire-expr — reading an expression back out of the wire format.
+ *
+ * Shared by decompile and by every node family's deserializer, so the set of
+ * accepted spellings lives in one place.
+ */
+/**
+ * The JS body of a value in an EXPRESSION SLOT: a field that always holds an
+ * expression and never literal text (a branch condition, a loop collection, an
+ * agent input binding, an app input binding, a field binding).
+ *
+ * The wire format has more than one spelling for one expression there, and this
+ * is the one place that knows them all:
+ *
+ *  - `=js:<body>` -- what SDK compile writes.
+ *  - `=<body>` (bare `=`) -- what the product writes for bindings: the CLI's
+ *    agent-input encoder emits `=$vars.<node>.output.<field>` (uipath-cli
+ *    `agent-input-encoding-utils.ts`), and `=$metadata.<key>` the same way.
+ *  - `=vars.<path>` / `=metadata.<path>` -- the PATH form flow-v1 writes for app
+ *    and field bindings. It names the same variable the SDK spells `$vars.<path>`.
+ *  - no prefix -- the slot stores a bare JS body (decision/switch conditions).
+ *
+ * A VALUE slot (an ordinary node input) is different: there only `=js:` marks an
+ * expression and any other string is literal text, as the product reads it
+ * (flow-schema `coerceToExpressionValue`). Do not use this for one.
+ */
+export declare function wireExprBody(raw: string): string;

package/dist/core/wire-expr.js

@@ -0,0 +1,34 @@
+/**
+ * core/wire-expr — reading an expression back out of the wire format.
+ *
+ * Shared by decompile and by every node family's deserializer, so the set of
+ * accepted spellings lives in one place.
+ */
+/**
+ * The JS body of a value in an EXPRESSION SLOT: a field that always holds an
+ * expression and never literal text (a branch condition, a loop collection, an
+ * agent input binding, an app input binding, a field binding).
+ *
+ * The wire format has more than one spelling for one expression there, and this
+ * is the one place that knows them all:
+ *
+ *  - `=js:<body>` -- what SDK compile writes.
+ *  - `=<body>` (bare `=`) -- what the product writes for bindings: the CLI's
+ *    agent-input encoder emits `=$vars.<node>.output.<field>` (uipath-cli
+ *    `agent-input-encoding-utils.ts`), and `=$metadata.<key>` the same way.
+ *  - `=vars.<path>` / `=metadata.<path>` -- the PATH form flow-v1 writes for app
+ *    and field bindings. It names the same variable the SDK spells `$vars.<path>`.
+ *  - no prefix -- the slot stores a bare JS body (decision/switch conditions).
+ *
+ * A VALUE slot (an ordinary node input) is different: there only `=js:` marks an
+ * expression and any other string is literal text, as the product reads it
+ * (flow-schema `coerceToExpressionValue`). Do not use this for one.
+ */
+export function wireExprBody(raw) {
+    if (raw.startsWith('=js:'))
+        return raw.slice(4);
+    if (!raw.startsWith('='))
+        return raw;
+    const body = raw.slice(1);
+    return /^(?:vars|metadata)(?:\.[A-Za-z_$][\w$]*|\[\d+\])*$/.test(body.trim()) ? `$${body.trim()}` : body;
+}

package/dist/decompile-cli.js

@@ -129,7 +129,17 @@ if (!existsSync(BASELINE)) {
   // ask for confirmation before the write. Left as a no-op for now.
   // ---------------------------------------------------------------------------
 
-  const args = [ORIGINAL, EDITED, '-o', MERGED];
+  // \`merge <edited> --original <original>\` is the grammar; the positional
+  // \`merge <original> <edited>\` pair is deprecated. A \`uip\` from before
+  // UiPath/cli#4526 knows only the pair, so ask its \`merge --help\` first.
+  // Key on the door, not the file name: on Windows \`uip\` resolves to node.exe
+  // or a full uip.exe path.
+  const mergeHelp = frontDoor.via === 'uip'
+    ? spawnSync(frontDoor.file, [...frontDoor.prefix, 'merge', '--help'], { encoding: 'utf8' })
+    : undefined;
+  const namedOriginal = mergeHelp === undefined
+    || \`\${mergeHelp.stdout ?? ''}\${mergeHelp.stderr ?? ''}\`.includes('--original');
+  const args = namedOriginal ? [EDITED, '--original', ORIGINAL, '-o', MERGED] : [ORIGINAL, EDITED, '-o', MERGED];
   if (existsSync(BASELINE)) args.push('--baseline', BASELINE);
   run('merge', args);
   console.log('\\n>>> Wrote ' + ${JSON.stringify(base + '.merged.flow')});

package/dist/decompile.d.ts

@@ -128,9 +128,11 @@ export interface DecompileOptions {
     /**
      * Receives each non-fatal finding about the file, one message per finding:
      * a node no trigger reaches (the builder cannot express a detached node, so
-     * the source omits it — strict mode throws instead), and a core
-     * `(type, typeVersion)` pair this SDK does not bundle (the source keeps it;
-     * `compile` will refuse it). The CLI prints these on stderr.
+     * the source omits it — strict mode throws instead), and a
+     * `(type, typeVersion)` pair this SDK cannot resolve for a type it ships at
+     * other versions (the source omits that `{ version }`, so the node compiles at
+     * the SDK's default; `merge` with a baseline keeps the untouched original
+     * node at its version — strict mode throws instead). The CLI prints these on stderr.
      */
     warn?: (message: string) => void;
     /**
@@ -142,6 +144,9 @@ export interface DecompileOptions {
      * (`{{input.start__output__notes}}`), so the recovered source declares its
      * inputs under those names — the same flow, not the same spelling. Without a
      * reader, a shell agent decompiles with empty prompts and a warning.
+     * A context index placed by the canvas or the CLI keeps its real name and
+     * folder only in `<agent source>/resources/<inputs.source>/resource.json`,
+     * which is read the same way.
      */
     readSidecar?: (relativePath: string) => string | undefined;
 }