@uipath/maestro-builder-sdk 6.31.5 → 6.31.6

package/dist/compile-cli.js

@@ -19,7 +19,7 @@
  */
 import { reportDiagnostics, reportResult, thrownDiagnostic } from './cli-result.js';
 import { writeJsonFile } from './core/json-file.js';
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { serializeWithSidecars, compileOwnsResource } from './serialize.js';
@@ -32,9 +32,12 @@ 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 { resourceSourcesOfOtherFlows } from './project-resource-users.js';
+import { flowSources, resourceSourcesOfOtherFlows } from './project-resource-users.js';
+import { fnv1aX4Uuid } from './core/stable-id.js';
 import { BindingRefusal } from './core/binding-messages.js';
 import { ByoaRefusal } from './core/byoa.js';
+/** An agent folder name: a uuid, any case. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export async function run(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
         console.error('usage: compile <flow.ts | BaseName> [-o out.flow] [--library <dir>] [--bindings <file>]');
@@ -93,10 +96,57 @@ export async function run(argv) {
     // (EVENT_BYOA_UNVERIFIED): the check pass above reports each first, and this is
     // the same refusal in the same `✗ [CODE]` shape when that pass was skipped
     // (`--no-check`, or an emit-only project). Nothing is written.
+    const out = flagValue(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;
+    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
+    // keeps a canvas agent's `source` (the sidecar must still resolve), so
+    // compiling that source to a SECOND `.flow` in the same project would write
+    // into the first flow's folder: its `agent.json` is overwritten with the new
+    // flow's agent, and `uip agent refresh` for the new flow declares every
+    // resource the first flow keeps there. The product never shares a folder
+    // either: Studio Web mints a fresh uuid for an imported flow whose agent the
+    // project already owns, copies the folder and restamps `projectId`
+    // (flow-workbench MST-14919). So does compile: an agent whose `source`
+    // another `.flow` in this Flow project claims is written to its own folder,
+    // derived from that `source` and this file's name, so a recompile lands in
+    // the same one. Outside a Flow project (`project.uiproj`) nothing is a
+    // deliverable: the brownfield loop writes its baseline/edited candidates
+    // beside the original on purpose, and they are left as they were.
+    //
+    // Two rules keep the choice stable across later edits to the project:
+    //   - The OWNER keeps its folder. A source the existing `out` file already
+    //     names stays put, even if another `.flow` names it too (one compiled
+    //     into it before this rule existed): the flow being recompiled is the one
+    //     that already lives there, so it is never the one moved.
+    //   - A re-home is STICKY. Once the re-homed folder exists, the step keeps
+    //     writing there even after the flow that claimed the old folder is
+    //     deleted or renamed; otherwise the next compile would move back into the
+    //     old folder (and its leftover resources) and orphan the new one.
+    const inProject = existsSync(join(outDir, 'project.uiproj'));
+    const claimed = inProject ? sourcesOfOtherFlows(outDir, resolve(out)) : new Map();
+    const ownSources = inProject ? new Set(flowSources(readJsonOrUndefined(resolve(out))).map((s) => s.toLowerCase())) : new Set();
+    const rehomed = new Map();
+    const agentSource = (source, step) => {
+        // Only a uuid names a folder (as in Studio Web); anything else is left to
+        // the sidecar-path check below rather than read from here.
+        if (!inProject || !UUID.test(source))
+            return source;
+        const key = source.toLowerCase();
+        if (ownSources.has(key))
+            return source;
+        const to = fnv1aX4Uuid(`${key}/${basename(out)}`);
+        const owner = claimed.get(key);
+        if (owner === undefined)
+            return existsSync(join(outDir, to, 'agent.json')) ? to : source;
+        if (!rehomed.has(source))
+            rehomed.set(source, { from: source, to, step, owner });
+        return to;
+    };
     const warnings = [];
     let emitted;
     try {
-        emitted = serializeWithSidecars(built, { library, bindings, warn: (w) => warnings.push(w) });
+        emitted = serializeWithSidecars(built, { library, bindings, warn: (w) => warnings.push(w), agentSource });
     }
     catch (error) {
         for (const w of warnings)
@@ -119,7 +169,6 @@ export async function run(argv) {
     for (const w of warnings)
         console.error(`  ⚠ [${w.code}] ${w.message}`);
     diagnostics.push(...warnings.map(serializeWarningDiagnostic));
-    const out = flagValue(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;
     // An inline agent is TWO artifacts: the node, and the agent's own configuration
     // at `<source>/agent.json` — which is where flow-v1's serializer points the
     // runtime (`entryPoint: "<source>/agent.json"`, resolved relative to the
@@ -131,7 +180,6 @@ export async function run(argv) {
     //
     // Every sidecar is checked before anything is written; success is reported
     // only once every file is on disk.
-    const outDir = dirname(resolve(out));
     const targets = sidecars.map((s) => ({ sidecar: s, target: resolve(outDir, s.path) }));
     const escaping = targets.find(({ target }) => target === outDir || !isWithin(outDir, target));
     if (escaping) {
@@ -152,6 +200,20 @@ export async function run(argv) {
         console.log(`compile: wrote ${sidecar.path}`);
         written.push(target);
     }
+    // A re-homed agent's folder starts as a copy of the folder it came from, minus
+    // what this compile just wrote (its `agent.json`, the resources it derives)
+    // and minus every `resources/<id>/` this flow's nodes do not name — copying
+    // those would hand the new flow's agent the old flow's index again, which is
+    // the bug. A file already in the new folder is the new flow's own and is kept.
+    if (rehomed.size > 0) {
+        const referenced = new Set(flowSources(flowJson).map((s) => s.toLowerCase()));
+        for (const { from, to, step, owner } of rehomed.values()) {
+            const copied = seedFolder(join(outDir, from), join(outDir, to), referenced);
+            console.log(`compile: agent "${step}" uses its own folder ${to}: ${from} belongs to ${owner}`
+                + (copied > 0 ? ` (copied ${copied} file(s) from it)` : '')
+                + `. To make this explicit, set source: "${to}" on "${step}" in the .flow.ts.`);
+        }
+    }
     reportResult({ path: resolve(out), nodes: flowJson.nodes.length, edges: flowJson.edges.length, sidecars: written });
     // PRUNE the agent resources this compile owns but did not write this time.
     // Compile otherwise only ever ADDS files, and an agent resource is keyed by a
@@ -176,7 +238,11 @@ export async function run(argv) {
     // canvas resources there are still that flow's. A resource another
     // `.flow` beside this one references by `inputs.source` is never pruned.
     const removedResources = [];
-    const referencedElsewhere = resourceSourcesOfOtherFlows(outDir, resolve(out));
+    const referencedElsewhere = sourcesOfOtherFlows(outDir, resolve(out));
+    // ... and neither is one THIS flow still names: a re-homed agent's folder is
+    // seeded with the resources its nodes reference (see `seedFolder`), and a
+    // designer resource a node here points at is in use, whatever its type.
+    const referencedHere = new Set(flowSources(flowJson).map((s) => s.toLowerCase()));
     const owned = new Set(sidecars
         .filter((s) => /\/resources\/[^/]+\/resource\.json$/.test(s.path))
         .map((s) => resolve(outDir, s.path)));
@@ -189,9 +255,9 @@ export async function run(argv) {
             continue;
         for (const entry of readdirSync(resourcesDir)) {
             const file = join(resourcesDir, entry, 'resource.json');
-            if (!existsSync(file) || owned.has(file))
+            if (!existsSync(file) || owned.has(file) || referencedHere.has(entry.toLowerCase()))
                 continue;
-            const user = referencedElsewhere.get(entry);
+            const user = referencedElsewhere.get(entry.toLowerCase());
             if (user !== undefined) {
                 console.log(`compile: kept ${join('resources', entry, 'resource.json')}: ${user} still references it`);
                 continue;
@@ -251,3 +317,60 @@ function serializeWarningDiagnostic(w) {
     return { level: 'warning', code: w.code, message: w.message };
 }
 runWhenInvokedDirectly(import.meta.url, 'compile', run);
+/** A JSON file's contents, or `undefined` when it is missing or unreadable. */
+function readJsonOrUndefined(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `resourceSourcesOfOtherFlows`, keyed lower-case: folder names keep their
+ * case, claims must not. The first file to claim a source wins, as there.
+ */
+function sourcesOfOtherFlows(dir, self) {
+    const users = new Map();
+    for (const [src, f] of resourceSourcesOfOtherFlows(dir, self)) {
+        if (!users.has(src.toLowerCase()))
+            users.set(src.toLowerCase(), f);
+    }
+    return users;
+}
+/**
+ * Copy agent folder `from` into `to`, for an agent re-homed off a folder another
+ * flow owns. Skipped: the top-level `agent.json` (compile writes its own, with
+ * the new identity), any `resources/<id>/` whose id is not in `referenced`, any
+ * file already present in `to`, and anything that is not a plain file or
+ * folder. Returns how many files were copied; a missing `from` copies nothing.
+ */
+function seedFolder(from, to, referenced) {
+    let copied = 0;
+    const walk = (rel) => {
+        let entries;
+        try {
+            entries = readdirSync(join(from, rel), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const r = rel === '' ? e.name : join(rel, e.name);
+            if (rel === '' && e.name === 'agent.json')
+                continue;
+            if (rel === 'resources' && !referenced.has(e.name.toLowerCase()))
+                continue;
+            if (e.isDirectory()) {
+                walk(r);
+            }
+            else if (e.isFile() && !existsSync(join(to, r))) {
+                mkdirSync(dirname(join(to, r)), { recursive: true });
+                copyFileSync(join(from, r), join(to, r));
+                copied++;
+            }
+        }
+    };
+    walk('');
+    return copied;
+}

package/dist/project-resource-users.d.ts

@@ -7,3 +7,11 @@
  * nothing.
  */
 export declare function resourceSourcesOfOtherFlows(dir: string, self: string): Map<string, string>;
+/**
+ * Every `inputs.source` string a flow's nodes name — agent folders and agent
+ * resource ids alike — root scope and subflow bodies, in the case the file
+ * spells them. A malformed flow yields nothing. The one walk both
+ * {@link resourceSourcesOfOtherFlows} and compile's own-flow checks use, so the
+ * two cannot disagree on where a node keeps its source.
+ */
+export declare function flowSources(flow: unknown): string[];

package/dist/project-resource-users.js

@@ -31,17 +31,31 @@ export function resourceSourcesOfOtherFlows(dir, self) {
         catch {
             continue;
         }
-        const walk = (scope) => {
-            const s = scope;
-            for (const n of Array.isArray(s?.nodes) ? s.nodes : []) {
-                const src = n?.inputs?.source;
-                if (typeof src === 'string' && !users.has(src))
-                    users.set(src, f);
-            }
-            if (s?.subflows && typeof s.subflows === 'object')
-                Object.values(s.subflows).forEach(walk);
-        };
-        walk(flow);
+        for (const src of flowSources(flow))
+            if (!users.has(src))
+                users.set(src, f);
     }
     return users;
 }
+/**
+ * Every `inputs.source` string a flow's nodes name — agent folders and agent
+ * resource ids alike — root scope and subflow bodies, in the case the file
+ * spells them. A malformed flow yields nothing. The one walk both
+ * {@link resourceSourcesOfOtherFlows} and compile's own-flow checks use, so the
+ * two cannot disagree on where a node keeps its source.
+ */
+export function flowSources(flow) {
+    const ids = [];
+    const walk = (scope) => {
+        const s = scope;
+        for (const n of Array.isArray(s?.nodes) ? s.nodes : []) {
+            const src = n?.inputs?.source;
+            if (typeof src === 'string')
+                ids.push(src);
+        }
+        if (s?.subflows && typeof s.subflows === 'object')
+            Object.values(s.subflows).forEach(walk);
+    };
+    walk(flow);
+    return ids;
+}

package/dist/serialize.d.ts

@@ -99,6 +99,18 @@ export interface SerializeOpts {
         path: string;
         json: unknown;
     }>;
+    /**
+     * Maps an agent's folder uuid (its `source`) to the one this compile writes,
+     * given the step's name. `compile-cli` passes it when the `source` a step
+     * carries already belongs to ANOTHER `.flow` in the same Flow project (#1184):
+     * decompile keeps a canvas agent's `source`, so compiling that source to a
+     * second `.flow` would otherwise write into the first flow's folder. The uuid
+     * returned is spent everywhere the `source` is: the node's `inputs.source`,
+     * the `agent.json` identity, and every sidecar path.
+     *
+     * @internal
+     */
+    agentSource?: (source: string, step: string) => string;
 }
 /**
  * `serialize`, plus the extra files the flow needs on disk beside it.

package/dist/serialize.js

@@ -4335,6 +4335,17 @@ export function serialize(built, opts = {}) {
      * gets them and one that does not is unaffected.
      */
     const sidecars = opts.sidecars ?? [];
+    /**
+     * An agent step's folder uuid (`source`): the one the step carries, else one
+     * derived from the flow id + step name rather than random, so a recompile is
+     * byte-identical — a v4-shaped uuid over a stable hash, because the platform
+     * treats it as an opaque id and the designer shows it as a folder. Then
+     * `opts.agentSource` may move it to a folder this flow owns (#1184).
+     */
+    const agentFolder = (carried, stepName) => {
+        const source = carried ?? fnv1aX4Uuid(`${built.id}/${stepName}`);
+        return opts.agentSource ? opts.agentSource(source, stepName) : source;
+    };
     const subflows = {};
     const rootGlobals = emittableGlobals(built, `flow "${built.id}"`);
     const root = newScope(rootGlobals.outputs, rootGlobals.vars, rootGlobals.backing, rootGlobals.backingReads);
@@ -5146,11 +5157,8 @@ export function serialize(built, opts = {}) {
                         : `Drop { version: '${version}' } to use ${INLINE_AGENT_DEFAULT_VERSION}, or drop \`memory\`.`));
             }
             const id = stepUid(scope, step.name);
-            // `source` is the agent's directory name. Derived from the flow id + step
-            // name rather than random so a recompile is byte-identical — a v4-shaped uuid
-            // over a stable hash, because the platform treats it as an opaque id and the
-            // designer shows it as a folder.
-            const source = s.source ?? fnv1aX4Uuid(`${built.id}/${step.name}`);
+            // `source` is the agent's directory name; see `agentFolder`.
+            const source = agentFolder(s.source, step.name);
             const node = makeNode(def.nodeType, id, step.name, { parentId, requestedVersion: step.options?.version, def });
             // Unlike the published families the inline agent KEEPS no node-level model:
             // 29 of 29 deployed instances carry none (the def's `model.source: true` is
@@ -5706,7 +5714,7 @@ export function serialize(built, opts = {}) {
             // lets the platform do that translation.
             const s = spec.inputs;
             const id = stepUid(scope, step.name);
-            const source = s.source ?? fnv1aX4Uuid(`${built.id}/${step.name}`);
+            const source = agentFolder(s.source, step.name);
             const node = makeNode(NODE_TYPE.conversationalAgent, id, step.name, { parentId, requestedVersion: step.options?.version });
             delete node.model;
             const st = s.settings ?? {};
@@ -5799,7 +5807,7 @@ export function serialize(built, opts = {}) {
             // definition declares what comes back.
             const s = spec.inputs;
             const id = stepUid(scope, step.name);
-            const source = s.source ?? fnv1aX4Uuid(`${built.id}/${step.name}`);
+            const source = agentFolder(s.source, step.name);
             const node = makeNode(NODE_TYPE.voiceAgent, id, step.name, { parentId, requestedVersion: step.options?.version });
             // Same rule as the inline agent's: the resource model lives on the
             // definition (its `model.source: true` is what makes `source` an input).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.31.5",
+  "version": "6.31.6",
   "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": "19700f105da9eae840ec05cd3796c28a96f1a4ed"
+  "gitref": "77c2e7b1f09268cc94ee0f4b8f9d4ae80ba625ee"
 }