@uipath/maestro-builder-sdk 6.70.5 → 6.70.7

package/dist/case/task-output-ref.js

@@ -0,0 +1,212 @@
+/**
+ * Reading another task's output in place: the SDD's `vars.$xref('<stage>',
+ * '<task>', '<output>')` marker, and `taskOutput()`, the typed way to write it
+ * (builder-sdk#1241).
+ *
+ * A task's own output is a variable of its own: the Case Designer saves it as
+ * `{ name: 'AgentExpenseRequest', id: 'agentExpenseRequest', var:
+ * 'agentExpenseRequest' }`, with no root `variables` entry, and a later task
+ * reads it as `=vars.agentExpenseRequest`. The id is the plan's, not the
+ * author's: it is unique across the plan, so a second task's `Action` output
+ * is `action2`. An SDD therefore names an output by where it is produced, and
+ * `uip maestro case sdd convert` lowers each marker to `vars.<output id>`
+ * (`sdd-convert/xrefs.ts`). Without the lowering here, an author had to copy
+ * the value into a case variable the SDD does not declare, and `validate
+ * --strict --sdd` refuses each one (`STRICT_SDD_VARIABLE_EXTRA`).
+ *
+ * The rule lives here so `check` (at `build()`) and `serialize` read a marker
+ * the same way. `build()` cannot see the ids, which `serialize` mints, so it
+ * resolves the stage and the task, and the output where the task's rows are
+ * all authored (a reference-mode task). `serialize` resolves every marker
+ * against the rows it wrote and refuses one that names no output.
+ */
+/**
+ * One argument, read by its own delimiter: `'…'`, `"…"`, `` `…` `` or the curly
+ * pair, the four `sdd convert` accepts. A curly pair is two code points, so it
+ * gets its own branch instead of a backreference.
+ */
+const QUOTED = String.raw `(?:'((?:\\.|[^'\\])*)'|"((?:\\.|[^"\\])*)"|` +
+    '`((?:\\\\.|[^`\\\\])*)`' +
+    String.raw `|\u201c([^\u201d]*)\u201d)`;
+/** A `vars.$xref(stage, task, output)` marker. Global: use with `replace`/`matchAll` only. */
+const XREF_CALL = new RegExp(String.raw `vars\.\$xref\(\s*${QUOTED}\s*,\s*${QUOTED}\s*,\s*${QUOTED}\s*\)`, 'g');
+/**
+ * A property read glued to the marker (`vars.$xref(…).unusualClauses`). The
+ * producer may not have run when the reader does, so inside a `=js:`
+ * expression the lowering writes the optional chain
+ * `vars.<id>?.unusualClauses`, as `sdd convert` does. Only there: `?.` is
+ * JavaScript, and nothing shows that the platform's non-js `=vars.<path>`
+ * binding reads it, so any other value keeps the plain `.`.
+ */
+const DOTTED_READ = /^\.[A-Za-z_$]/;
+const unescape = (value) => value.replace(/\\(.)/g, '$1');
+/** Each marker in `text`, in order, with where it sits. */
+export function taskOutputRefs(text) {
+    if (!text.includes('$xref'))
+        return [];
+    return [...text.matchAll(XREF_CALL)].map((m) => {
+        const arg = (from) => unescape(m.slice(from, from + 4).find((v) => v !== undefined) ?? '');
+        return { stage: arg(1), task: arg(5), output: arg(9), whole: m[0], index: m.index ?? 0 };
+    });
+}
+/**
+ * Replace every marker in `text` with what `lower` returns for it. In a `=js:`
+ * expression, a marker followed by a property read gets the optional chain
+ * (`vars.<id>?.field`); any other value keeps the plain read (`vars.<id>.field`).
+ *
+ * @param text - The expression.
+ * @param lower - The variable a marker reads (`agentExpenseRequest`), or `undefined` to keep the marker.
+ */
+export function lowerTaskOutputRefs(text, lower) {
+    if (!text.includes('$xref'))
+        return text;
+    const js = /^\s*=js:/.test(text);
+    let out = '';
+    let at = 0;
+    for (const ref of taskOutputRefs(text)) {
+        const after = text.slice(ref.index + ref.whole.length);
+        const variable = lower(ref);
+        // `undefined` keeps the marker as written (a reference to a stand-in; see `resolveInPlan`).
+        out += variable === undefined ? text.slice(at, ref.index) + ref.whole : `${text.slice(at, ref.index)}vars.${variable}${js && DOTTED_READ.test(after) ? '?' : ''}`;
+        at = ref.index + ref.whole.length;
+    }
+    return out + text.slice(at);
+}
+/**
+ * The one candidate `name` picks out: an exact match first, then a
+ * case-insensitive one (an SDD addresses a stage or an output in any case).
+ * `undefined` when none does; `'ambiguous'` when more than one does.
+ */
+export function pickByName(items, name, names) {
+    for (const same of [(a) => a === name, (a) => a.toLowerCase() === name.toLowerCase()]) {
+        const hits = [...new Set(items.filter((item) => names(item).some((n) => n !== undefined && same(n))))];
+        if (hits.length === 1)
+            return hits[0];
+        if (hits.length > 1)
+            return 'ambiguous';
+    }
+    return undefined;
+}
+/**
+ * The row an output reference names among one task's rows: by the field it
+ * reads (`name`) or by the variable it writes (`var`).
+ */
+export function pickOutputRow(rows, output) {
+    return pickByName(rows, output, (row) => [row.name, row.var]);
+}
+/** The refusal message for a marker that resolves to nothing. */
+export function unresolvedTaskOutputRef(ref, why) {
+    return `taskOutput(${JSON.stringify(ref.stage)}, ${JSON.stringify(ref.task)}, ${JSON.stringify(ref.output)}) ${why}. ` +
+        'A task-output reference names the stage label, the task name and the output (the result field it reads, or the key it has in `.outputs()`).';
+}
+/**
+ * The marker for a reference: `vars.$xref('<stage>','<task>','<output>')`,
+ * each argument single-quoted with its quotes and backslashes escaped. What
+ * `taskOutput()` returns, and what decompile writes back.
+ */
+export function taskOutputMarker(stage, task, output) {
+    const quote = (value) => `'${value.replace(/[\\']/g, '\\$&')}'`;
+    return `vars.$xref(${quote(stage)},${quote(task)},${quote(output)})`;
+}
+/** Every stage task's output rows in a written caseplan, in document order. */
+export function planTaskOutputs(plan) {
+    const found = [];
+    const nodes = plan?.nodes;
+    for (const node of Array.isArray(nodes) ? nodes : []) {
+        const data = node?.data;
+        if (typeof data?.label !== 'string' || !Array.isArray(data.tasks))
+            continue;
+        for (const lane of data.tasks)
+            for (const task of Array.isArray(lane) ? lane : []) {
+                if (typeof task?.displayName !== 'string')
+                    continue;
+                const rows = Array.isArray(task.data?.outputs) ? task.data.outputs : [];
+                found.push({
+                    stage: data.label,
+                    task: task.displayName,
+                    rows: rows.filter((row) => row && typeof row === 'object'),
+                    ...(task.data?.standIn === true ? { standIn: true } : {}),
+                });
+            }
+    }
+    return found;
+}
+/**
+ * What a reference reads in a written plan: the variable of the row it names
+ * (`vars.<id>`, or a custom row's `var`, which has no id), or why it names none.
+ */
+export function resolveInPlan(tasks, ref) {
+    const stage = pickByName([...new Set(tasks.map((t) => t.stage))], ref.stage, (label) => [label]);
+    if (stage === undefined)
+        return { why: `names no stage labelled ${JSON.stringify(ref.stage)}` };
+    if (stage === 'ambiguous')
+        return { why: `names a stage label that more than one stage answers to` };
+    const task = pickByName(tasks.filter((t) => t.stage === stage), ref.task, (t) => [t.task]);
+    if (task === undefined)
+        return { why: `names no task ${JSON.stringify(ref.task)} in stage ${JSON.stringify(stage)}` };
+    if (task === 'ambiguous')
+        return { why: `names a task that more than one task in stage ${JSON.stringify(stage)} answers to` };
+    // The named task was refused and stood in (collect mode). Its refusal is the
+    // finding; its outputs were never written, so there is nothing to judge the
+    // reference against here (`build()` already judged it against the authored ones).
+    if (task.standIn)
+        return { standIn: true };
+    const row = pickOutputRow(task.rows, ref.output);
+    const offered = [...new Set(task.rows.map((r) => r.name).filter((n) => typeof n === 'string'))];
+    if (row === undefined)
+        return { why: `names no output of task ${JSON.stringify(task.task)}, whose outputs are ${offered.length ? offered.map((n) => JSON.stringify(n)).join(', ') : 'none'}` };
+    if (row === 'ambiguous')
+        return { why: `names more than one output of task ${JSON.stringify(task.task)}; name it by the variable it writes instead` };
+    const variable = typeof row.id === 'string' && row.id ? row.id : row.var;
+    if (typeof variable !== 'string' || !variable)
+        return { why: `names an output of task ${JSON.stringify(task.task)} that writes no variable` };
+    return { variable };
+}
+/**
+ * Turn each `vars.<output id>` read in `text` that only a task-output reference
+ * can say back into `vars.$xref(…)`, for decompile. `byId` maps such an id to
+ * the reference that names it.
+ */
+export function raiseTaskOutputReads(text, byId) {
+    if (!byId.size || !text.includes('vars.'))
+        return text;
+    return text.replace(/(?<![\w$.])vars\.([A-Za-z_$][\w$]*)(?![\w$])/g, (whole, id) => {
+        const ref = byId.get(id);
+        return ref ? taskOutputMarker(ref.stage, ref.task, ref.output) : whole;
+    });
+}
+/**
+ * The output ids a decompiled source can only read back by reference: a row
+ * whose id is not the variable it writes (a reassigned extract, a Designer row
+ * such as `{ id: 'oA1b2C3d4', var: 'AgentExpenseRequest' }`). Recompiling mints
+ * that id afresh, and no declaration makes `vars.<id>` readable, so a
+ * `vars.<id>` read in the plan goes back to the source as the reference that
+ * resolves to the same row. A read of an id that is also a variable (an
+ * own-name row, a root variable) is left as written. A row the reference
+ * could not name uniquely is left as written too.
+ */
+export function referableOutputIds(plan, rootNames) {
+    const tasks = planTaskOutputs(plan);
+    const vars = new Set(rootNames);
+    for (const task of tasks)
+        for (const row of task.rows)
+            if (typeof row.var === 'string')
+                vars.add(row.var);
+    const byId = new Map();
+    for (const task of tasks)
+        for (const row of task.rows) {
+            if (typeof row.id !== 'string' || !row.id || row.id === row.var || vars.has(row.id))
+                continue;
+            for (const output of [row.name, row.var]) {
+                if (typeof output !== 'string' || !output)
+                    continue;
+                const ref = { stage: task.stage, task: task.task, output };
+                const resolved = resolveInPlan(tasks, ref);
+                if ('variable' in resolved && resolved.variable === row.id) {
+                    byId.set(row.id, ref);
+                    break;
+                }
+            }
+        }
+    return byId;
+}

package/dist/compile-cli.js

@@ -24,7 +24,7 @@
  */
 import { diagnosticLine, reportDiagnostics, reportResult, thrownDiagnostic } from './cli-result.js';
 import { writeJsonFile } from './core/json-file.js';
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { serializeWithSidecars } from './serialize.js';
@@ -36,7 +36,7 @@ import { connectionResources, inlineAgentResources, mergeBindingsV2, refreshInli
 import { readBindingsV2, readInlineAgentFiles } from './bindings-v2-files.js';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
 import { defaultBindingsFile } from './workdir.js';
-import { isWithin } from './path-within.js';
+import { isWithin, physicalPath } from './path-within.js';
 import { flowSources, resourceSourcesOfOtherFlows } from './project-resource-users.js';
 import { fnv1aX4Uuid } from './core/stable-id.js';
 import { CompileRefusal } from './core/compile-refusal.js';
@@ -86,7 +86,20 @@ export async function run(argv) {
     // BYOA-only event on a connection `prepare` never checked
     // (EVENT_BYOA_UNVERIFIED): printed in the same `✗ [CODE]` shape `check` uses
     // for it. Nothing is written.
-    const out = flagValue(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;
+    const explicitOut = flagValue(argv, '-o');
+    const out = explicitOut ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;
+    // The default is named after the flow, which decompile copies from the input: keep it inside cwd.
+    if (explicitOut === undefined) {
+        const target = physicalPath(resolve(out));
+        if (target === undefined || !isWithin(realpathSync.native(process.cwd()), target)) {
+            const message = `refusing to write ${out} outside the working directory: without -o the output is named after`
+                + ` the flow (${JSON.stringify(built.name)}). Pass -o <file>.flow to choose where it is written`;
+            console.error(`compile: ${message}; not emitting.`);
+            diagnostics.push({ level: 'error', code: 'FLOW_NAME_OUTSIDE_WORKING_DIR', message });
+            reportDiagnostics(diagnostics);
+            return 1;
+        }
+    }
     const outDir = dirname(resolve(out));
     // ONE FOLDER, ONE FLOW (#1184). An agent's `source` is the name of the folder
     // beside the `.flow` that holds its `agent.json` and `resources/`. Decompile

package/dist/core/refusals.d.ts

@@ -640,6 +640,7 @@ export declare const REFUSALS: {
     readonly TASK_OUTPUTS_NO_RESPONSE: "lowering";
     readonly TASK_OUTPUTS_PLACEHOLDER_EVENT: "lowering";
     readonly TASK_OUTPUTS_UNSUPPORTED: "lowering";
+    readonly TASK_OUTPUT_REF_UNRESOLVED: "lowering";
     readonly TASK_OUTPUT_SOURCE_AND_ASSIGN: "lowering";
     readonly TASK_REENTRY_IGNORED: "lint";
     readonly TASK_TIMER_OUT_OF_RANGE: "lint";

package/dist/core/refusals.js

@@ -692,6 +692,7 @@ export const REFUSALS = {
     TASK_OUTPUTS_NO_RESPONSE: 'lowering',
     TASK_OUTPUTS_PLACEHOLDER_EVENT: 'lowering',
     TASK_OUTPUTS_UNSUPPORTED: 'lowering',
+    TASK_OUTPUT_REF_UNRESOLVED: 'lowering',
     TASK_OUTPUT_SOURCE_AND_ASSIGN: 'lowering',
     TASK_REENTRY_IGNORED: 'lint',
     TASK_TIMER_OUT_OF_RANGE: 'lint',

package/dist/path-within.d.ts

@@ -1,20 +1,3 @@
-/**
- * path-within — the one path-containment test for anything that writes files.
- *
- * "Is `child` inside `parent`?" looks like a string-prefix question and is not
- * one. `child.startsWith(parent + '/')` is correct only where the separator is
- * `/`: on Windows `path.resolve` returns `C:\proj\P\x`, the check refuses every
- * path, and compile refused every inline agent's `<source>/agent.json`
- * (flow-builder-sdk#946). A prefix test without a trailing separator has the
- * opposite bug: it accepts the sibling `C:\proj\P2\x` as inside `C:\proj\P`.
- *
- * So the test is `relative(parent, child)` instead, which gets both right on
- * every platform, and Windows' case-insensitive drive letters and
- * cross-drive paths (`relative` returns the absolute `D:\x` there) with them.
- *
- * The path implementation is a parameter so the Windows rules can be tested on
- * a Linux runner (`isWithin(a, b, path.win32)`). Callers leave it out.
- */
 import * as nodePath from 'node:path';
 /** The slice of `node:path` the test needs; `path.win32` and `path.posix` both fit. */
 export type PathApi = Pick<typeof nodePath, 'relative' | 'isAbsolute' | 'sep'>;
@@ -31,3 +14,18 @@ export type PathApi = Pick<typeof nodePath, 'relative' | 'isAbsolute' | 'sep'>;
  *   isWithin('C:\\proj\\P', 'D:\\agent.json', path.win32)  // false — other drive
  */
 export declare function isWithin(parent: string, child: string, path?: PathApi): boolean;
+/**
+ * Where `dir` lands on disk: the real path of its deepest ancestor that
+ * exists, every link on the way followed, then the rest of `dir`, which does
+ * not exist yet and so holds no link. `undefined` when that ancestor's real
+ * path cannot be read: a link to nothing, or a loop of links. A caller treats
+ * `undefined` as outside.
+ *
+ * The agent SDK's CLI keeps a copy of this function for its default output
+ * folder, so both CLIs follow links the same way.
+ *
+ * @example
+ *   // ./work/sw-basic/l is a link to /elsewhere, and X does not exist:
+ *   physicalPath('/cwd/work/sw-basic/l/X')  // '/elsewhere/X'
+ */
+export declare function physicalPath(dir: string): string | undefined;

package/dist/path-within.js

@@ -12,10 +12,16 @@
  * every platform, and Windows' case-insensitive drive letters and
  * cross-drive paths (`relative` returns the absolute `D:\x` there) with them.
  *
+ * `isWithin` reads only the spelling of its paths, so a link inside `parent`
+ * that points out of it passes. A check that guards a write compares
+ * `physicalPath`s instead.
+ *
  * The path implementation is a parameter so the Windows rules can be tested on
  * a Linux runner (`isWithin(a, b, path.win32)`). Callers leave it out.
  */
+import { lstatSync, realpathSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { basename, dirname, join } from 'node:path';
 /**
  * `child` is `parent` itself or somewhere beneath it.
  *
@@ -39,3 +45,41 @@ export function isWithin(parent, child, path = nodePath) {
     // Windows: a child on another drive has no relative spelling.
     return !path.isAbsolute(rel);
 }
+/**
+ * Where `dir` lands on disk: the real path of its deepest ancestor that
+ * exists, every link on the way followed, then the rest of `dir`, which does
+ * not exist yet and so holds no link. `undefined` when that ancestor's real
+ * path cannot be read: a link to nothing, or a loop of links. A caller treats
+ * `undefined` as outside.
+ *
+ * The agent SDK's CLI keeps a copy of this function for its default output
+ * folder, so both CLIs follow links the same way.
+ *
+ * @example
+ *   // ./work/sw-basic/l is a link to /elsewhere, and X does not exist:
+ *   physicalPath('/cwd/work/sw-basic/l/X')  // '/elsewhere/X'
+ */
+export function physicalPath(dir) {
+    const rest = [];
+    let at = dir;
+    for (;;) {
+        try {
+            lstatSync(at);
+            break;
+        }
+        catch {
+            // Missing: its parent, then.
+        }
+        const parent = dirname(at);
+        if (parent === at)
+            break;
+        rest.unshift(basename(at));
+        at = parent;
+    }
+    try {
+        return join(realpathSync.native(at), ...rest);
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.70.5",
+  "version": "6.70.7",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -100,5 +100,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "fa9dc7bf7b81b8dfd7fe6090beb21100879d79f6"
+  "gitref": "31471f814e8ca706a02e96e3dbceb39641584de6"
 }