@uipath/maestro-builder-sdk 6.18.9 → 6.19.0

package/dist/raw-node.js

@@ -0,0 +1,116 @@
+/**
+ * `rawNode` — place a node this SDK has no factory for, carrying its definition
+ * verbatim. Moved from core/node-classes.ts in Phase 3 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md so its diagnostics can ask the node-type
+ * registry what a registered type says about a raw node of it; the package entry
+ * re-exports it, so authors import it exactly as before.
+ */
+import { FlowAction, } from './core/node-classes.js';
+import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
+import { rawNodeInputProblem, rawNodeTypedFamilyWarning } from './raw-node-advice.js';
+/**
+ * Place a node this SDK has no factory for, carrying its definition verbatim
+ * (`uipath.exotic.thing@2.1` and the manifest the platform served for it).
+ *
+ * @remarks
+ * This is the escape hatch the coverage plan requires: an unknown registry
+ * definition is expressible without bypassing serializer invariants. The
+ * serializer still owns the node's id, label, `typeVersion` and edge wiring; you
+ * supply which definition and which inputs, exactly as a hand-written
+ * {@link FlowAction} subclass would.
+ *
+ * It is also what `decompile` emits for a node type it cannot name, so a
+ * round trip preserves the node's TYPE and VERSION instead of degrading it to a
+ * placeholder:
+ *
+ * ```ts
+ * .step('exotic', rawNode({
+ *   nodeType: 'uipath.exotic.thing',
+ *   version: '2.1',
+ *   manifest: exoticManifest,      // exactly what `registry get` returned
+ *   inputs: { where: input('scope') },
+ * }))
+ * ```
+ *
+ * `manifest` must be a real definition — an exact copy of what the registry or
+ * Workbench serves for that `nodeType@version`. It is not permission to invent
+ * one: the platform resolves the node against its own catalog at run time, so a
+ * hand-written manifest validates locally and fails on the tenant.
+ *
+ * Prefer a typed factory when one exists — it carries the family's checks, its
+ * defaults, and its output contract, none of which a raw node can know.
+ *
+ * **Never for a connector.** A `uipath.connector.*` node type is refused by
+ * `check` and `compile`: a raw node carries the author's inputs verbatim, so the
+ * emitted node has no `inputs.detail` and no connection binding — `validate`
+ * only warns ("Connector is not configured") and the run can never reach
+ * Integration Service. Use {@link connector}, and `registry prepare` when
+ * compile reports an input the static library does not carry; use
+ * {@link onEvent} for a connector event trigger.
+ *
+ * **Prefer the typed factory** for a node type that has one: `check` warns
+ * (`RAW_NODE_TYPED_FAMILY`), because `validate` cannot see an input the
+ * registry definition does not declare. For a `core.datafabric.*` type, a key
+ * the product never reads (an invented `_sortOptions` in place of `_sort`) is
+ * an error at a version the SDK bundles (`RAW_NODE_UNKNOWN_INPUT`); the
+ * canvas's snapshots, such as the `_entityFields` a related-path filter
+ * needs, stay legal.
+ *
+ * @param spec - The definition to compile against, plus the node's inputs.
+ * @returns A node to pass to `.step(...)`.
+ */
+export function rawNode(spec) {
+    return new RawNode(spec);
+}
+/** The {@link rawNode} implementation — a snapshot-backed contribution. */
+class RawNode extends FlowAction {
+    spec;
+    constructor(spec) {
+        super();
+        this.spec = spec;
+    }
+    /**
+     * `check` surfaces the connector refusal as an error, a typed family as a
+     * warning, and an input a registered node type never reads as an error at a
+     * bundled version (a warning at any other); `compile` throws the errors
+     * (see {@link contribute}).
+     */
+    diagnostics() {
+        const refusal = connectorRawNodeRefusal(this.spec.nodeType);
+        if (refusal)
+            return [{ code: 'RAW_NODE_CONNECTOR', severity: 'error', message: refusal }];
+        const out = [];
+        const unknown = rawNodeInputProblem(this.spec.nodeType, this.spec.version, this.spec.inputs);
+        if (unknown)
+            out.push({ code: 'RAW_NODE_UNKNOWN_INPUT', ...unknown });
+        const typed = rawNodeTypedFamilyWarning(this.spec.nodeType);
+        if (typed)
+            out.push({ code: 'RAW_NODE_TYPED_FAMILY', severity: 'warning', message: typed });
+        return out;
+    }
+    contribute(context) {
+        // compile does not run diagnostics(); refuse here too so the escape hatch
+        // cannot emit an unconfigured connector node. (An input a registered node
+        // type never reads is refused by the serializer, for every contribution.)
+        const refusal = connectorRawNodeRefusal(this.spec.nodeType);
+        if (refusal)
+            throw new Error(refusal);
+        const version = context.requestedVersion ?? this.spec.version;
+        if (context.requestedVersion !== undefined && context.requestedVersion !== this.spec.version) {
+            // Versions are exact everywhere in this SDK: a contributor may not
+            // substitute its own for an explicit request (design §2.6).
+            throw new Error(`rawNode("${this.spec.nodeType}") carries version ${this.spec.version}, but the step requests `
+                + `${context.requestedVersion}. Pass the manifest for the requested version, or drop { version }.`);
+        }
+        return {
+            definition: {
+                source: 'snapshot',
+                nodeType: this.spec.nodeType,
+                version,
+                manifest: this.spec.manifest,
+            },
+            ...(this.spec.inputs !== undefined ? { inputs: this.spec.inputs } : {}),
+            ...(this.spec.outputs !== undefined ? { outputs: this.spec.outputs } : {}),
+        };
+    }
+}

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

@@ -1,3 +1,4 @@
+import { win32 } from "node:path";
 export interface Launch {
     file: string;
     args: string[];
@@ -13,12 +14,21 @@ export interface LaunchHost {
     execPath: string;
     isFile(path: string): boolean;
     readFile(path: string): string;
+    /** Windows path operations (`node:path`'s `win32`), passed in so {@link resolveLaunch} imports nothing. */
+    win32: Pick<typeof win32, "join" | "dirname" | "extname">;
 }
+/** The host this process runs on. */
+export declare function ambientLaunchHost(): LaunchHost;
 /**
- * The file and arguments to spawn for `executable args`, without a shell.
+ * The file and arguments to spawn for `executable args` on `host`, without a shell.
+ *
+ * Self-contained on purpose (see the module comment): generated scripts embed
+ * `resolveLaunch.toString()`.
  *
  * @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 resolveLaunch(executable: string, args: readonly string[], host: LaunchHost): Launch;
+/** {@link resolveLaunch} on this process's host. */
 export declare function launchFor(executable: string, args: readonly string[], host?: LaunchHost): Launch;

package/dist/registry/uip/launch.js

@@ -22,6 +22,13 @@
  * A name that is not bare (a path, or one with an extension) is spawned as
  * given, and so is anything on another platform.
  *
+ * The rules live in ONE self-contained function, {@link resolveLaunch}, because
+ * a second copy runs outside this package: the brownfield pipeline scripts that
+ * `flow decompile` and `case decompile` write embed its source text
+ * (`pipeline-front-door.ts`, flow-builder-sdk#1120). So it may reference only
+ * its parameters and globals — no module constant, no import — and a test runs
+ * its source text in an empty context to hold that.
+ *
  * Example, on Windows with npm's global bin on PATH:
  *   launchFor("uip", ["--version"])
  *   // -> { file: "C:\\Program Files\\nodejs\\node.exe",
@@ -29,14 +36,8 @@
  */
 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() {
+/** The host this process runs on. */
+export function ambientLaunchHost() {
     return {
         platform: process.platform,
         path: process.env.PATH,
@@ -51,55 +52,61 @@ function ambientHost() {
             }
         },
         readFile: (path) => readFileSync(path, "utf8"),
+        win32,
     };
 }
-/** 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.
+ * The file and arguments to spawn for `executable args` on `host`, without a shell.
+ *
+ * Self-contained on purpose (see the module comment): generated scripts embed
+ * `resolveLaunch.toString()`.
  *
  * @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))
+export function resolveLaunch(executable, args, host) {
+    const path = host.win32;
+    // Bare: no directory part and no extension. Only a bare name is looked up.
+    const bare = executable !== "" && !/[\\/]/.test(executable) && path.extname(executable) === "";
+    if (host.platform !== "win32" || !bare)
         return { file: executable, args: [...args] };
-    const found = findOnPath(executable, host);
+    // The first `<dir>\<executable><ext>` on PATH, in cmd.exe's PATHEXT order.
+    const extensions = (host.pathExt || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+    let found;
+    search: for (const dir of (host.path ?? "").split(";")) {
+        const trimmed = dir.trim().replace(/^"(.*)"$/, "$1");
+        if (trimmed === "")
+            continue;
+        for (const ext of extensions) {
+            const candidate = path.join(trimmed, executable + ext.toLowerCase());
+            if (host.isFile(candidate)) {
+                found = candidate;
+                break search;
+            }
+        }
+    }
     // Not on PATH: spawn the bare name and let the ENOENT say so.
-    if (!found)
+    if (found === undefined)
         return { file: executable, args: [...args] };
-    const ext = win32.extname(found).toLowerCase();
+    const ext = path.extname(found).toLowerCase();
     if (ext !== ".cmd" && ext !== ".bat")
         return { file: found, args: [...args] };
-    const script = shimTarget(found, host);
-    if (!script || !host.isFile(script)) {
+    // The script an npm (cmd-shim) or pnpm shim hands its arguments to: the last
+    // quoted `%dp0%\…` / `%~dp0\…` JavaScript path followed by `%*`.
+    const matches = [...host.readFile(found).matchAll(/"%~?dp0%?\\([^"]+\.[cm]?js)"\s+%\*/g)];
+    const last = matches[matches.length - 1];
+    const script = last ? path.join(path.dirname(found), last[1]) : undefined;
+    if (script === undefined || !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`).");
+            (script !== undefined
+                ? `and the script it names (${script}) does not exist.`
+                : "and it names no JavaScript entry point to run instead.") +
+            " Reinstall it with npm (for the UiPath CLI, `npm install -g @uipath/cli`).");
     }
     return { file: host.execPath, args: [script, ...args] };
 }
+/** {@link resolveLaunch} on this process's host. */
+export function launchFor(executable, args, host = ambientLaunchHost()) {
+    return resolveLaunch(executable, args, host);
+}

package/dist/registry/uip/pipeline-front-door.d.ts

@@ -0,0 +1,2 @@
+/** The script text: imports, the embedded resolver, `frontDoor`, and `run(verb, args)`. */
+export declare function pipelineFrontDoor(kind: 'flow' | 'case'): string;

package/dist/registry/uip/pipeline-front-door.js

@@ -0,0 +1,88 @@
+/**
+ * The "front door" block of a generated brownfield pipeline script: how the
+ * script finds a CLI to run `compile`, `decompile` and `merge` with.
+ *
+ * `flow decompile` and `case decompile` each write a `<Name>.pipeline.mjs`
+ * beside the source. Both used to carry their own copy of this block, and both
+ * spawned the bare names `uip` and `npx` without a shell. On Windows both are
+ * `.cmd` shims, which Node cannot start that way, so the probe for `uip` failed,
+ * the `npx` fallback failed too, and the pipeline could not run at all
+ * (flow-builder-sdk#1120, the same defect as #940 in the registry).
+ *
+ * Now there is one block, and it starts programs through the same rules the
+ * registry uses: it embeds the source text of `resolveLaunch`
+ * (`registry/uip/launch.ts`), so a fix there reaches every pipeline written
+ * after it. The order is unchanged:
+ *   1. `uip maestro <kind>`, when `uip maestro <kind> compile --help` exits 0
+ *      (a CLI that carries the authoring commands);
+ *   2. otherwise the SDK's own `flow-sdk` bin, found the way
+ *      `npx --no-install flow-sdk` found it: `node_modules/.bin` in the script's
+ *      folder and every folder above it, then `PATH`.
+ *
+ * The block brings its own imports, `existsSync` among them, and defines
+ * `run(verb, args)`; the pipeline body uses both. Nothing in it names a path on
+ * the machine that generated it, so a pipeline stays relocatable.
+ *
+ * Example, for `kind = 'flow'` on a machine whose `uip` has the commands:
+ *   run('compile', ['A.flow.ts', '-o', 'A.edited.flow'])
+ *   // POSIX:   uip maestro flow compile A.flow.ts -o A.edited.flow
+ *   // Windows: node.exe <npm>\node_modules\@uipath\cli\dist\index.js maestro flow compile …
+ */
+import { resolveLaunch } from './launch.js';
+/** The script text: imports, the embedded resolver, `frontDoor`, and `run(verb, args)`. */
+export function pipelineFrontDoor(kind) {
+    return `import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, win32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const KIND = ${JSON.stringify(kind)};
+
+// How to start a program by name without a shell, Windows .cmd shims included.
+// Copied from the SDK's registry/uip/launch.ts when this file was generated.
+${resolveLaunch.toString()}
+
+const launchHost = (path) => ({
+  platform: process.platform,
+  path,
+  pathExt: process.env.PATHEXT,
+  execPath: process.execPath,
+  isFile: (p) => { try { return statSync(p).isFile(); } catch { return false; } },
+  readFile: (p) => readFileSync(p, 'utf8'),
+  win32,
+});
+
+// 1. \`uip maestro <kind>\`, when this CLI carries the authoring commands.
+function uipFrontDoor() {
+  let uip;
+  try {
+    uip = resolveLaunch('uip', [], launchHost(process.env.PATH));
+  } catch {
+    return undefined; // a uip shim that cannot be read: use the SDK instead
+  }
+  const probe = spawnSync(uip.file, [...uip.args, 'maestro', KIND, 'compile', '--help'], { stdio: 'ignore' });
+  return !probe.error && probe.status === 0 ? { file: uip.file, prefix: [...uip.args, 'maestro', KIND] } : undefined;
+}
+
+// 2. The SDK's flow-sdk bin, where \`npx --no-install flow-sdk\` looked for it.
+function sdkFrontDoor() {
+  const bins = [];
+  for (let dir = dirname(fileURLToPath(import.meta.url)); ; dir = dirname(dir)) {
+    bins.push(join(dir, 'node_modules', '.bin'));
+    if (dirname(dir) === dir) break;
+  }
+  let sdk;
+  if (process.platform === 'win32') {
+    sdk = resolveLaunch('flow-sdk', [], launchHost([...bins, process.env.PATH ?? ''].join(';')));
+  } else {
+    const local = bins.map((bin) => join(bin, 'flow-sdk')).find((p) => existsSync(p));
+    sdk = { file: local ?? 'flow-sdk', args: [] };
+  }
+  return { file: sdk.file, prefix: [...sdk.args, KIND] };
+}
+
+const frontDoor = uipFrontDoor() ?? sdkFrontDoor();
+const run = (verb, args) =>
+  execFileSync(frontDoor.file, [...frontDoor.prefix, verb, ...args], { stdio: 'inherit' });
+`;
+}