@uipath/maestro-builder-sdk 6.53.2 → 6.54.1

package/dist/case/case-sdk.d.ts

@@ -595,9 +595,16 @@ export interface TaskInputBinding {
 export interface TaskOutputBinding {
     /** The case-variable name the field feeds (read downstream as `=vars.<var>`). */
     var: string;
-    /** The source field expression, e.g. `=response` or `=Error.Message`. */
+    /** The source field expression, e.g. `=response` or `=Error.Message`. For a `custom` output, the value assigned instead. */
     source: string;
     type: TypeDesc;
+    /**
+     * A custom assignment output, written `custom: true` with no `id`, the way
+     * Studio Web saves one: when the task completes, `var` is set to `source` (a
+     * literal, `=vars.<name>`, or a `=js:` expression), not to a field of the
+     * task's result. Set by `.outputs({ <var>: { assign } })`.
+     */
+    custom?: boolean;
 }
 export interface BuiltTask {
     /** Task key + display name (also the handle used by `selected-tasks-completed`). */
@@ -1131,12 +1138,38 @@ declare class TaskBuilder {
      * task's own (bare) output, with no root entry — until a second task writes
      * the same variable, which makes both reassignments.
      *
-     * @param shape - Case-variable names to the result field they take, or `{ source, type }`.
+     * Pass `{ assign, type }` for a **custom** output: the SDD's `x = expr` row.
+     * When the task completes, the case variable is set to `assign` — a literal,
+     * `=vars.<name>`, or a `=js:` expression — instead of a result field. It is
+     * written as Studio Web saves one: `custom: true`, `elementId: 'root'`, no
+     * `id`. The SDD notation `=metadata.<field>` reads nothing outside `=js:`, so it
+     * is written as `=js:metadata.<field>`. An SDD literal copied with its quotes
+     * (`{ assign: '"literal-assigned"' }`) loses them, as `sdd convert` reads it.
+     * A custom output sees only the outputs listed before it on the same task:
+     * outputs are evaluated in order, so it cannot read its own variable or a
+     * later output's (`check` reports `OUTPUT_SELF_REFERENCE` /
+     * `OUTPUT_FORWARD_READ`).
+     *
+     * @example
+     * **Extract a result field and assign two custom outputs**
+     * ```ts
+     * casePlan('echo').stage('Echo', (s) => s.task('Echo', (t) =>
+     *   t.apiWorkflow('Echo', { folder: 'Shared' }).outputs({
+     *     renamedResult: '=APIOutput1',
+     *     literalResult: { assign: 'literal-assigned' },
+     *     resultCopy: { assign: "=js:vars.renamedResult + '-copy'" },
+     *   })))
+     * ```
+     *
+     * @param shape - Case-variable names to the result field they take, `{ source, type }`, or a custom `{ assign, type }`.
      * @returns This builder, so calls chain.
      */
     outputs(shape: Record<string, string | {
         source: string;
         type?: TypeDesc;
+    } | {
+        assign: string;
+        type?: TypeDesc;
     }>): this;
     /**
      * Add a task-entry condition. Pass a nested array for the complete OR-of-AND grid.

package/dist/case/case-sdk.js

@@ -489,15 +489,48 @@ class TaskBuilder {
      * task's own (bare) output, with no root entry — until a second task writes
      * the same variable, which makes both reassignments.
      *
-     * @param shape - Case-variable names to the result field they take, or `{ source, type }`.
+     * Pass `{ assign, type }` for a **custom** output: the SDD's `x = expr` row.
+     * When the task completes, the case variable is set to `assign` — a literal,
+     * `=vars.<name>`, or a `=js:` expression — instead of a result field. It is
+     * written as Studio Web saves one: `custom: true`, `elementId: 'root'`, no
+     * `id`. The SDD notation `=metadata.<field>` reads nothing outside `=js:`, so it
+     * is written as `=js:metadata.<field>`. An SDD literal copied with its quotes
+     * (`{ assign: '"literal-assigned"' }`) loses them, as `sdd convert` reads it.
+     * A custom output sees only the outputs listed before it on the same task:
+     * outputs are evaluated in order, so it cannot read its own variable or a
+     * later output's (`check` reports `OUTPUT_SELF_REFERENCE` /
+     * `OUTPUT_FORWARD_READ`).
+     *
+     * @example
+     * **Extract a result field and assign two custom outputs**
+     * ```ts
+     * casePlan('echo').stage('Echo', (s) => s.task('Echo', (t) =>
+     *   t.apiWorkflow('Echo', { folder: 'Shared' }).outputs({
+     *     renamedResult: '=APIOutput1',
+     *     literalResult: { assign: 'literal-assigned' },
+     *     resultCopy: { assign: "=js:vars.renamedResult + '-copy'" },
+     *   })))
+     * ```
+     *
+     * @param shape - Case-variable names to the result field they take, `{ source, type }`, or a custom `{ assign, type }`.
      * @returns This builder, so calls chain.
      */
     outputs(shape) {
         this._outputs ??= [];
         for (const [name, v] of Object.entries(shape)) {
-            const source = typeof v === 'string' ? v : v.source;
-            const type = (typeof v === 'string' ? 'string' : (v.type ?? 'string'));
-            this._outputs.push({ var: name, source, type });
+            if (typeof v === 'string') {
+                this._outputs.push({ var: name, source: v, type: 'string' });
+                continue;
+            }
+            const type = (v.type ?? 'string');
+            if ('assign' in v) {
+                if ('source' in v)
+                    throw new Error(`task "${this._name}": output "${name}" sets both source and assign — use source to extract a result field, assign for a custom output.`);
+                this._outputs.push({ var: name, source: customOutputValue(v.assign), type, custom: true });
+            }
+            else {
+                this._outputs.push({ var: name, source: v.source, type });
+            }
         }
         return this;
     }
@@ -543,6 +576,41 @@ class TaskBuilder {
         };
     }
 }
+/**
+ * A custom output's value as the runtime reads it. `=metadata.<field>` (the SDD
+ * notation) has no bare path prefix, so it resolves to nothing; only inside
+ * `=js:` is `metadata` in scope. The same narrow rewrite as `uip maestro case
+ * sdd convert` (`canonicalExpression`).
+ */
+function customOutputValue(value) {
+    const unquoted = unquoteLiteral(value);
+    return unquoted.startsWith('=metadata.') ? `=js:${unquoted.slice(1)}` : unquoted;
+}
+/**
+ * An SDD cell's quoted literal without its quotes, as the CLI's `sdd convert`
+ * reads it (`unquoteLiteral` in `packages/case-tool/src/services/sdd-convert/io.ts`):
+ * `"literal-assigned"` → `literal-assigned`, with escaped quotes unescaped.
+ * A value not wholly wrapped in one pair of `"…"` or `'…'` (an unescaped quote
+ * inside, or an expression like `'a' + 'b'`) is returned unchanged.
+ */
+function unquoteLiteral(cell) {
+    const text = cell.trim();
+    const quote = text[0];
+    if (quote !== '"' && quote !== "'")
+        return cell;
+    if (text.length < 2 || text[text.length - 1] !== quote)
+        return cell;
+    const inner = text.slice(1, -1);
+    for (let at = 0; at < inner.length; at += 1) {
+        if (inner[at] === '\\') {
+            at += 1;
+            continue;
+        }
+        if (inner[at] === quote)
+            return cell;
+    }
+    return inner.replaceAll(`\\${quote}`, quote);
+}
 class StageBuilder {
     _label;
     _exception;

package/dist/case/check.js

@@ -539,6 +539,32 @@ function checkStage(stage, diags, refStage, refPlacement, bindings) {
             if (isResourceLabelRefusal(resolved))
                 diags.push({ level: 'error', code: resolved.code, message: resolved.message, where: t.name });
         }
+        // A custom row (`{ assign }`) is evaluated in array order, after the rows
+        // before it on the same task: it cannot read itself or a later row's
+        // variable (it would see the old value). `uip maestro case validate
+        // --strict` reports these as STRICT_OUTPUT_SELF_REFERENCE /
+        // STRICT_OUTPUT_FORWARD_READ; they need only this task, so check says so.
+        (t.outputs ?? []).forEach((o, i) => {
+            if (!o.custom || !o.source.startsWith('='))
+                return;
+            const later = new Set((t.outputs ?? []).slice(i + 1).map((row) => row.var));
+            for (const name of varsRead(o.source)) {
+                if (name === o.var)
+                    diags.push({
+                        level: 'error',
+                        code: 'OUTPUT_SELF_REFERENCE',
+                        message: `Task "${t.name}" custom output "${o.var}" reads vars.${name}, its own variable. A custom output is set once when the task completes; read another variable, or compute the value from the task's result.`,
+                        where: t.name,
+                    });
+                else if (later.has(name))
+                    diags.push({
+                        level: 'error',
+                        code: 'OUTPUT_FORWARD_READ',
+                        message: `Task "${t.name}" custom output "${o.var}" reads vars.${name}, which a later output on the same task writes. Outputs are evaluated in the order listed, so it would read the old value. List "${name}" before "${o.var}".`,
+                        where: t.name,
+                    });
+            }
+        });
         if (t.kind === 'business-rule') {
             if (!t.ref || !t.ref.name.trim() || !t.ref.folderPath.trim())
                 diags.push({
@@ -548,6 +574,8 @@ function checkStage(stage, diags, refStage, refPlacement, bindings) {
                     where: t.name,
                 });
             for (const o of t.outputs ?? []) {
+                if (o.custom)
+                    continue; // an assigned value, not a result field
                 const wrapped = /^=\s*(result|output)\./.exec(o.source);
                 if (wrapped)
                     diags.push({
@@ -666,3 +694,10 @@ function checkStage(stage, diags, refStage, refPlacement, bindings) {
             });
     }
 }
+/** The case variables an expression reads as `vars.<name>` or `vars["<name>"]`. */
+function varsRead(expression) {
+    const names = new Set();
+    for (const m of expression.matchAll(/\bvars\.([A-Za-z_$][\w$]*)|\bvars\[\s*(['"])(.+?)\2\s*\]/g))
+        names.add(m[1] ?? m[3]);
+    return names;
+}

package/dist/case/decompile.js

@@ -806,9 +806,14 @@ function ioArg(rows, kind) {
     const entries = rows.map((row) => {
         const name = kind === 'inputs' ? row.name : row.var;
         const value = tsLiteral(row[valueField] ?? '');
-        const cell = row.type && row.type !== 'string'
-            ? `{ ${valueField}: ${value}, type: ${tsLiteral(row.type)} }`
-            : value;
+        // A custom output (`custom: true`) assigns its value; it reads no result field.
+        const custom = kind === 'outputs' && row.custom === true;
+        const typed = row.type && row.type !== 'string' ? `, type: ${tsLiteral(row.type)}` : '';
+        const cell = custom
+            ? `{ assign: ${value}${typed} }`
+            : typed
+                ? `{ ${valueField}: ${value}${typed} }`
+                : value;
         return `${key(String(name ?? ''))}: ${cell}`;
     });
     return `{ ${entries.join(', ')} }`;

package/dist/case/serialize.js

@@ -1258,6 +1258,8 @@ const OWN_NAME_OUTPUT_ROWS = new WeakSet();
  * `var` still names the shared case variable.
  */
 function emitTaskOutput(o, elementId, ids, seed, resolver) {
+    if (o.custom)
+        return emitCustomOutput(o, resolver);
     const path = o.source.replace(/^=/, '');
     const field = path.split('.').pop() || o.source;
     // A reassigned row registers the readable companion once (declared vars take
@@ -1291,6 +1293,20 @@ function emitTaskOutput(o, elementId, ids, seed, resolver) {
         elementId,
     };
 }
+/**
+ * A custom assignment output (`.outputs({ x: { assign } })`), as Studio Web and
+ * `uip maestro case sdd convert` (`customOutputFor`) write one: no `id` and no
+ * `originalVar` (it reads no result field), `value` and `source` both the
+ * assigned value, an empty `target` and `body`, and `elementId: 'root'`:
+ *   { name: 'literalResult', type: 'string', custom: true, var: 'literalResult',
+ *     value: 'literal-assigned', source: 'literal-assigned', target: '', body: '', elementId: 'root' }
+ * Like an extract, it registers the root companion so `=vars.<var>` resolves.
+ */
+function emitCustomOutput(o, resolver) {
+    if (!resolver.varCompanions.has(o.var))
+        resolver.varCompanions.set(o.var, { id: o.var, name: o.var, type: o.type, elementId: 'root', custom: true });
+    return { name: o.var, type: o.type, custom: true, var: o.var, value: o.source, source: o.source, target: '', body: '', elementId: 'root' };
+}
 // ─── Business-rule task ───────────────────────────────────────────────────────
 /** The version a business-rule task carries: below v3 the engine cannot run the
  * `.uirule` package a BusinessRules project deploys (the case converter falls
@@ -1707,6 +1723,8 @@ function claimOutputId(resolver, base) {
 }
 /** Whether a task output is written in the own-name shape (see `emitTaskOutput`). */
 function isOwnNameOutput(o) {
+    if (o.custom)
+        return false;
     const path = o.source.replace(/^=/, '');
     return !path.includes('.') && keepsOwnName(o.var, path);
 }

package/dist/registry/curated-overlay.d.ts

@@ -78,6 +78,30 @@ export declare function readOverlayCorrections(overlayPath: string): Promise<Ove
  * What was done is reported in one line, and recorded in `.curated-overlay.json`
  * beside the index, so a second application recognises its own patches: the
  * record keeps a sha256 of each patched entry and sidecar, and a correction
- * whose files no longer match it is patched again.
+ * whose files no longer match it is patched again. The record also names the
+ * overlay that wrote it ({@link curatedOverlayIdentity}). Under a different
+ * overlay, such as a newer SDK pulling a published archive, every correction
+ * is patched again, so fields a newer correction lists are added.
  */
 export declare function applyCuratedOverlay(libraryPath: string, overlayPath?: string, reporter?: Reporter): Promise<CuratedOverlayResult>;
+/** What {@link checkCuratedOverlay} found, one line per item. */
+export interface CuratedOverlayCheck {
+    /** Parts the overlay adds that are absent: the overlay was not applied, or broke. */
+    missing: string[];
+    /**
+     * Corrections whose target the library no longer serves at the correction's
+     * path, or serves without the fields the patch adds: the operation moved,
+     * was renamed or re-versioned. `registry pull` only warns about these too.
+     */
+    staleCorrections: string[];
+}
+/**
+ * Check `libraryPath` against the curated overlay. Both lists are empty once
+ * {@link applyCuratedOverlay} has run on it, unless a correction went stale.
+ * Every overlay identity that is not a correction must be indexed at a file
+ * that exists, and each side-table must equal the bundled copy.
+ *
+ * The connector library pipeline runs this on the archive it publishes,
+ * because readers that load that archive directly apply no overlay.
+ */
+export declare function checkCuratedOverlay(libraryPath: string, overlayPath?: string): Promise<CuratedOverlayCheck>;

package/dist/registry/curated-overlay.js

@@ -34,6 +34,25 @@ export async function curatedOverlayIdentity(overlayPath = bundledOverlayPath())
 function entryIdentity(entry) {
     return `${String(entry.nodeType)}\0${String(entry.version)}`;
 }
+/**
+ * Every path the library resolves each identity to. A `GenericExpanded` or
+ * per-object entry shares its nodeType with its siblings, so an identity
+ * legitimately has more than one.
+ */
+function pathsByIdentity(entries) {
+    const resolvedPaths = new Map();
+    for (const entry of entries) {
+        if (typeof entry.path !== "string")
+            continue;
+        const identity = entryIdentity(entry);
+        const known = resolvedPaths.get(identity);
+        if (known === undefined)
+            resolvedPaths.set(identity, [entry.path]);
+        else
+            known.push(entry.path);
+    }
+    return resolvedPaths;
+}
 /** The ledger of deliberate patches; read here, never copied into a library. */
 export const CORRECTIONS_FILE = "overlay-corrections.json";
 /**
@@ -209,7 +228,10 @@ async function patchCorrection(libraryPath, overlayPath, correction) {
  * What was done is reported in one line, and recorded in `.curated-overlay.json`
  * beside the index, so a second application recognises its own patches: the
  * record keeps a sha256 of each patched entry and sidecar, and a correction
- * whose files no longer match it is patched again.
+ * whose files no longer match it is patched again. The record also names the
+ * overlay that wrote it ({@link curatedOverlayIdentity}). Under a different
+ * overlay, such as a newer SDK pulling a published archive, every correction
+ * is patched again, so fields a newer correction lists are added.
  */
 export async function applyCuratedOverlay(libraryPath, overlayPath = bundledOverlayPath(), 
 // The public materializer API does not forward one, and a warning nobody
@@ -223,24 +245,13 @@ reporter = consoleReporter) {
     const previous = (await exists(recordPath))
         ? (await readJson(recordPath))
         : {};
+    const overlayIdentity = await curatedOverlayIdentity(overlayPath);
+    const sameOverlay = previous.overlayIdentity === overlayIdentity;
     const previouslyAdded = new Set(previous.added ?? []);
     const previousDigests = previous.correctedSha256 ?? {};
     const digests = {};
     const entries = destination.entries ?? [];
-    // Every path the library resolves each identity to. A `GenericExpanded` or
-    // per-object entry shares its nodeType with its siblings, so an identity
-    // legitimately has more than one.
-    const resolvedPaths = new Map();
-    for (const entry of entries) {
-        if (typeof entry.path !== "string")
-            continue;
-        const identity = entryIdentity(entry);
-        const known = resolvedPaths.get(identity);
-        if (known === undefined)
-            resolvedPaths.set(identity, [entry.path]);
-        else
-            known.push(entry.path);
-    }
+    const resolvedPaths = pathsByIdentity(entries);
     const additions = [];
     const skipped = new Set();
     const added = [];
@@ -285,15 +296,18 @@ reporter = consoleReporter) {
             continue;
         }
         // Our own earlier patch, as long as neither file changed since: a refreshed
-        // entry (an `unzip -o` over the same directory, say) is patched again.
+        // entry (an `unzip -o` over the same directory, say) is patched again. So
+        // is our patch under another overlay, whose correction may list more; when
+        // it lists nothing new, the patch is still ours, not upstream catching up.
         const digest = await correctionDigest(libraryPath, row.path);
-        if (previousDigests[row.path] === digest) {
+        const ownPatch = previousDigests[row.path] === digest;
+        if (ownPatch && sameOverlay) {
             corrected.push(row.path);
             digests[row.path] = digest;
             continue;
         }
         const patched = await patchCorrection(libraryPath, overlayPath, correction);
-        if (patched.added.length === 0) {
+        if (patched.added.length === 0 && !ownPatch) {
             kept.push(row.path);
             reporter.warn([
                 `  WARN: curated overlay correction no longer needed: ${row.path} (${correction.since})`,
@@ -338,6 +352,7 @@ reporter = consoleReporter) {
     };
     writeJsonFile(recordPath, {
         $comment: "What the SDK's curated overlay did to this library (registry pull). See curated-overlay.ts.",
+        overlayIdentity,
         added: result.added,
         corrected: result.corrected,
         correctedSha256: digests,
@@ -350,3 +365,82 @@ reporter = consoleReporter) {
         `, kept ${result.kept.length + result.skipped.length} published definition(s) unchanged.`);
     return result;
 }
+/**
+ * Check `libraryPath` against the curated overlay. Both lists are empty once
+ * {@link applyCuratedOverlay} has run on it, unless a correction went stale.
+ * Every overlay identity that is not a correction must be indexed at a file
+ * that exists, and each side-table must equal the bundled copy.
+ *
+ * The connector library pipeline runs this on the archive it publishes,
+ * because readers that load that archive directly apply no overlay.
+ */
+export async function checkCuratedOverlay(libraryPath, overlayPath = bundledOverlayPath()) {
+    const library = (await readJson(join(libraryPath, "index.json")));
+    const overlay = (await readJson(join(overlayPath, "index.json")));
+    const corrections = await readOverlayCorrections(overlayPath);
+    const correctionPaths = new Set(corrections.map((correction) => correction.path));
+    const resolvedPaths = pathsByIdentity(library.entries ?? []);
+    const overlayRows = new Map();
+    const missing = [];
+    const staleCorrections = [];
+    for (const row of overlay.entries ?? []) {
+        if (typeof row.path !== "string")
+            continue;
+        overlayRows.set(row.path, row);
+        if (correctionPaths.has(row.path))
+            continue;
+        const name = `${String(row.nodeType)}@${String(row.version)}`;
+        const paths = resolvedPaths.get(entryIdentity(row));
+        if (paths === undefined) {
+            missing.push(`definition ${name}: no index row`);
+            continue;
+        }
+        for (const path of paths) {
+            if (!(await exists(join(libraryPath, path))))
+                missing.push(`definition ${name}: indexed at ${path}, which is absent`);
+        }
+    }
+    for (const correction of corrections) {
+        const where = `correction ${correction.path} (${correction.since})`;
+        const paths = resolvedPaths.get(entryIdentity(overlayRows.get(correction.path))) ?? [];
+        if (!paths.includes(correction.path)) {
+            staleCorrections.push(`${where}: the library has no definition at that path${paths.length ? ` (it indexes ${paths.join(", ")})` : ""}`);
+            continue;
+        }
+        if (!(await exists(join(libraryPath, correction.path)))) {
+            staleCorrections.push(`${where}: the library indexes that path, but the file is absent`);
+            continue;
+        }
+        const lacks = [];
+        const entry = (await readJson(join(libraryPath, correction.path)));
+        const entryFields = fieldNames(entry.inputSchema?.fields);
+        for (const field of correction.inputFields ?? []) {
+            if (!entryFields.has(field))
+                lacks.push(`inputSchema field ${field}`);
+        }
+        const sidecarPath = join(libraryPath, sidecarOf(correction.path));
+        if (await exists(sidecarPath)) {
+            const sidecar = sidecarBody(await readJson(sidecarPath)) ?? {};
+            const sidecarFields = fieldNames(sidecar.inputDefinition?.fields);
+            for (const field of correction.inputFields ?? []) {
+                if (!sidecarFields.has(field))
+                    lacks.push(`sidecar inputDefinition field ${field}`);
+            }
+            for (const key of correction.sidecarKeys ?? []) {
+                if (!(key in sidecar))
+                    lacks.push(`sidecar key ${key}`);
+            }
+        }
+        if (lacks.length > 0)
+            staleCorrections.push(`${where}: the definition lacks ${lacks.join(", ")}`);
+    }
+    for (const table of SIDE_TABLES) {
+        const target = join(libraryPath, table);
+        if (!(await exists(target)))
+            missing.push(`side-table ${table}: absent`);
+        else if (!(await readFile(target)).equals(await readFile(join(overlayPath, table)))) {
+            missing.push(`side-table ${table}: differs from the SDK's copy`);
+        }
+    }
+    return { missing, staleCorrections };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.53.2",
+  "version": "6.54.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -96,5 +96,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "7836e4e1acb3db20b1eef709958d4c02219f3a78"
+  "gitref": "5dfee12e621c69cfa2cf1338fc7df299768dbe16"
 }