@uipath/maestro-builder-sdk 6.70.7 → 6.70.9

package/dist/core/binding-messages.js

@@ -5,7 +5,7 @@
  * from the inner loop as from compile. Before this, `check` printed `0 error(s)`
  * for a source `compile` then refused (teams-decision, 2026-09-01, turn 22 → 23).
  */
-import { prepareCommand } from './cli-spelling.js';
+import { placeholder, prepareCommand } from './cli-spelling.js';
 import { CompileRefusal } from './compile-refusal.js';
 /** A tenant resource key — an Integration Service connection id or an Orchestrator folder key — is a GUID. */
 export const GUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -96,7 +96,7 @@ export function bindingLabelRefusal(bindings, name, attribute, where, target) {
     return undefined;
 }
 function prepareFor(target) {
-    return prepareCommand(target?.key ?? '<connector-key>', target?.action ?? '<action>');
+    return prepareCommand(target?.key ?? placeholder('<connector-key>'), target?.action ?? placeholder('<action>'));
 }
 /**
  * Why compile refuses `name`, and how to bind it.
@@ -143,7 +143,7 @@ export function connectionConnectorConflictMessage(connection, users) {
     return `connection "${connection}" is used by steps of different connectors (${who}). An Integration Service `
         + `connection belongs to exactly one connector, so at most one of these steps can run on it, and the solution `
         + `resource would be declared as whichever came first. Give each connector its own connection label in `
-        + `bindings.json (\`${prepareCommand('<connector-key>', '<action>')}\` binds one per connector). A managed `
+        + `bindings.json (\`${prepareCommand(placeholder('<connector-key>'), placeholder('<action>'))}\` binds one per connector). A managed `
         + `\`http({ managed: true, … })\` step on another connector's connection must name that connector in `
         + `\`targetConnector\`.`;
 }

package/dist/core/byoa.js

@@ -88,11 +88,11 @@ export function byoaUnverified(where, sub, facts, ledger, bindings) {
     if (byoaRecordFor(ledger, byoaLedgerKey(sub.connector, sub.event), id))
         return undefined;
     const named = label === id ? `connection ${id}` : `connection \`${label}\` (${id})`;
-    const object = sub.object ? ` --object ${sub.object}` : '';
+    const object = sub.object ? ['--object', sub.object] : [];
     return `${where}: \`${sub.connector}\` \`${sub.event}\` requires a BYOA (bring-your-own-app) connection — `
         + `one created with your own OAuth app — and ${named} was never checked against that requirement. `
         + `A standard connection deploys and the trigger never fires. Prepare the event on this connection, `
         + `which refuses a standard connection and records a BYOA one:\n`
-        + `  ${prepareCommand(sub.connector, sub.event)}${object} --connection-id ${id}\n`
+        + `  ${prepareCommand(sub.connector, sub.event, ...object, '--connection-id', id)}\n`
         + `BYOA connections (rows for \`${sub.connector}\`): uip is connections list --byoa --all-folders`;
 }

package/dist/core/cli-spelling.d.ts

@@ -23,12 +23,33 @@ export interface CliSpellingEnv {
  * @returns `uip maestro` when the caller said so, else `npx flow-sdk`.
  */
 export declare function cliSpelling(env?: CliSpellingEnv): string;
+declare const PLACEHOLDER_TEXT: unique symbol;
+/** A `<name>` placeholder the SDK itself writes into a printed command; printed bare. */
+export interface Placeholder {
+    readonly [PLACEHOLDER_TEXT]: string;
+}
+/**
+ * Mark `<name>` as a placeholder for {@link prepareCommand}. Only a marked
+ * placeholder is printed bare: a plain string shaped like `<x>` can come from a
+ * `.flow`, and bare it is a shell redirection.
+ *
+ * @example
+ * ```ts
+ * prepareCommand(key, event, '--connection-id', placeholder('<id>'));
+ * ```
+ */
+export declare function placeholder(name: string): Placeholder;
 /**
  * A `registry prepare` command line, spelled for whoever is driving.
  *
- * @param connectorKey - The connector key, or omitted for the bare command.
- * @param action - The operation, printed as `--action <action>`.
- * @param rest - Further arguments, e.g. `--object`, `<name>`.
+ * The key, action and object often come from a `.flow` file, so every argument
+ * goes through {@link shellArg}; only a {@link placeholder} is kept as is. A value
+ * {@link shellArg} cannot quote prints as its placeholder, and the line ends
+ * with the value once, JSON-escaped: `… --object <object> (where <object> is "a';x")`.
+ *
+ * @param connectorKey - The connector key, or omitted (or empty) for the bare command.
+ * @param action - The operation, printed as `--action <action>`; omitted when empty.
+ * @param rest - Further arguments, e.g. `--object`, `Lead`; an empty one prints as `''`.
  * @returns The full command, no trailing newline.
  *
  * @example
@@ -36,9 +57,25 @@ export declare function cliSpelling(env?: CliSpellingEnv): string;
  * prepareCommand('uipath-salesforce-slack', 'send-message-to-user');
  * // -> "npx flow-sdk registry prepare uipath-salesforce-slack --action send-message-to-user"
  * // -> "uip maestro registry prepare …" when FLOW_SDK_INVOKED_AS="uip maestro"
+ * prepareCommand('uipath-x', 'created', '--object', 'My Object');
+ * // -> "npx flow-sdk registry prepare uipath-x --action created --object 'My Object'"
+ * ```
+ */
+export declare function prepareCommand(connectorKey?: string | Placeholder, action?: string | Placeholder, ...rest: (string | Placeholder)[]): string;
+/**
+ * One argument of a printed command, safe to paste into a POSIX shell or PowerShell.
+ *
+ * @param arg - The argument; `''` is returned for the empty string.
+ * @returns The argument as is, single-quoted, or `undefined` when no quoting is safe in both shells.
+ *
+ * @example
+ * ```ts
+ * shellArg('Lead');          // -> "Lead"
+ * shellArg('Lead;curl x|sh'); // -> "'Lead;curl x|sh'"
+ * shellArg("a';echo X;#");   // -> undefined
  * ```
  */
-export declare function prepareCommand(connectorKey?: string, action?: string, ...rest: string[]): string;
+export declare function shellArg(arg: string): string | undefined;
 /**
  * The argument of one `--resolve <field>:<by>=<value>`, single-quoted when the
  * shell would otherwise mangle it.
@@ -58,3 +95,4 @@ export declare function resolveFlagArg(field: string, by: string, value: string)
  * moved to `uip`. Name it here once.
  */
 export declare const PULL_COMMAND = "uip maestro registry pull";
+export {};

package/dist/core/cli-spelling.js

@@ -44,12 +44,39 @@ export function cliSpelling(env = ambientEnv()) {
     const hint = (env.FLOW_SDK_INVOKED_AS ?? '').trim();
     return SPELLING.test(hint) ? hint : DEFAULT_CLI_SPELLING;
 }
+/** A `<name>` placeholder a caller prints for the reader to fill in, e.g. `<id>`, `<action>`. */
+const PLACEHOLDER = /^<[a-z][a-z0-9-]*>$/;
+const PLACEHOLDER_TEXT = Symbol('placeholder');
+/**
+ * Mark `<name>` as a placeholder for {@link prepareCommand}. Only a marked
+ * placeholder is printed bare: a plain string shaped like `<x>` can come from a
+ * `.flow`, and bare it is a shell redirection.
+ *
+ * @example
+ * ```ts
+ * prepareCommand(key, event, '--connection-id', placeholder('<id>'));
+ * ```
+ */
+export function placeholder(name) {
+    if (!PLACEHOLDER.test(name))
+        throw new Error(`internal SDK error: ${JSON.stringify(name)} is not a <name> placeholder`);
+    return { [PLACEHOLDER_TEXT]: name };
+}
+/** The placeholder printed in place of the value after `flag`: `<object>` after `--object`, else `<arg>`. */
+function placeholderAfter(flag) {
+    return flag !== undefined && /^--[a-z][a-z0-9-]*$/.test(flag) ? `<${flag.slice(2)}>` : '<arg>';
+}
 /**
  * A `registry prepare` command line, spelled for whoever is driving.
  *
- * @param connectorKey - The connector key, or omitted for the bare command.
- * @param action - The operation, printed as `--action <action>`.
- * @param rest - Further arguments, e.g. `--object`, `<name>`.
+ * The key, action and object often come from a `.flow` file, so every argument
+ * goes through {@link shellArg}; only a {@link placeholder} is kept as is. A value
+ * {@link shellArg} cannot quote prints as its placeholder, and the line ends
+ * with the value once, JSON-escaped: `… --object <object> (where <object> is "a';x")`.
+ *
+ * @param connectorKey - The connector key, or omitted (or empty) for the bare command.
+ * @param action - The operation, printed as `--action <action>`; omitted when empty.
+ * @param rest - Further arguments, e.g. `--object`, `Lead`; an empty one prints as `''`.
  * @returns The full command, no trailing newline.
  *
  * @example
@@ -57,22 +84,64 @@ export function cliSpelling(env = ambientEnv()) {
  * prepareCommand('uipath-salesforce-slack', 'send-message-to-user');
  * // -> "npx flow-sdk registry prepare uipath-salesforce-slack --action send-message-to-user"
  * // -> "uip maestro registry prepare …" when FLOW_SDK_INVOKED_AS="uip maestro"
+ * prepareCommand('uipath-x', 'created', '--object', 'My Object');
+ * // -> "npx flow-sdk registry prepare uipath-x --action created --object 'My Object'"
  * ```
  */
 export function prepareCommand(connectorKey, action, ...rest) {
-    return [cliSpelling(), 'registry', 'prepare', connectorKey, ...(action ? ['--action', action] : []), ...rest]
-        .filter(Boolean)
-        .join(' ');
+    const held = [];
+    const arg = (value, stand) => {
+        if (typeof value !== 'string')
+            return value[PLACEHOLDER_TEXT];
+        const quoted = shellArg(value);
+        if (quoted !== undefined)
+            return quoted;
+        held.push(`${stand} is ${JSON.stringify(value)}`);
+        return stand;
+    };
+    const words = [cliSpelling(), 'registry', 'prepare'];
+    if (connectorKey)
+        words.push(arg(connectorKey, '<connector-key>'));
+    if (action)
+        words.push('--action', arg(action, '<action>'));
+    rest.forEach((value, i) => {
+        const prev = rest[i - 1];
+        words.push(arg(value, placeholderAfter(typeof prev === 'string' ? prev : undefined)));
+    });
+    const line = words.join(' ');
+    return held.length ? `${line} (where ${held.join(', ')})` : line;
+}
+/** Characters a POSIX shell or PowerShell reads specially in an unquoted argument (globs, whitespace, quotes incl. “ ” „, `$`, operators). */
+const SHELL_UNSAFE = /[\s'"`$\\[\]*?;&|(){}!#~<>\u201C-\u201E]/;
+/**
+ * Characters no single quoting keeps literal in both a POSIX shell and
+ * PowerShell: POSIX writes `'` as `'\''`, which PowerShell reads as a break-out;
+ * PowerShell also ends `'…'` at U+2018–U+201B; a control character can end the
+ * line. Every other character is literal inside `'…'` in both.
+ */
+const UNQUOTABLE = /['\u2018-\u201B\p{Cc}]/u;
+/** `arg` in POSIX shell single quotes, each embedded `'` written as `'\''`. */
+function singleQuote(arg) {
+    return `'${arg.replaceAll("'", `'\\''`)}'`;
 }
 /**
- * Characters that make a `--resolve` argument unsafe to paste unquoted. `[*]`
- * is a shell glob (every multiselect wire name, `users[*]`), whitespace splits
- * a real name (`Coder Evals`) into two arguments, and quotes, `$`, backslash
- * and the control operators change what the shell hands over. The `<value>`
- * placeholder a template prints is stripped before the test, so a template
- * with nothing else unsafe keeps its bytes.
+ * One argument of a printed command, safe to paste into a POSIX shell or PowerShell.
+ *
+ * @param arg - The argument; `''` is returned for the empty string.
+ * @returns The argument as is, single-quoted, or `undefined` when no quoting is safe in both shells.
+ *
+ * @example
+ * ```ts
+ * shellArg('Lead');          // -> "Lead"
+ * shellArg('Lead;curl x|sh'); // -> "'Lead;curl x|sh'"
+ * shellArg("a';echo X;#");   // -> undefined
+ * ```
  */
-const SHELL_UNSAFE = /[\s'"`$\\[\]*?;&|(){}!#~<>]/;
+export function shellArg(arg) {
+    if (UNQUOTABLE.test(arg))
+        return undefined;
+    return arg === '' || SHELL_UNSAFE.test(arg) ? `'${arg}'` : arg;
+}
 /**
  * The argument of one `--resolve <field>:<by>=<value>`, single-quoted when the
  * shell would otherwise mangle it.
@@ -86,7 +155,7 @@ export function resolveFlagArg(field, by, value) {
     const arg = `${field}:${by}=${value}`;
     if (!SHELL_UNSAFE.test(arg.replaceAll('<value>', '')))
         return arg;
-    return `'${arg.replaceAll("'", `'\\''`)}'`;
+    return singleQuote(arg);
 }
 /**
  * The command a message tells a person or agent to run when the cache is

package/dist/core/connector-checks.js

@@ -260,7 +260,7 @@ export function checkConnectorSchema(where, spec, opts, dialect, report) {
             message: `${where}: object "${spec.object}" has no locally materialized schema — `
                 + `this operation resolves its object against the connection, so its fields cannot be `
                 + `validated here and compile will emit it unverified. Prepare it once:\n`
-                + `  ${prepare} --object ${spec.object}\n`
+                + `  ${prepareCommand(spec.key, spec.action, ...(spec.object ? ['--object', spec.object] : []))}\n`
                 + `The name is matched against the connected catalog (exact, then case-insensitive on `
                 + `name and display name); several matches fail with the candidates to choose from, and `
                 + `the prepared descriptor is the import to switch to.`,

package/dist/core/event-checks.js

@@ -121,7 +121,7 @@ compileRefusals = true) {
         warn('OBJECT_UNPREPARED', `${where}: object \`${object}\` has no prepared schema for `
             + `\`${sub.connector}\` \`${sub.event}\`, and this connector's objects come from `
             + `the connection, so the library cannot carry one. Materialize it:\n`
-            + `  ${prepareCommand(connectorKey, eventName)} --object ${object}\n`
+            + `  ${prepareCommand(connectorKey, eventName, '--object', object)}\n`
             + `Until then its event parameters and filterable fields are unknown and `
             + `nothing here can check them.`);
     }
@@ -171,8 +171,7 @@ compileRefusals = true) {
                     + `connector discovers CUSTOM FIELDS per connection, so the baked list is a `
                     + `subset by design and this name may be a real field of yours. Prepare the `
                     + `event against your connection to check it for real:\n`
-                    + `  ${prepareCommand(connectorKey, eventName)}`
-                    + `${object ? ` --object ${object}` : ''}\n`
+                    + `  ${prepareCommand(connectorKey, eventName, ...(object ? ['--object', object] : []))}\n`
                     + `Baked fields: ${names.slice(0, 12).join(', ')}${names.length > 12 ? ', …' : ''}.`);
                 return;
             }

package/dist/decompile.js

@@ -45,7 +45,7 @@ import { outputBackingGlobal, outputBackingName } from './flow-output-backing.js
 import { mapJsCode } from './core/js-code-spans.js';
 import { VARS_READ_RE } from './core/vars-read.js';
 import { missingBindingLabels } from './core/binding-messages.js';
-import { prepareCommand } from './core/cli-spelling.js';
+import { placeholder, prepareCommand } from './core/cli-spelling.js';
 import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
 import { contributionPort, forwardFanOut } from './core/definition-handles.js';
 import { STICKY_NOTE_TYPE } from './core/definitionless-node-types.js';
@@ -982,7 +982,7 @@ function unboundMarker(node, labels, key, action) {
         + `The source leaves ${missing.length > 1 ? 'them' : 'it'} out${isCanvasDraft(node)
             ? ' and marks the step `{ draft: true }`: compile writes it as a draft, and check refuses it'
             : ', and compile and check refuse it'} (BINDING_MISSING) until it names both labels: `
-        + `run \`${prepareCommand(key, action ?? '<action>')}\`, then pass `
+        + `run \`${prepareCommand(key, action ?? placeholder('<action>'))}\`, then pass `
         + `\`connection\` and \`folder\`.`);
     return ` /* TODO: bind ${commentText(names)}; check refuses this node until it has both labels (BINDING_MISSING) */`;
 }

package/dist/registry/generators/descriptors.js

@@ -18,7 +18,7 @@
  * event's per-object variants are skipped because they share their template's
  * node type and so would emit the same const twice.
  */
-import { prepareCommand } from "../../core/cli-spelling.js";
+import { placeholder, prepareCommand } from "../../core/cli-spelling.js";
 import { commentText, docComment } from "../../core/comment-text.js";
 import { PACKAGE_NAME } from "../../package-name.js";
 import { pyJsonString, pyJsonStringify } from "../codecs/pyjson.js";
@@ -207,7 +207,7 @@ export function emitEvent(entry, inFields, inputTree, outputTree, name, inputTyp
         lines.push(" * Requires a BYOA (bring-your-own-app) connection — on a standard one the");
         lines.push(" * trigger deploys and never fires. Bind it with");
         // Spelled for whoever ran the generator, like every `check` remedy.
-        lines.push(` * \`${commentText(prepareCommand(pyStr(connectorKey), eventId, "--connection-id", "<id>"))}\`,`);
+        lines.push(` * \`${commentText(prepareCommand(pyStr(connectorKey), eventId, "--connection-id", placeholder("<id>")))}\`,`);
         lines.push(" * which refuses a standard connection and records the check `compile` requires;");
         lines.push(" * `uip is connections list --byoa --all-folders` lists the BYOA connections.");
     }

package/dist/registry/generators/markdown/sections/event-facts.js

@@ -5,7 +5,7 @@
  * event page is unchanged. The facts are the sidecar's, which the library build
  * stamps from the event's `triggers objects` row (#848).
  */
-import { prepareCommand } from "../../../../core/cli-spelling.js";
+import { placeholder, prepareCommand } from "../../../../core/cli-spelling.js";
 import { isEventNodeType } from "../../../model/library.js";
 import { dictOf, getStr } from "../pyvalue.js";
 export function eventFactsLines(j, v1def) {
@@ -29,7 +29,7 @@ export function eventFactsLines(j, v1def) {
             "connection that was never checked (`EVENT_BYOA_UNVERIFIED`).");
         out.push("");
         out.push("```bash");
-        out.push(prepareCommand(key, event, "--connection-id", "<id>"));
+        out.push(prepareCommand(key, event, "--connection-id", placeholder("<id>")));
         out.push("uip is connections list --byoa --all-folders   # the BYOA connections");
         out.push("```");
         out.push("");

package/dist/serialize.js

@@ -57,7 +57,7 @@ import { planFlowGlobals, planSharedInputs, sharedInputRoots } from './flow-vari
 import { outputBackingGlobal, planOutputBacking } from './flow-output-backing.js';
 import { mapJsCode } from './core/js-code-spans.js';
 import { contributionPort } from './core/definition-handles.js';
-import { prepareCommand } from './core/cli-spelling.js';
+import { placeholder, prepareCommand } from './core/cli-spelling.js';
 import { processResourceBindings } from './core/process-resource.js';
 import { types } from './core/expr.js';
 import { SUBFLOW_START_LABEL } from './core/subflow-start.js';
@@ -612,7 +612,7 @@ function resolveBinding(opts, name, attribute, where, target) {
         const fault = STUB_GUID_RE.test(value)
             ? `"401 Invalid Organization or User secret, or invalid Element token provided" — no such connection exists`
             : `"'Connection' has an invalid GUID value: '${value}'"`;
-        const remedy = `Bind the real one: \`${prepareCommand('<connector-key>', '<action>')}\` finds the connection `
+        const remedy = `Bind the real one: \`${prepareCommand(placeholder('<connector-key>'), placeholder('<action>'))}\` finds the connection `
             + `and writes both entries into bindings.json (several candidates: pass \`--connection-id <id>\` from the list it `
             + `prints); by hand, read Id and FolderKey from \`uip is connections list --all-folders --output json\`.`;
         const message = resolved === undefined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.70.7",
+  "version": "6.70.9",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -100,5 +100,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "31471f814e8ca706a02e96e3dbceb39641584de6"
+  "gitref": "89c9c37af44dc7763bc2334209b79935aff68e7a"
 }