@uipath/maestro-builder-sdk 6.16.13 → 6.17.0

package/dist/registry/uip/client.js

@@ -1,28 +1,30 @@
-/**
- * Running `uip`, and standing in for it.
- *
- * Everything in the registry that talks to the tenant goes through a
- * {@link UipClient}. The real one spawns the CLI with a timeout and UTF-8
- * decoding. The replay one serves envelopes captured earlier, keyed by the
- * exact argv, and fails loudly on a call nobody recorded — which is how prepare
- * and the library builder are tested without a tenant, and how the same
- * recording drives a byte-for-byte comparison against the Python they replace.
- *
- * Nothing here judges the response. Whether a non-zero exit is fatal, or a
- * `Result: Failure` envelope should be cached, is the caller's rule — the
- * Python callers disagreed with each other on purpose, and those rules stay
- * beside the call sites that own them.
- */
-import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { mkdirSync, readFileSync, existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import { join } from "node:path";
+import { writeJsonFile } from "../../core/json-file.js";
+import { HostUipClient } from "./host.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
  * child that exceeds even this is killed, which is what `execFile` did too.
  */
 const MAX_OUTPUT_BYTES = 256 * 1024 * 1024;
+let childProcessModule;
+/**
+ * `node:child_process`, loaded on first use. `bpmn/registry-fallback.ts` imports this
+ * module, so the `/bpmn` and root builder entries reach it; a builder import must not
+ * load a process API it may never use (FB009). The specifier stays a literal so the
+ * architecture lint sees the edge.
+ */
+function childProcess() {
+    return (childProcessModule ??= createRequire(import.meta.url)("node:child_process"));
+}
+/** The error for a `uip` that is not there: what to install, not just ENOENT. */
+function cannotStart(executable, error) {
+    return new Error(`Could not start ${executable}: ${error.message}. The registry verbs call the ` +
+        "UiPath CLI; install it and log in, or put it on PATH.");
+}
 /** The real thing: spawn the CLI, capture both streams, never throw on a non-zero exit. */
 export class SpawnUipClient {
     defaults;
@@ -40,7 +42,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 = spawn(executable, args, {
+            const child = childProcess().spawn(executable, args, {
                 cwd: options.cwd ?? this.defaults.cwd,
                 stdio: ["ignore", "pipe", "pipe"],
             });
@@ -70,8 +72,7 @@ export class SpawnUipClient {
                 if (timer !== undefined)
                     clearTimeout(timer);
                 if (error.code === "ENOENT") {
-                    reject(new Error(`Could not start ${executable}: ${error.message}. The registry verbs call the ` +
-                        "UiPath CLI; install it and log in, or put it on PATH."));
+                    reject(cannotStart(executable, error));
                     return;
                 }
                 // Every other spawn failure — EACCES on the binary, EAGAIN with no
@@ -118,6 +119,21 @@ export function recordingName(argv) {
         .slice(0, 60);
     return `${slug}-${digest}.json`;
 }
+/** The recording for `argv` in `directory`; throws, naming the argv and the file, when there is none. */
+function readRecording(directory, argv) {
+    const path = join(directory, recordingName(argv));
+    if (!existsSync(path)) {
+        throw new Error(`ReplayUipClient: no recording for\n  ${argv.join(" ")}\n(expected ${path}). ` +
+            "Record it with RecordingUipClient, or the call is one the code under test should not make. " +
+            "A build replays only when UIP_REPLAY_DIR is set; if that was not intended, unset it.");
+    }
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+/** Write `result` down as the recording for `argv` in `directory`. */
+function writeRecording(directory, argv, result) {
+    mkdirSync(directory, { recursive: true });
+    writeJsonFile(join(directory, recordingName(argv)), { argv: [...argv], result });
+}
 /**
  * Serve recorded results; refuse anything unrecorded.
  *
@@ -134,13 +150,7 @@ export class ReplayUipClient {
         const name = recordingName(argv);
         let recording = this.byName.get(name);
         if (!recording) {
-            const path = join(this.directory, name);
-            if (!existsSync(path)) {
-                throw new Error(`ReplayUipClient: no recording for\n  ${argv.join(" ")}\n(expected ${path}). ` +
-                    "Record it with RecordingUipClient, or the call is one the code under test should not make. " +
-                    "A build replays only when UIP_REPLAY_DIR is set; if that was not intended, unset it.");
-            }
-            recording = JSON.parse(readFileSync(path, "utf8"));
+            recording = readRecording(this.directory, argv);
             this.byName.set(name, recording);
         }
         return { ...recording.result };
@@ -157,10 +167,12 @@ export class RecordingUipClient {
     }
     async run(argv, options) {
         const result = await this.inner.run(argv, options);
-        const recording = { argv: [...argv], result };
-        writeFileSync(join(this.directory, recordingName(argv)), `${JSON.stringify(recording, null, 2)}\n`);
+        writeRecording(this.directory, argv, result);
         return result;
     }
+    close() {
+        this.inner.close?.();
+    }
 }
 /**
  * A client that runs nothing and reports every call as refused.
@@ -213,14 +225,63 @@ export class OfflineUipClient {
  *
  * Both exist to capture a fixture from a real tenant and to replay one — that
  * is how `fixtures/library-build/` was taken — and neither is meant to be set
- * in a pipeline. They are read here and nowhere else, so this is the only place
- * an operator can be told what they do.
+ * in a pipeline. They are read by `uipSwitches()` here, for this and
+ * {@link runUipSync}, and nowhere else, so this is the only place an operator can
+ * be told what they do.
+ *
+ * A third, `FLOW_SDK_UIP_HOST=0`, turns off the one-process host a caller may
+ * ask for with `host` (see `host.ts`): every call then spawns its own `uip`,
+ * which is how the registry ran before flow-builder-sdk#965 and the shape to
+ * compare against when a prepare misbehaves.
  */
 export function defaultUipClient(options = {}) {
-    const replay = process.env.UIP_REPLAY_DIR;
+    const { replay, record } = uipSwitches();
     if (replay)
         return new ReplayUipClient(replay);
-    const client = new SpawnUipClient(options);
-    const record = process.env.UIP_RECORD_DIR;
+    const { host, ...runOptions } = options;
+    const spawning = new SpawnUipClient(runOptions);
+    // One `uip mcp serve` for the command's whole chain of calls, where the
+    // caller asked for it and the operator has not switched it off. Serial, so
+    // not for the library builder, whose `concurrency` runs calls side by side.
+    const client = host && process.env.FLOW_SDK_UIP_HOST !== "0"
+        ? new HostUipClient(spawning, typeof host === "object" ? host : {})
+        : spawning;
     return record ? new RecordingUipClient(client, record) : client;
 }
+/** The replay and record switches (see {@link defaultUipClient}); an empty value is unset. */
+function uipSwitches() {
+    return { replay: process.env.UIP_REPLAY_DIR || undefined, record: process.env.UIP_RECORD_DIR || undefined };
+}
+/**
+ * Run `uip` synchronously, for the one caller that cannot await:
+ * `bpmn/registry-fallback.ts` resolves an extension type while a builder method runs.
+ * Same switches as {@link defaultUipClient} (`UIP_REPLAY_DIR` answers from recordings and
+ * throws on an unrecorded call; `UIP_RECORD_DIR` writes each result down) and the same
+ * contract as {@link SpawnUipClient}: no stdin, a non-zero exit or a timeout is a result,
+ * a missing executable throws the install instruction.
+ */
+export function runUipSync(argv, options = {}) {
+    const { replay, record } = uipSwitches();
+    if (replay)
+        return { ...readRecording(replay, argv).result };
+    const [executable, ...args] = argv;
+    const r = childProcess().spawnSync(executable, args, {
+        cwd: options.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf8",
+        timeout: options.timeoutMs,
+        killSignal: "SIGKILL",
+        maxBuffer: MAX_OUTPUT_BYTES,
+    });
+    const errno = r.error?.code;
+    if (errno === "ENOENT")
+        throw cannotStart(executable, r.error);
+    if (r.error && errno !== "ETIMEDOUT" && errno !== "ENOBUFS")
+        throw r.error;
+    const result = {
+        code: r.status, signal: r.signal, stdout: r.stdout ?? "", stderr: r.stderr ?? "", timedOut: errno === "ETIMEDOUT",
+    };
+    if (record)
+        writeRecording(record, argv, result);
+    return result;
+}

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

@@ -0,0 +1,41 @@
+import type { UipClient, UipResult, UipRunOptions } from "./client.js";
+/** The MCP tool this client calls; a server without it is treated as absent. */
+export declare const HOST_TOOL = "run_argv";
+export interface HostUipClientOptions {
+    /**
+     * The command that starts the host for `executable` (`argv[0]`, normally
+     * `uip`). Defaults to `[executable, "mcp", "serve"]`; tests point it at a
+     * fake server.
+     */
+    hostCommand?: (executable: string) => string[];
+    startTimeoutMs?: number;
+    /** Where to say why the host was given up on; silent by default. */
+    onFallback?: (reason: string) => void;
+}
+/**
+ * Run `uip` calls through one `uip mcp serve` process, falling back to
+ * `fallback` (the spawning client) whenever the host cannot serve a call.
+ */
+export declare class HostUipClient implements UipClient {
+    private readonly fallback;
+    private readonly options;
+    private host;
+    private starting;
+    private disabled;
+    private queue;
+    constructor(fallback: UipClient, options?: HostUipClientOptions);
+    run(argv: readonly string[], options?: UipRunOptions): Promise<UipResult>;
+    /** Shut the host down. Calls still in flight finish first; later calls start a new one. */
+    close(): void;
+    private runSerially;
+    private ensureHost;
+    private start;
+    /**
+     * Spawn per call from here on, silently. This is the path for a CLI whose
+     * server predates `run_argv`: a prepare on it works exactly as it did
+     * before this client existed, so there is nothing to tell the user.
+     */
+    private spawnFromNowOn;
+    /** Spawn per call from here on, and say why: the host failed. */
+    private giveUp;
+}

package/dist/registry/uip/host.js

@@ -0,0 +1,312 @@
+import { createRequire } from "node:module";
+/** 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. */
+const DEFAULT_START_TIMEOUT_MS = 20_000;
+/** Stderr the host printed, kept for the message when it dies. */
+const STDERR_KEEP = 4_000;
+/** Thrown inside the client when a call's timeout elapsed; never escapes `run`. */
+class HostTimeout extends Error {
+}
+/** Thrown inside the client when the host or its protocol failed; never escapes `run`. */
+class HostFailure extends Error {
+}
+/**
+ * `ref`/`unref` a child's stdio pipe. The streams are typed as plain
+ * `Readable`/`Writable`, but a piped stdio stream is a `net.Socket`, which
+ * has both; a stream without them (a test's fake) is simply left alone.
+ */
+function refStream(stream, on) {
+    const socket = stream;
+    if (!socket)
+        return;
+    if (on)
+        socket.ref?.();
+    else
+        socket.unref?.();
+}
+/** A live `uip mcp serve` process and the JSON-RPC conversation with it. */
+class Host {
+    child;
+    pending = new Map();
+    nextId = 1;
+    buffer = "";
+    stderr = "";
+    closed = false;
+    /** Set when the client killed the host on purpose, so `close` is not a failure. */
+    killedForTimeout = false;
+    exitHook;
+    constructor(child) {
+        this.child = child;
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => this.onData(chunk));
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            this.stderr = (this.stderr + chunk).slice(-STDERR_KEEP);
+        });
+        child.on("error", (error) => this.fail(new HostFailure(`uip mcp serve: ${error.message}`)));
+        child.on("close", (code, signal) => {
+            this.closed = true;
+            process.removeListener("exit", this.exitHook);
+            const why = this.killedForTimeout
+                ? new HostTimeout("killed after a call's timeout")
+                : new HostFailure(`uip mcp serve exited (code ${code}, signal ${signal})` + (this.stderr.trim() ? `: ${this.stderr.trim()}` : ""));
+            this.fail(why);
+        });
+        // stdin is written only by us; an error there (EPIPE after the server
+        // died) is reported through `close`, not as an unhandled event.
+        child.stdin.on("error", () => undefined);
+        this.exitHook = () => {
+            if (!this.closed)
+                child.kill("SIGKILL");
+        };
+        process.once("exit", this.exitHook);
+        this.idle();
+    }
+    get alive() {
+        return !this.closed;
+    }
+    /**
+     * Let the SDK process exit while the host sits idle: with nothing in
+     * flight nothing here holds the event loop, and when the parent exits the
+     * server reads EOF on its stdin and shuts down. A call in flight `ref`s the
+     * pipes again, so the loop waits for its answer.
+     */
+    idle() {
+        this.child.unref();
+        for (const stream of [this.child.stdout, this.child.stderr, this.child.stdin])
+            refStream(stream, false);
+    }
+    busy() {
+        this.child.ref();
+        for (const stream of [this.child.stdout, this.child.stderr, this.child.stdin])
+            refStream(stream, true);
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        let newline = this.buffer.indexOf("\n");
+        while (newline >= 0) {
+            const line = this.buffer.slice(0, newline).trim();
+            this.buffer = this.buffer.slice(newline + 1);
+            if (line !== "")
+                this.onLine(line);
+            newline = this.buffer.indexOf("\n");
+        }
+    }
+    onLine(line) {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            // Something other than JSON-RPC on the server's stdout — a command that
+            // wrote to the real stream instead of its sink. The framing is broken
+            // from here on, so every call in flight fails and the client falls back.
+            this.fail(new HostFailure(`uip mcp serve wrote something other than JSON-RPC: ${line.slice(0, 200)}`));
+            return;
+        }
+        // A notification has no id; a server-to-client REQUEST (`ping`) has an id
+        // of its own numbering and a `method`. Neither is an answer to us, and a
+        // request whose id happened to equal a pending call's would otherwise be
+        // read as that call's reply and fail it.
+        if (typeof message.id !== "number" || "method" in message)
+            return;
+        const waiting = this.pending.get(message.id);
+        if (!waiting)
+            return;
+        this.pending.delete(message.id);
+        if (this.pending.size === 0)
+            this.idle();
+        waiting.resolve(message);
+    }
+    /** Reject every call in flight; later calls find `alive` false. */
+    fail(error) {
+        const waiting = [...this.pending.values()];
+        this.pending.clear();
+        this.idle();
+        for (const entry of waiting)
+            entry.reject(error);
+    }
+    notify(method, params) {
+        this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+    }
+    request(method, params, timeoutMs) {
+        if (this.closed)
+            return Promise.reject(new HostFailure("uip mcp serve is not running"));
+        const id = this.nextId++;
+        this.busy();
+        return new Promise((resolve, reject) => {
+            let timer;
+            const settle = (fn) => (value) => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                fn(value);
+            };
+            this.pending.set(id, { resolve: settle(resolve), reject: settle(reject) });
+            if (timeoutMs !== undefined && timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    // A command cannot be cancelled inside the host, so the host goes.
+                    // `close` then fails this call with the timeout the flag records.
+                    this.killedForTimeout = true;
+                    this.child.kill("SIGKILL");
+                }, timeoutMs);
+            }
+            this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+        });
+    }
+    /** End the conversation: the server treats stdin EOF as shutdown. */
+    close() {
+        process.removeListener("exit", this.exitHook);
+        if (this.closed)
+            return;
+        this.child.stdin.end();
+        // If it ignores EOF, it does not get to outlive the command.
+        const grace = setTimeout(() => {
+            if (!this.closed)
+                this.child.kill("SIGKILL");
+        }, 2_000);
+        grace.unref();
+    }
+    kill() {
+        process.removeListener("exit", this.exitHook);
+        if (!this.closed)
+            this.child.kill("SIGKILL");
+    }
+}
+/**
+ * Run `uip` calls through one `uip mcp serve` process, falling back to
+ * `fallback` (the spawning client) whenever the host cannot serve a call.
+ */
+export class HostUipClient {
+    fallback;
+    options;
+    host;
+    starting;
+    disabled = false;
+    queue = Promise.resolve();
+    constructor(fallback, options = {}) {
+        this.fallback = fallback;
+        this.options = options;
+    }
+    run(argv, options = {}) {
+        if (this.disabled || options.cwd !== undefined)
+            return this.fallback.run(argv, options);
+        const task = this.queue.then(() => this.runSerially(argv, options));
+        this.queue = task.then(() => undefined, () => undefined);
+        return task;
+    }
+    /** Shut the host down. Calls still in flight finish first; later calls start a new one. */
+    close() {
+        const host = this.host;
+        this.host = undefined;
+        if (host)
+            this.queue.then(() => host.close(), () => host.close());
+    }
+    async runSerially(argv, options) {
+        if (this.disabled)
+            return this.fallback.run(argv, options);
+        const host = await this.ensureHost(argv[0]);
+        if (!host)
+            return this.fallback.run(argv, options);
+        try {
+            const response = await host.request("tools/call", { name: HOST_TOOL, arguments: { args: argv.slice(1) } }, options.timeoutMs);
+            return toResult(response);
+        }
+        catch (error) {
+            if (error instanceof HostTimeout) {
+                this.host = undefined;
+                return { code: null, signal: "SIGKILL", stdout: "", stderr: "", timedOut: true };
+            }
+            this.giveUp(error instanceof Error ? error.message : String(error));
+            return this.fallback.run(argv, options);
+        }
+    }
+    async ensureHost(executable) {
+        if (this.host?.alive)
+            return this.host;
+        this.host = undefined;
+        if (!this.starting) {
+            this.starting = this.start(executable).finally(() => {
+                this.starting = undefined;
+            });
+        }
+        return this.starting;
+    }
+    async start(executable) {
+        const command = (this.options.hostCommand ?? ((exe) => [exe, "mcp", "serve"]))(executable);
+        const startTimeoutMs = this.options.startTimeoutMs ?? DEFAULT_START_TIMEOUT_MS;
+        let child;
+        try {
+            // Loaded here, not at import: `client.ts` imports this module and the builder
+            // 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"] });
+        }
+        catch (error) {
+            this.giveUp(`could not start ${command.join(" ")}: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+        const host = new Host(child);
+        try {
+            const initialized = await host.request("initialize", {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "maestro-builder-sdk", version: "0" },
+            }, startTimeoutMs);
+            if (initialized.error)
+                throw new HostFailure(`initialize failed: ${initialized.error.message ?? "unknown error"}`);
+            host.notify("notifications/initialized");
+            const listed = await host.request("tools/list", {}, startTimeoutMs);
+            const tools = listed.result?.tools ?? [];
+            if (!tools.some((tool) => tool.name === HOST_TOOL)) {
+                // An older CLI, not a fault: spawn per call, and say nothing.
+                host.close();
+                this.spawnFromNowOn();
+                return undefined;
+            }
+        }
+        catch (error) {
+            host.kill();
+            this.giveUp(error instanceof HostTimeout
+                ? `uip mcp serve did not answer within ${startTimeoutMs} ms`
+                : error instanceof Error
+                    ? error.message
+                    : String(error));
+            return undefined;
+        }
+        this.host = host;
+        return host;
+    }
+    /**
+     * Spawn per call from here on, silently. This is the path for a CLI whose
+     * server predates `run_argv`: a prepare on it works exactly as it did
+     * before this client existed, so there is nothing to tell the user.
+     */
+    spawnFromNowOn() {
+        this.disabled = true;
+        this.host?.kill();
+        this.host = undefined;
+    }
+    /** Spawn per call from here on, and say why: the host failed. */
+    giveUp(reason) {
+        if (this.disabled)
+            return;
+        this.spawnFromNowOn();
+        this.options.onFallback?.(`uip host unavailable, spawning each call instead: ${reason}`);
+    }
+}
+/** The tool's structured answer as the result every caller already reads. */
+function toResult(response) {
+    if (response.error)
+        throw new HostFailure(`${HOST_TOOL} failed: ${response.error.message ?? "unknown error"}`);
+    const result = response.result;
+    const structured = result?.structuredContent;
+    if (structured === undefined ||
+        typeof structured.stdout !== "string" ||
+        typeof structured.stderr !== "string" ||
+        typeof structured.exitCode !== "number") {
+        throw new HostFailure(`${HOST_TOOL} answered without stdout/stderr/exitCode`);
+    }
+    return { code: structured.exitCode, signal: null, stdout: structured.stdout, stderr: structured.stderr, timedOut: false };
+}

package/dist/serialize.d.ts

@@ -1,3 +1,4 @@
+import type { DefinitionReference } from './core/node-classes.js';
 import type { BuiltFlow } from './flow-sdk.js';
 import type { Library } from './library.js';
 import type { Bindings } from './bindings.js';
@@ -87,6 +88,12 @@ export declare function serializeWithSidecars(built: BuiltFlow, opts?: Serialize
         json: unknown;
     }>;
 };
+/**
+ * Resolve a contribution's {@link DefinitionReference} to a concrete manifest —
+ * exactly (design §2.6/§4.2): the named version resolves or compilation fails,
+ * and a contributor that ignored the author's requested version is rejected.
+ */
+export declare function resolveContributionDefinition(ref: DefinitionReference, requestedVersion: string | undefined, where: string): any;
 export declare function serialize(built: BuiltFlow, opts?: SerializeOpts): any;
 /**
  * Every node `configuration` that carries Studio Web's split envelope must be