@uipath/maestro-builder-sdk 6.46.4 → 6.46.5

package/dist/case/check.js

@@ -5,6 +5,7 @@ import { caseJsonPreservation, caseJsonPreservationErrors } from './preserve.js'
 import { EQUALS_EXPR_DIALECT, checkBindingLabels, checkConnectorContract, checkConnectorLookups, checkConnectorSchema, } from '../core/connector-checks.js';
 import { checkEventResolution } from '../core/event-checks.js';
 import { EXTERNAL_TASK_DESCRIPTOR_CONTRACT } from './external.js';
+import { isResourceLabelRefusal, resolveResourceRef } from './resource-identity.js';
 const TYPE_NAMES = new Set(Object.values(types));
 // audit-case-coverage: rule-slot table start
 // This runtime table must equal the committed matrix's rejected cells. The audit
@@ -257,7 +258,7 @@ export function check(built, opts = {}) {
     // positive that blocks emit (this gate runs before serialization), so it must be
     // re-derived from the serializer rather than from remembered probe results.
     for (const stage of built.stages) {
-        checkStage(stage, diags, refStage, refPlacement);
+        checkStage(stage, diags, refStage, refPlacement, opts.bindings);
         stage.slaRules.forEach((s, i) => checkSla(s, `stage "${stage.label}" SLA #${i + 1}`, diags));
     }
     built.slaRules.forEach((s, i) => checkSla(s, `case SLA #${i + 1}`, diags));
@@ -394,7 +395,7 @@ function isNilOrEmpty(value) {
         return Object.keys(value).length === 0;
     return false;
 }
-function checkStage(stage, diags, refStage, refPlacement) {
+function checkStage(stage, diags, refStage, refPlacement, bindings) {
     const where = `stage "${stage.label}"`;
     if (stage.exception && stage.required !== false)
         diags.push({
@@ -484,16 +485,15 @@ function checkStage(stage, diags, refStage, refPlacement) {
                 where: t.name,
             });
         // The builder binds a resource task itself: it mints the name/folderPath
-        // binding pair from the literal name and folder. A `=bindings.<id>` string
-        // passed as either becomes part of the binding key, which then names no
-        // resource (`=bindings.f.=bindings.n`) and dangles at deploy.
-        if (t.ref && [t.ref.name, t.ref.folderPath].some((v) => v.trim().startsWith('=bindings.')))
-            diags.push({
-                level: 'error',
-                code: 'RESOURCE_REF_IS_BINDING',
-                message: `Task "${t.name}" passes a "=bindings.<id>" reference as its resource name or folder. Pass the resource's own name and its folder, e.g. .agent('Contract Analysis', { folder: 'Shared/Legal' }); compile writes the name/folderPath binding pair keyed '<folder>.<name>' and points the task at it.`,
-                where: t.name,
-            });
+        // binding pair from the literal name and folder. A `=bindings.<label>` name
+        // or folder is read through bindings.json first, the way a connector's
+        // `connection:` label is; one bindings.json cannot answer is refused with the
+        // same text serialize throws (`resolveResourceRef`).
+        if (t.ref) {
+            const resolved = resolveResourceRef(t.ref, bindings, `Task "${t.name}"`);
+            if (isResourceLabelRefusal(resolved))
+                diags.push({ level: 'error', code: resolved.code, message: resolved.message, where: t.name });
+        }
         if (t.kind === 'business-rule') {
             if (!t.ref || !t.ref.name.trim() || !t.ref.folderPath.trim())
                 diags.push({

package/dist/case/resource-identity.d.ts

@@ -23,6 +23,7 @@
  * `case-validate-service.ts` exempts that prefix from its key/folder agreement
  * check.
  */
+import { type BindingsView } from '../core/binding-messages.js';
 export declare const SOLUTION_FOLDER = "solution_folder";
 export interface ResourceIdentity {
     /** The `resourceKey` both rows of the name/folderPath binding pair carry. */
@@ -42,3 +43,47 @@ export interface ResourceIdentity {
 export declare function resourceIdentity(name: string, folder: string): ResourceIdentity;
 /** True for the key of a resource built inside the same solution. */
 export declare function isInSolutionKey(resourceKey: string): boolean;
+/**
+ * Why a resource task's `=bindings.<label>` name or folder cannot be resolved.
+ *
+ * - `RESOURCE_REF_IS_BINDING`: there is no bindings.json (or it declares nothing),
+ *   so the label names nothing compile can read.
+ * - `RESOURCE_BINDING_UNDECLARED`: bindings.json does not declare the label, or
+ *   declares it with no value.
+ */
+export interface ResourceLabelRefusal {
+    code: 'RESOURCE_REF_IS_BINDING' | 'RESOURCE_BINDING_UNDECLARED';
+    message: string;
+}
+/**
+ * The literal name and folder of a resource task, with any `=bindings.<label>`
+ * resolved through the project's bindings.json, the way a connector task's
+ * `connection:` label is.
+ *
+ *   bindings.json  { "name": "agentName",   "default": "Agent" }
+ *                  { "name": "agentFolder", "default": "Shared/Golden" }
+ *   .agent('=bindings.agentName', { folder: '=bindings.agentFolder' })
+ *     -> { name: 'Agent', folderPath: 'Shared/Golden' }
+ *
+ * The task then compiles exactly as `.agent('Agent', { folder: 'Shared/Golden' })`
+ * does: compile mints the name/folderPath binding pair keyed `<folder>.<name>`.
+ * Passing the label straight through instead keyed the pair
+ * `=bindings.f.=bindings.n`, which names no resource and dangles at deploy.
+ *
+ * @param ref - The authored name and folder.
+ * @param bindings - The project's bindings.json, if any.
+ * @param where - The task, as a diagnostic names it.
+ * @returns The literal pair, or the refusal.
+ */
+export declare function resolveResourceRef(ref: {
+    name: string;
+    folderPath: string;
+}, bindings: BindingsView | undefined, where: string): {
+    name: string;
+    folderPath: string;
+} | ResourceLabelRefusal;
+/** True when {@link resolveResourceRef} refused. */
+export declare function isResourceLabelRefusal(r: {
+    name: string;
+    folderPath: string;
+} | ResourceLabelRefusal): r is ResourceLabelRefusal;

package/dist/case/resource-identity.js

@@ -23,6 +23,7 @@
  * `case-validate-service.ts` exempts that prefix from its key/folder agreement
  * check.
  */
+import { GUID_RE } from '../core/binding-messages.js';
 export const SOLUTION_FOLDER = 'solution_folder';
 const SOLUTION_FOLDER_KEY_PREFIX = `${SOLUTION_FOLDER}.`;
 /**
@@ -43,3 +44,72 @@ export function resourceIdentity(name, folder) {
 export function isInSolutionKey(resourceKey) {
     return resourceKey.startsWith(SOLUTION_FOLDER_KEY_PREFIX);
 }
+/** How a resource task's name or folder spells a bindings.json label. */
+const BINDING_LABEL_PREFIX = '=bindings.';
+/** The literal value bindings.json declares for `label`, or `undefined`. */
+function declaredValue(bindings, label) {
+    const entry = bindings?.entry?.(label);
+    // `default` is the value a person reads (the resource's name, the folder
+    // path); `resourceKey` can be the resource's GUID. A map-form bindings.json
+    // puts the value in both. A GUID-shaped `resourceKey` is never a name or a
+    // folder: taking it would key the pair `<folder>.<guid>`, which dangles at
+    // deploy, so the label falls through to RESOURCE_BINDING_UNDECLARED.
+    const fallback = typeof entry?.resourceKey === 'string' && GUID_RE.test(entry.resourceKey.trim()) ? undefined : entry?.resourceKey;
+    const value = entry ? (entry.default ?? fallback) : bindings?.resolve(label);
+    return typeof value === 'string' && value.trim() && !value.trim().startsWith(BINDING_LABEL_PREFIX)
+        ? value
+        : undefined;
+}
+/**
+ * The literal name and folder of a resource task, with any `=bindings.<label>`
+ * resolved through the project's bindings.json, the way a connector task's
+ * `connection:` label is.
+ *
+ *   bindings.json  { "name": "agentName",   "default": "Agent" }
+ *                  { "name": "agentFolder", "default": "Shared/Golden" }
+ *   .agent('=bindings.agentName', { folder: '=bindings.agentFolder' })
+ *     -> { name: 'Agent', folderPath: 'Shared/Golden' }
+ *
+ * The task then compiles exactly as `.agent('Agent', { folder: 'Shared/Golden' })`
+ * does: compile mints the name/folderPath binding pair keyed `<folder>.<name>`.
+ * Passing the label straight through instead keyed the pair
+ * `=bindings.f.=bindings.n`, which names no resource and dangles at deploy.
+ *
+ * @param ref - The authored name and folder.
+ * @param bindings - The project's bindings.json, if any.
+ * @param where - The task, as a diagnostic names it.
+ * @returns The literal pair, or the refusal.
+ */
+export function resolveResourceRef(ref, bindings, where) {
+    const out = { name: ref.name, folderPath: ref.folderPath };
+    for (const attribute of ['name', 'folderPath']) {
+        const authored = ref[attribute].trim();
+        if (!authored.startsWith(BINDING_LABEL_PREFIX))
+            continue;
+        const label = authored.slice(BINDING_LABEL_PREFIX.length);
+        const what = attribute === 'name' ? 'resource name' : 'folder';
+        const literal = `e.g. .agent('Contract Analysis', { folder: 'Shared/Legal' })`;
+        const declared = bindings?.declared?.() ?? [];
+        if (declared.length === 0)
+            return {
+                code: 'RESOURCE_REF_IS_BINDING',
+                message: `${where} passes "${authored}" as its ${what}, and there is no bindings.json declaring "${label}". `
+                    + `Declare it in bindings.json ({ "name": "${label}", "default": "<the ${what}>" }), or pass the ${what} itself, ${literal}; `
+                    + `compile writes the name/folderPath binding pair keyed '<folder>.<name>' and points the task at it.`,
+            };
+        const value = declaredValue(bindings, label);
+        if (value === undefined)
+            return {
+                code: 'RESOURCE_BINDING_UNDECLARED',
+                message: `${where} passes "${authored}" as its ${what}, but bindings.json does not declare "${label}" with a value `
+                    + `(it declares: ${declared.join(', ')}). Use one of those labels, add "${label}" with its ${what} as "default", `
+                    + `or pass the ${what} itself, ${literal}.`,
+            };
+        out[attribute] = value;
+    }
+    return out;
+}
+/** True when {@link resolveResourceRef} refused. */
+export function isResourceLabelRefusal(r) {
+    return 'code' in r;
+}

package/dist/case/serialize.js

@@ -18,7 +18,7 @@ import { resolveEventWhere } from '../core/lookups.js';
 import { resolveCaseSubscription } from './subscription.js';
 import { externalDescriptorRefusal } from './external.js';
 import { CASE_FORMAT_PROFILE, CASE_SCHEMA_VERSIONS } from './format-profile.js';
-import { resourceIdentity } from './resource-identity.js';
+import { isResourceLabelRefusal, resolveResourceRef, resourceIdentity } from './resource-identity.js';
 import { ownEntry } from '../core/own-entry.js';
 import { resolveSchemaVersion } from '../schema-version.js';
 import { caseJsonPreservation, caseJsonPreservationErrors, } from './preserve.js';
@@ -914,7 +914,7 @@ function taskData(task, resolver, taskId, stageId, ids) {
             // never literals: `validate` refuses a literal (CASE_MGMT_RESOURCE_TASK_
             // LITERAL_BINDING), and deploy re-targets a resource only through its
             // binding (#1240).
-            const { nameRef, folderRef } = referenceBindings(task.kind, task.ref, resolver, ids);
+            const { nameRef, folderRef } = referenceBindings(task.kind, task.ref, resolver, ids, task.name);
             const data = { name: nameRef, folderPath: folderRef };
             const elementId = `${stageId}-${taskId}`;
             if (task.inputs?.length)
@@ -940,7 +940,7 @@ function taskData(task, resolver, taskId, stageId, ids) {
             // The Action App the task opens, bound like any resource: an `app`
             // name/folderPath pair keyed `<deployment folder>.<app>` (#1240).
             if (task.ref) {
-                const { nameRef, folderRef } = referenceBindings('action', task.ref, resolver, ids);
+                const { nameRef, folderRef } = referenceBindings('action', task.ref, resolver, ids, task.name);
                 data.name = nameRef;
                 data.folderPath = folderRef;
             }
@@ -1278,7 +1278,12 @@ function resourceBinding(resolver, ids, binding, resourceKey, propertyAttribute,
 /** The binding `resource` an action task's Action App is bound by (no subtype). */
 const ACTION_APP_RESOURCE = 'app';
 /** The `=bindings.<id>` name/folderPath references of a published-resource task. */
-function referenceBindings(kind, ref, resolver, ids) {
+function referenceBindings(kind, authored, resolver, ids, taskName) {
+    // A `=bindings.<label>` name or folder reads through bindings.json to its
+    // literal value, so the task binds exactly as the literal form does.
+    const ref = resolveResourceRef(authored, resolver.bindings, `Task "${taskName}"`);
+    if (isResourceLabelRefusal(ref))
+        throw new Error(`[${ref.code}] ${ref.message}`);
     const binding = kind === 'business-rule'
         ? { resource: BUSINESS_RULE_RESOURCE }
         : kind === 'action'
@@ -1308,7 +1313,7 @@ function referenceBindings(kind, ref, resolver, ids) {
  *   (`=<Decision>.<column>`).
  */
 function businessRuleTaskData(task, resolver, elementId, ids) {
-    const { nameRef, folderRef } = referenceBindings(task.kind, task.ref, resolver, ids);
+    const { nameRef, folderRef } = referenceBindings(task.kind, task.ref, resolver, ids, task.name);
     const ownRow = (name, source, seed, extra = {}) => {
         const slot = ids.make('v', 8, `${elementId}:${seed}`);
         return { name, type: 'jsonSchema', id: slot, var: slot, value: slot, source, target: `=${slot}`, elementId, ...extra };

package/package.json

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