@uipath/maestro-builder-sdk 6.18.7 → 6.18.9

package/dist/registry/pull-cli.d.ts

@@ -20,4 +20,25 @@ export declare const CONNECTORS_LIBRARY_VERSION_ENV = "CONNECTORS_LIBRARY_VERSIO
  * rather than guessed at, so a typo cannot fall back to "latest" silently.
  */
 export declare function connectorsLibraryUrl(argv: string[], env?: Record<string, string | undefined>): string;
+/**
+ * Point `current` at an entry, replacing whatever it named.
+ *
+ * Nothing to do when `current` already resolves to the entry — the unchanged
+ * pull, which is most of them.
+ *
+ * Otherwise the new link is made under a temp name and renamed over `current`.
+ * On POSIX that rename is atomic over an existing symlink, so a concurrent
+ * compile never finds the link missing. On Windows `current` is a junction, and
+ * a rename onto an existing junction fails with `EPERM` (flow-builder-sdk#945),
+ * so there the old link is parked under `current.old-<pid>` first, the new one
+ * renamed in, and the parked one removed; a failed rename puts the parked link
+ * back. That leaves a moment where `current` does not exist, which Windows
+ * gives no way to avoid with a junction.
+ *
+ * Links are removed with `unlink`, never a recursive `rm`: the link's target is
+ * the extracted library, and removing the link must not reach into it.
+ *
+ * @param platform - Which branch to take; a parameter so both run in tests.
+ */
+export declare function pointCurrentAt(root: string, sha256: string, platform?: NodeJS.Platform): Promise<void>;
 export declare function run(argv: string[]): Promise<number>;

package/dist/registry/pull-cli.js

@@ -1,6 +1,6 @@
 import { reportResult } from '../cli-result.js';
 import { createHash } from "node:crypto";
-import { mkdir, readFile, rename, rm, stat, symlink, writeFile, } from "node:fs/promises";
+import { mkdir, readFile, realpath, rename, rm, stat, symlink, unlink, writeFile, } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { writeJsonFile } from "../core/json-file.js";
 import { CURRENT_LINK, LIBRARY_JSON_DIR, LIBRARY_MARKDOWN_DIR, cacheEntry, libraryCacheRoot, referencedConnectorKeys, } from "../core/library-cache.js";
@@ -215,16 +215,81 @@ async function writeSource(libraryPath, archive, sha256, archiveSha256, overlayS
 /**
  * Point `current` at an entry, replacing whatever it named.
  *
- * Written to a temp name and renamed, so a reader never sees the link missing —
- * `rename` over an existing symlink is atomic, while unlink-then-create leaves a
- * window where a concurrent compile finds nothing.
+ * Nothing to do when `current` already resolves to the entry — the unchanged
+ * pull, which is most of them.
+ *
+ * Otherwise the new link is made under a temp name and renamed over `current`.
+ * On POSIX that rename is atomic over an existing symlink, so a concurrent
+ * compile never finds the link missing. On Windows `current` is a junction, and
+ * a rename onto an existing junction fails with `EPERM` (flow-builder-sdk#945),
+ * so there the old link is parked under `current.old-<pid>` first, the new one
+ * renamed in, and the parked one removed; a failed rename puts the parked link
+ * back. That leaves a moment where `current` does not exist, which Windows
+ * gives no way to avoid with a junction.
+ *
+ * Links are removed with `unlink`, never a recursive `rm`: the link's target is
+ * the extracted library, and removing the link must not reach into it.
+ *
+ * @param platform - Which branch to take; a parameter so both run in tests.
  */
-async function pointCurrentAt(root, sha256) {
+export async function pointCurrentAt(root, sha256, platform = process.platform) {
     const link = join(root, CURRENT_LINK);
+    if (await resolvesTo(link, join(root, sha256)))
+        return;
     const temporary = `${link}.tmp-${process.pid}`;
-    await rm(temporary, { recursive: true, force: true });
-    await symlink(sha256, temporary, "junction");
-    await rename(temporary, link);
+    await removeLink(temporary);
+    try {
+        await symlink(sha256, temporary, "junction");
+        if (platform !== "win32") {
+            await rename(temporary, link);
+            return;
+        }
+        const parked = `${link}.old-${process.pid}`;
+        await removeLink(parked);
+        let wasParked = false;
+        try {
+            await rename(link, parked);
+            wasParked = true;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        try {
+            await rename(temporary, link);
+        }
+        catch (error) {
+            if (wasParked)
+                await rename(parked, link).catch(() => undefined);
+            throw error;
+        }
+        if (wasParked)
+            await removeLink(parked);
+    }
+    finally {
+        // Gone already after a successful rename; this is for every way out that
+        // is not one, so a failed pull leaves no `current.tmp-<pid>` behind.
+        await removeLink(temporary);
+    }
+}
+/** Whether `link` and `entry` name the same directory; false when either is missing. */
+async function resolvesTo(link, entry) {
+    try {
+        return (await realpath(link)) === (await realpath(entry));
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove a symlink or junction without following it; a missing one is fine. */
+async function removeLink(path) {
+    try {
+        await unlink(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
 }
 export async function run(argv) {
     if (has(argv, "--help") || has(argv, "-h")) {

package/dist/registry/uip/client.js

@@ -4,6 +4,7 @@ import { createRequire } from "node:module";
 import { join } from "node:path";
 import { writeJsonFile } from "../../core/json-file.js";
 import { HostUipClient } from "./host.js";
+import { launchFor } from "./launch.js";
 /**
  * Room for the largest `registry search` a tenant has answered, with margin.
  * `execFile`'s 1 MiB default cut that stream off, so the port raised it; a
@@ -35,6 +36,9 @@ export class SpawnUipClient {
         const [executable, ...args] = argv;
         const timeoutMs = options.timeoutMs ?? this.defaults.timeoutMs;
         return new Promise((resolve, reject) => {
+            // `uip` stays the logical name in argv (recordings are keyed by it);
+            // only here is it turned into what Windows can start (launch.ts, #940).
+            const launch = launchFor(executable, args);
             // stdin is `ignore`, not the default pipe. A pipe this process never
             // writes to stays open, so a `uip` that decides to prompt — an expired
             // login, a consent question — would block on it for as long as the
@@ -42,7 +46,7 @@ export class SpawnUipClient {
             // reads EOF at once and the CLI fails like any other call, which is
             // what Python's `subprocess.run` gave it: the parent's stdin, already at
             // EOF on an agent.
-            const child = childProcess().spawn(executable, args, {
+            const child = childProcess().spawn(launch.file, launch.args, {
                 cwd: options.cwd ?? this.defaults.cwd,
                 stdio: ["ignore", "pipe", "pipe"],
             });
@@ -265,7 +269,8 @@ export function runUipSync(argv, options = {}) {
     if (replay)
         return { ...readRecording(replay, argv).result };
     const [executable, ...args] = argv;
-    const r = childProcess().spawnSync(executable, args, {
+    const launch = launchFor(executable, args);
+    const r = childProcess().spawnSync(launch.file, launch.args, {
         cwd: options.cwd,
         stdio: ["ignore", "pipe", "pipe"],
         encoding: "utf8",

package/dist/registry/uip/host.js

@@ -1,4 +1,5 @@
 import { createRequire } from "node:module";
+import { launchFor } from "./launch.js";
 /** The MCP tool this client calls; a server without it is treated as absent. */
 export const HOST_TOOL = "run_argv";
 /** How long the host may take to start and list its tools before the client gives up on it. */
@@ -241,7 +242,8 @@ export class HostUipClient {
             // entries reach `client.ts`, so a static import would load a process API on
             // every builder import (FB009).
             const { spawn } = createRequire(import.meta.url)("node:child_process");
-            child = spawn(command[0], command.slice(1), { stdio: ["pipe", "pipe", "pipe"] });
+            const launch = launchFor(command[0], command.slice(1));
+            child = spawn(launch.file, launch.args, { stdio: ["pipe", "pipe", "pipe"] });
         }
         catch (error) {
             this.giveUp(`could not start ${command.join(" ")}: ${error instanceof Error ? error.message : String(error)}`);

package/dist/registry/uip/launch.d.ts

@@ -0,0 +1,24 @@
+export interface Launch {
+    file: string;
+    args: string[];
+}
+/** The parts of the host the lookup reads; injected so the Windows branch is testable anywhere. */
+export interface LaunchHost {
+    platform: NodeJS.Platform;
+    /** `PATH`, `;`-separated on Windows. */
+    path: string | undefined;
+    /** `PATHEXT`; cmd.exe's default when unset. */
+    pathExt: string | undefined;
+    /** The Node that runs a shim's script — this process's own. */
+    execPath: string;
+    isFile(path: string): boolean;
+    readFile(path: string): string;
+}
+/**
+ * The file and arguments to spawn for `executable args`, without a shell.
+ *
+ * @throws when, on Windows, the name resolves to a batch shim this cannot read
+ * a script out of — naming the shim, so the remedy is not "put uip on PATH"
+ * for a `uip` that is on PATH.
+ */
+export declare function launchFor(executable: string, args: readonly string[], host?: LaunchHost): Launch;

package/dist/registry/uip/launch.js

@@ -0,0 +1,105 @@
+/**
+ * What to actually spawn for a logical `uip` command line.
+ *
+ * Every argv in the registry starts with the bare name `uip` (`commands.ts`),
+ * and that name is what recordings are keyed by, so it stays bare everywhere
+ * above the spawn. On POSIX the bare name is also what `spawn` wants. On
+ * Windows it is not (flow-builder-sdk#940): npm installs the CLI as a `uip.cmd`
+ * shim (plus a POSIX `uip` script Windows cannot run), and Node starts neither
+ * without a shell — `uip` is `ENOENT`, and `uip.cmd` is `EINVAL` since the
+ * CVE-2024-27980 fix refused `.cmd`/`.bat` without `shell`.
+ *
+ * `shell: true` would start it, but every argument (`-f name=value`, a JSON
+ * value, a `|` in a JMESPath filter) would then go through cmd.exe quoting, and
+ * a timeout's `kill` would end cmd.exe and leave the CLI running. So on Windows
+ * a bare name is looked up on `PATH` the way cmd.exe would (`PATHEXT` order),
+ * and:
+ *   - an `.exe`/`.com` is spawned by its full path;
+ *   - a `.cmd`/`.bat` npm shim is read for the script it runs
+ *     (`"%dp0%\node_modules\@uipath\cli\dist\index.js" %*`), and that script is
+ *     run with this process's own Node, which is what the shim would do;
+ *   - a shim that names no script is an error that says so, not a guess.
+ * A name that is not bare (a path, or one with an extension) is spawned as
+ * given, and so is anything on another platform.
+ *
+ * Example, on Windows with npm's global bin on PATH:
+ *   launchFor("uip", ["--version"])
+ *   // -> { file: "C:\\Program Files\\nodejs\\node.exe",
+ *   //      args: ["C:\\Users\\me\\AppData\\Roaming\\npm\\node_modules\\@uipath\\cli\\dist\\index.js", "--version"] }
+ */
+import { readFileSync, statSync } from "node:fs";
+import { win32 } from "node:path";
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+/**
+ * The script an npm (`cmd-shim`) or pnpm shim hands its arguments to: the last
+ * quoted `%dp0%\…` / `%~dp0\…` path followed by `%*`. Only a JavaScript target
+ * counts; a shim around something else is not one this module can run directly.
+ */
+const SHIM_TARGET = /"%~?dp0%?\\([^"]+\.[cm]?js)"\s+%\*/g;
+function ambientHost() {
+    return {
+        platform: process.platform,
+        path: process.env.PATH,
+        pathExt: process.env.PATHEXT,
+        execPath: process.execPath,
+        isFile: (path) => {
+            try {
+                return statSync(path).isFile();
+            }
+            catch {
+                return false;
+            }
+        },
+        readFile: (path) => readFileSync(path, "utf8"),
+    };
+}
+/** True for a name `PATH` lookup applies to: no directory part and no extension. */
+function isBareName(executable) {
+    return executable !== "" && !/[\\/]/.test(executable) && win32.extname(executable) === "";
+}
+/** The first `<dir>\<executable><ext>` on PATH, in cmd.exe's order, or undefined. */
+function findOnPath(executable, host) {
+    const extensions = (host.pathExt || DEFAULT_PATHEXT).split(";").filter(Boolean);
+    for (const dir of (host.path ?? "").split(";")) {
+        const trimmed = dir.trim().replace(/^"(.*)"$/, "$1");
+        if (trimmed === "")
+            continue;
+        for (const ext of extensions) {
+            const candidate = win32.join(trimmed, executable + ext.toLowerCase());
+            if (host.isFile(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/** The script a `.cmd`/`.bat` shim runs, as an absolute path, or undefined. */
+function shimTarget(shim, host) {
+    const matches = [...host.readFile(shim).matchAll(SHIM_TARGET)];
+    const last = matches.at(-1);
+    return last ? win32.join(win32.dirname(shim), last[1]) : undefined;
+}
+/**
+ * The file and arguments to spawn for `executable args`, without a shell.
+ *
+ * @throws when, on Windows, the name resolves to a batch shim this cannot read
+ * a script out of — naming the shim, so the remedy is not "put uip on PATH"
+ * for a `uip` that is on PATH.
+ */
+export function launchFor(executable, args, host = ambientHost()) {
+    if (host.platform !== "win32" || !isBareName(executable))
+        return { file: executable, args: [...args] };
+    const found = findOnPath(executable, host);
+    // Not on PATH: spawn the bare name and let the ENOENT say so.
+    if (!found)
+        return { file: executable, args: [...args] };
+    const ext = win32.extname(found).toLowerCase();
+    if (ext !== ".cmd" && ext !== ".bat")
+        return { file: found, args: [...args] };
+    const script = shimTarget(found, host);
+    if (!script || !host.isFile(script)) {
+        throw new Error(`Could not start ${executable}: ${found} is a batch file, which Node cannot run without a shell, ` +
+            (script ? `and the script it names (${script}) does not exist.` : "and it names no JavaScript entry point to run instead.") +
+            " Reinstall the UiPath CLI with npm (`npm install -g @uipath/cli`).");
+    }
+    return { file: host.execPath, args: [script, ...args] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.18.7",
+  "version": "6.18.9",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "7dffe3f9de6568ee2673c38faa5046eb7c86eb54"
+  "gitref": "6f8e3c88230704c5b5bc0e8983be45ebedd135dc"
 }