@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

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

@@ -1,3 +1,4 @@
+import { type PrepareOptions, type PrepareReport } from "./prepare/pipeline.js";
 /**
  * Fetch one operation's connection-resolved schema into a local overlay.
  *
@@ -14,7 +15,9 @@
  *
  * Needs the `uip` CLI on PATH and logged in. The tenant calls go through it —
  * `uip maestro flow registry get`, `uip is resources list/describe` — because
- * `uip` is the tenant client and this only orchestrates it.
+ * `uip` is the tenant client and this only orchestrates it. No interpreter is
+ * involved: this used to spawn `prepare_connector.py`, and the port of that
+ * script lives in `prepare/`.
  */
 export interface PrepareConnectorOptions {
     connectorKey: string;
@@ -46,13 +49,21 @@ export interface PrepareConnectorOptions {
     source?: string;
     /** Print the import line instead of editing the source. */
     noSourceRewrite?: boolean;
+    /** @deprecated No interpreter is involved any more; accepted and ignored. */
     pythonExecutable?: string;
-    /** Override used by tests and source checkouts. */
+    /** @deprecated The pipeline is part of the package; accepted and ignored. */
     generatorPath?: string;
 }
-/** The generator's argv for these options. Exported to be tested directly. */
-export declare function generatorArgs(options: PrepareConnectorOptions): string[];
-export declare function prepareConnector(options: PrepareConnectorOptions): Promise<void>;
+/** This module's options as the pipeline's, which name three things differently. */
+export declare function pipelineOptions(options: PrepareConnectorOptions): PrepareOptions;
+/**
+ * Prepare one operation, reporting to the console.
+ *
+ * Kept as a one-argument function because it is the API a caller outside this
+ * package holds; `prepare/pipeline.ts` is where the work is, and it takes its
+ * `uip` client and reporter injected so tests replay recordings.
+ */
+export declare function prepareConnector(options: PrepareConnectorOptions): Promise<PrepareReport>;
 /**
  * Options for this argv, or null when it does not name a connector, an action
  * and a connection. Split out from `run` so the parsing can be tested without

package/dist/registry/prepare-cli.js

@@ -1,5 +1,9 @@
-import { packagedGenerator, runGenerator } from "./python.js";
 import { PACKAGE_NAME } from "../package-name.js";
+import { exitCodeOf } from "./errors.js";
+import { exitText } from "./prepare/messages.js";
+import { prepareConnector as runPipeline } from "./prepare/pipeline.js";
+import { consoleReporter } from "./reporter.js";
+import { defaultUipClient } from "./uip/client.js";
 // This mirrors the generator's own flags one for one, so a `--version` here is
 // the connector's version, not the package's. The umbrella CLI spells that
 // `--connector-version`, because commander's program-level version option
@@ -14,58 +18,45 @@ const USAGE = [
     "                                [--resolve FIELD:BY=VALUE ...] [--refresh-lookups]",
     "                                [--out <dir>] [--version <v>] [--import <specifier>]",
     "                                [--json-only] [--source <flow.ts>] [--no-source-rewrite]",
-    "                                [--python <exe>]",
+    "                                [--python <exe>]   (accepted and ignored)",
 ].join("\n");
-/** The generator's argv for these options. Exported to be tested directly. */
-export function generatorArgs(options) {
-    const args = [options.connectorKey, options.action];
-    if (options.connectionId)
-        args.push("--connection-id", options.connectionId);
-    if (options.connection)
-        args.push("--connection", options.connection);
-    if (options.bindings)
-        args.push("--bindings", options.bindings);
-    if (options.bindConnection)
-        args.push("--bind-connection", options.bindConnection);
-    if (options.bindFolder)
-        args.push("--bind-folder", options.bindFolder);
-    if (options.noBindings)
-        args.push("--no-bindings");
-    if (options.objectName)
-        args.push("--object", options.objectName);
-    if (options.allObjects)
-        args.push("--all-objects");
-    for (const field of options.fields ?? [])
-        args.push("-f", field);
-    for (const one of options.resolve ?? [])
-        args.push("--resolve", one);
-    if (options.refreshLookups)
-        args.push("--refresh-lookups");
-    if (options.outPath)
-        args.push("--out", options.outPath);
-    if (options.version)
-        args.push("--version", options.version);
-    // Always sent, because the generator's own default is `../sdk/flow-sdk.js` —
-    // a relative path that resolves in the eval image's checkout and nowhere else.
-    // The legacy `prepare-connector` shim hard-coded this; nothing else does, so
-    // omitting it emits a descriptor whose import line resolves to nothing.
-    // Matches materializer.ts, which defaults the same specifier.
-    args.push("--import", options.connectorImport ?? DEFAULT_CONNECTOR_IMPORT);
-    if (options.jsonOnly)
-        args.push("--json-only");
-    if (options.source)
-        args.push("--source", options.source);
-    if (options.noSourceRewrite)
-        args.push("--no-source-rewrite");
-    return args;
+/** This module's options as the pipeline's, which name three things differently. */
+export function pipelineOptions(options) {
+    return {
+        connectorKey: options.connectorKey,
+        action: options.action,
+        connectionId: options.connectionId,
+        connection: options.connection,
+        bindings: options.bindings,
+        bindConnection: options.bindConnection,
+        bindFolder: options.bindFolder,
+        noBindings: options.noBindings,
+        objectName: options.objectName,
+        allObjects: options.allObjects,
+        fields: options.fields,
+        resolve: options.resolve,
+        refreshLookups: options.refreshLookups,
+        out: options.outPath,
+        version: options.version,
+        // Always set, because a descriptor's import line has to resolve for whoever
+        // installed the package. Matches materializer.ts, which defaults the same.
+        importSpecifier: options.connectorImport ?? DEFAULT_CONNECTOR_IMPORT,
+        jsonOnly: options.jsonOnly,
+        source: options.source,
+        noSourceRewrite: options.noSourceRewrite,
+    };
 }
+/**
+ * Prepare one operation, reporting to the console.
+ *
+ * Kept as a one-argument function because it is the API a caller outside this
+ * package holds; `prepare/pipeline.ts` is where the work is, and it takes its
+ * `uip` client and reporter injected so tests replay recordings.
+ */
 export async function prepareConnector(options) {
-    const args = generatorArgs(options);
-    await runGenerator({
-        script: options.generatorPath ?? packagedGenerator("prepare_connector.py"),
-        args,
-        pythonExecutable: options.pythonExecutable,
-        what: "Preparing the connector",
+    return runPipeline(pipelineOptions(options), {
+        client: defaultUipClient(),
+        reporter: consoleReporter,
     });
 }
 function value(args, name) {
@@ -136,10 +127,19 @@ export function parseArgs(argv) {
             consumed.add(index);
     });
     const positionals = argv.filter((_, index) => !consumed.has(index));
-    // `--connection-id` is no longer required: without one the generator
+    // `--connection-id` is no longer required: without one the pipeline
     // discovers the connection itself and writes bindings.json.
     if (positionals.length !== 2)
         return null;
+    // argparse put these in a mutually exclusive group, so it exited 2 when both
+    // appeared. Accepting both is worse than it sounds: the named object is
+    // matched and recorded in the ledger, and then every object is expanded over
+    // the top of it, so the author gets a different result from the one they
+    // asked for and no error.
+    if (argv.includes("--object") && argv.includes("--all-objects")) {
+        console.error("argument --all-objects: not allowed with argument --object");
+        return null;
+    }
     return {
         connectorKey: positionals[0],
         action: positionals[1],
@@ -174,12 +174,19 @@ export async function run(argv) {
         console.error(USAGE);
         return 2;
     }
+    for (const flag of ["--python", "--generator"]) {
+        if (argv.includes(flag)) {
+            console.error(`registry prepare: ${flag} is ignored — the pipeline runs in-process now and the flag will be removed.`);
+        }
+    }
     try {
         await prepareConnector(options);
         return 0;
     }
     catch (error) {
-        console.error(error instanceof Error ? error.message : String(error));
-        return 1;
+        // `exitText` reproduces the script's `sys.exit(f"prepare-connector: {e}")`,
+        // and the refusals it raises already carry that prefix.
+        console.error(exitText(error));
+        return exitCodeOf(error);
     }
 }

package/dist/registry/pull-cli.js

@@ -29,9 +29,10 @@ const USAGE = [
     "Usage: flow-sdk registry pull [--connectors <dir>] [--connector <key>]...",
     "                             [--library <dir>] [--library-md <dir>]",
     "                             [--url <url>] [--archive <zip>] [--force]",
-    "                             [--import <specifier>] [--triggers <path>] [--python <exe>]",
-    "                             [--root <prefix>] [--extractor <path>] [--generator <path>]",
+    "                             [--import <specifier>] [--triggers <path>] [--root <prefix>]",
 ].join("\n");
+/** Flags from the Python era, accepted for one release and ignored. */
+const IGNORED = ["--python", "--extractor", "--generator"];
 function value(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
@@ -191,7 +192,11 @@ export async function run(argv) {
     }
     const cacheDir = libraryCacheRoot();
     const force = has(argv, "--force");
-    const pythonExecutable = value(argv, "--python");
+    for (const flag of IGNORED) {
+        if (has(argv, flag)) {
+            console.error(`registry pull: ${flag} is ignored — the generators run in-process now and the flag will be removed.`);
+        }
+    }
     const connectorsPath = value(argv, "--connectors") ?? "connectors";
     try {
         const archive = await resolveArchive(argv, cacheDir, force);
@@ -216,8 +221,6 @@ export async function run(argv) {
                 archivePath: archive.path,
                 destinationPath: staging,
                 root: value(argv, "--root"),
-                pythonExecutable,
-                extractorPath: value(argv, "--extractor"),
             });
             await rm(libraryPath, { recursive: true, force: true });
             await mkdir(join(libraryPath, ".."), { recursive: true });
@@ -244,9 +247,7 @@ export async function run(argv) {
                 connectorsPath: wantConnectors ? connectorsPath : undefined,
                 connectorSubset: referenced,
                 connectorImport: value(argv, "--import"),
-                pythonExecutable,
                 triggersPath: value(argv, "--triggers"),
-                generatorPath: value(argv, "--generator"),
             });
         }
         if (!(await isFile(join(markdownPath, "index.json")))) {

package/dist/registry/reporter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Where progress and warnings go.
+ *
+ * The Python generators printed progress to stdout and `WARN:` lines to
+ * stderr, and prepare interleaved the two with explicit flushes so a note
+ * landed under the line it explained. A verb takes a {@link Reporter} so tests
+ * can run silent and so the CLI decides the streams once.
+ */
+export interface Reporter {
+    /** Progress a person watching the terminal wants to see. */
+    info(line: string): void;
+    /** A condition the run survived but the reader should know about. */
+    warn(line: string): void;
+}
+/** stdout for progress, stderr for warnings — the CLI's choice. */
+export declare const consoleReporter: Reporter;
+/** Everything to stderr, for verbs whose stdout carries a result. */
+export declare const stderrReporter: Reporter;
+export declare const silentReporter: Reporter;
+/** A reporter that remembers, for tests. */
+export declare class RecordingReporter implements Reporter {
+    readonly infos: string[];
+    readonly warnings: string[];
+    info(line: string): void;
+    warn(line: string): void;
+}

package/dist/registry/reporter.js

@@ -0,0 +1,41 @@
+/**
+ * Where progress and warnings go.
+ *
+ * The Python generators printed progress to stdout and `WARN:` lines to
+ * stderr, and prepare interleaved the two with explicit flushes so a note
+ * landed under the line it explained. A verb takes a {@link Reporter} so tests
+ * can run silent and so the CLI decides the streams once.
+ */
+/** stdout for progress, stderr for warnings — the CLI's choice. */
+export const consoleReporter = {
+    info(line) {
+        process.stdout.write(`${line}\n`);
+    },
+    warn(line) {
+        process.stderr.write(`${line}\n`);
+    },
+};
+/** Everything to stderr, for verbs whose stdout carries a result. */
+export const stderrReporter = {
+    info(line) {
+        process.stderr.write(`${line}\n`);
+    },
+    warn(line) {
+        process.stderr.write(`${line}\n`);
+    },
+};
+export const silentReporter = {
+    info() { },
+    warn() { },
+};
+/** A reporter that remembers, for tests. */
+export class RecordingReporter {
+    infos = [];
+    warnings = [];
+    info(line) {
+        this.infos.push(line);
+    }
+    warn(line) {
+        this.warnings.push(line);
+    }
+}

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

@@ -0,0 +1,99 @@
+export interface UipRunOptions {
+    /** Working directory for the CLI; defaults to the process's. */
+    cwd?: string;
+    /** Kill the call after this many milliseconds. `undefined` means no limit, as before. */
+    timeoutMs?: number;
+}
+export interface UipResult {
+    /** The exit code, or `null` when the process was killed by a signal. */
+    code: number | null;
+    signal?: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    /** True when `timeoutMs` elapsed and the process was killed. */
+    timedOut?: boolean;
+    /**
+     * True when no process ran because the client declined the call (see
+     * {@link OfflineUipClient}). A refusal reads like a failed run — non-zero
+     * exit, empty stdout — but it is not an answer from the tenant, so a caller
+     * that remembers failures in a cache must not remember this one.
+     */
+    refused?: boolean;
+}
+export interface UipClient {
+    /** Run `argv[0] argv.slice(1)` — the first element is the executable, normally `uip`. */
+    run(argv: readonly string[], options?: UipRunOptions): Promise<UipResult>;
+}
+/** The real thing: spawn the CLI, capture both streams, never throw on a non-zero exit. */
+export declare class SpawnUipClient implements UipClient {
+    private readonly defaults;
+    constructor(defaults?: UipRunOptions);
+    run(argv: readonly string[], options?: UipRunOptions): Promise<UipResult>;
+}
+/** The file a recorded call lives in, from its argv. */
+export declare function recordingName(argv: readonly string[]): string;
+/**
+ * Serve recorded results; refuse anything unrecorded.
+ *
+ * The refusal is the point. A test that reaches the tenant by accident should
+ * fail with the argv it tried, not pass against whatever the network said.
+ */
+export declare class ReplayUipClient implements UipClient {
+    private readonly directory;
+    private readonly byName;
+    constructor(directory: string);
+    run(argv: readonly string[]): Promise<UipResult>;
+}
+/** Run through another client and write every result down for replay. */
+export declare class RecordingUipClient implements UipClient {
+    private readonly inner;
+    private readonly directory;
+    constructor(inner: UipClient, directory: string);
+    run(argv: readonly string[], options?: UipRunOptions): Promise<UipResult>;
+}
+/**
+ * A client that runs nothing and reports every call as refused.
+ *
+ * This is what `--offline` installs, and it exists because of how a build
+ * replays. The three response caches hold every reply a run received, so a
+ * second build from them normally reaches no tenant — but a call that FAILED
+ * was never cached (neither generator caches a failed `registry get`), so the
+ * replay tries it again. On the machine doing the diagnosis there is usually no
+ * `uip`, and the build then dies on a spawn error instead of reproducing the
+ * snapshot it was asked to reproduce. A full-catalog run had 427 such calls:
+ * namespace probes where a miss is the expected answer.
+ *
+ * Failing is therefore the faithful answer, not a fallback. Every fetcher
+ * already treats a non-zero exit as "no data for this one", which is exactly
+ * what happened on the original run. The result is also marked `refused`, for
+ * the one thing a fetcher must NOT do with it: the two trigger caches remember
+ * a failure as an empty answer, and remembering a refusal that way would hand
+ * a later ONLINE run over the same `--keep-temp` caches an empty event
+ * catalogue.
+ */
+export declare class OfflineUipClient implements UipClient {
+    run(argv: readonly string[]): Promise<UipResult>;
+}
+/**
+ * The client a verb should use, honouring the recording and replay switches.
+ *
+ * Two environment variables change what a PRODUCTION build talks to, and
+ * nothing else announces them, so they are spelled out here:
+ *
+ *   - `UIP_REPLAY_DIR=<dir>` — no `uip` is run at all; every call is answered
+ *     from the recordings in `<dir>`. Set by accident, the build dies on its
+ *     first tenant call with `ReplayUipClient: no recording for …`, naming the
+ *     command and the file it looked for. Nothing is written to the tenant or
+ *     the directory.
+ *   - `UIP_RECORD_DIR=<dir>` — `uip` runs normally and every result is also
+ *     written to `<dir>` as one JSON file per call. Set by accident, the build
+ *     succeeds and looks ordinary, but leaves behind a directory of tenant
+ *     responses (connection ids, schemas, object listings) that grows with
+ *     every call; check for it if a build's working tree fills up.
+ *
+ * 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.
+ */
+export declare function defaultUipClient(options?: UipRunOptions): UipClient;

package/dist/registry/uip/client.js

@@ -0,0 +1,226 @@
+/**
+ * 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 { join } from "node:path";
+/**
+ * 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;
+/** The real thing: spawn the CLI, capture both streams, never throw on a non-zero exit. */
+export class SpawnUipClient {
+    defaults;
+    constructor(defaults = {}) {
+        this.defaults = defaults;
+    }
+    run(argv, options = {}) {
+        const [executable, ...args] = argv;
+        const timeoutMs = options.timeoutMs ?? this.defaults.timeoutMs;
+        return new Promise((resolve, reject) => {
+            // 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
+            // build runs, and no timeout is set by default. On /dev/null the prompt
+            // 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, {
+                cwd: options.cwd ?? this.defaults.cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            const stdout = [];
+            const stderr = [];
+            let bytes = 0;
+            let timedOut = false;
+            let settled = false;
+            const timer = timeoutMs !== undefined && timeoutMs > 0
+                ? setTimeout(() => {
+                    timedOut = true;
+                    child.kill("SIGKILL");
+                }, timeoutMs)
+                : undefined;
+            const collect = (chunks) => (chunk) => {
+                bytes += chunk.length;
+                chunks.push(chunk);
+                if (bytes > MAX_OUTPUT_BYTES)
+                    child.kill("SIGKILL");
+            };
+            child.stdout.on("data", collect(stdout));
+            child.stderr.on("data", collect(stderr));
+            child.on("error", (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                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."));
+                    return;
+                }
+                // Every other spawn failure — EACCES on the binary, EAGAIN with no
+                // process slots, a `uip` that is a directory — rejects as well, and
+                // that is a CHANGE from how this port read at first, where anything
+                // but a missing binary resolved a failed result and the run carried on
+                // into warnings and a thin library. Python raised `OSError` from
+                // `subprocess.run` for all of them, so rejecting is both the faithful
+                // answer and the better one: a permission problem on the CLI is not a
+                // connector that has no events.
+                reject(error);
+            });
+            child.on("close", (code, signal) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                // Decoded once, whole, so a multi-byte character split across two
+                // chunks comes out intact.
+                resolve({
+                    code,
+                    signal,
+                    stdout: Buffer.concat(stdout).toString("utf8"),
+                    stderr: Buffer.concat(stderr).toString("utf8"),
+                    timedOut,
+                });
+            });
+        });
+    }
+}
+/** The file a recorded call lives in, from its argv. */
+export function recordingName(argv) {
+    // Joined on NUL, which no argument can contain, so the digest is a function
+    // of the argument BOUNDARIES as well as the characters: a space would make
+    // `["uip", "is", "a b"]` and `["uip", "is", "a", "b"]` the same recording,
+    // and `--connectors "a,b"` versus two flags is exactly the kind of pair the
+    // registry issues.
+    const digest = createHash("sha256").update(argv.join("\u0000")).digest("hex").slice(0, 16);
+    const slug = argv
+        .slice(1, 5)
+        .join("-")
+        .replace(/[^A-Za-z0-9.-]+/g, "_")
+        .slice(0, 60);
+    return `${slug}-${digest}.json`;
+}
+/**
+ * Serve recorded results; refuse anything unrecorded.
+ *
+ * The refusal is the point. A test that reaches the tenant by accident should
+ * fail with the argv it tried, not pass against whatever the network said.
+ */
+export class ReplayUipClient {
+    directory;
+    byName = new Map();
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async run(argv) {
+        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"));
+            this.byName.set(name, recording);
+        }
+        return { ...recording.result };
+    }
+}
+/** Run through another client and write every result down for replay. */
+export class RecordingUipClient {
+    inner;
+    directory;
+    constructor(inner, directory) {
+        this.inner = inner;
+        this.directory = directory;
+        mkdirSync(directory, { recursive: true });
+    }
+    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`);
+        return result;
+    }
+}
+/**
+ * A client that runs nothing and reports every call as refused.
+ *
+ * This is what `--offline` installs, and it exists because of how a build
+ * replays. The three response caches hold every reply a run received, so a
+ * second build from them normally reaches no tenant — but a call that FAILED
+ * was never cached (neither generator caches a failed `registry get`), so the
+ * replay tries it again. On the machine doing the diagnosis there is usually no
+ * `uip`, and the build then dies on a spawn error instead of reproducing the
+ * snapshot it was asked to reproduce. A full-catalog run had 427 such calls:
+ * namespace probes where a miss is the expected answer.
+ *
+ * Failing is therefore the faithful answer, not a fallback. Every fetcher
+ * already treats a non-zero exit as "no data for this one", which is exactly
+ * what happened on the original run. The result is also marked `refused`, for
+ * the one thing a fetcher must NOT do with it: the two trigger caches remember
+ * a failure as an empty answer, and remembering a refusal that way would hand
+ * a later ONLINE run over the same `--keep-temp` caches an empty event
+ * catalogue.
+ */
+export class OfflineUipClient {
+    async run(argv) {
+        return {
+            code: 1,
+            signal: null,
+            stdout: "",
+            stderr: `offline: refused to run \`${argv.join(" ")}\` — no cached response, and --offline forbids the call`,
+            timedOut: false,
+            refused: true,
+        };
+    }
+}
+/**
+ * The client a verb should use, honouring the recording and replay switches.
+ *
+ * Two environment variables change what a PRODUCTION build talks to, and
+ * nothing else announces them, so they are spelled out here:
+ *
+ *   - `UIP_REPLAY_DIR=<dir>` — no `uip` is run at all; every call is answered
+ *     from the recordings in `<dir>`. Set by accident, the build dies on its
+ *     first tenant call with `ReplayUipClient: no recording for …`, naming the
+ *     command and the file it looked for. Nothing is written to the tenant or
+ *     the directory.
+ *   - `UIP_RECORD_DIR=<dir>` — `uip` runs normally and every result is also
+ *     written to `<dir>` as one JSON file per call. Set by accident, the build
+ *     succeeds and looks ordinary, but leaves behind a directory of tenant
+ *     responses (connection ids, schemas, object listings) that grows with
+ *     every call; check for it if a build's working tree fills up.
+ *
+ * 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.
+ */
+export function defaultUipClient(options = {}) {
+    const replay = process.env.UIP_REPLAY_DIR;
+    if (replay)
+        return new ReplayUipClient(replay);
+    const client = new SpawnUipClient(options);
+    const record = process.env.UIP_RECORD_DIR;
+    return record ? new RecordingUipClient(client, record) : client;
+}