@uipath/maestro-builder-sdk 6.9.4 → 6.10.0

package/dist/cli/commands/flow.js

@@ -1,4 +1,19 @@
-import { addValue, emitOnlyEnabled, inferCheckMode, invoke, loadTool } from '../common.js';
+import { Option } from 'commander';
+import { addValue, emitOnlyEnabled, inferCheckMode, invoke, loadTool, namedOrLegacySecond, retiredCompiledOption, refuse } from '../common.js';
+/** The retired compiled check's flags: `[commander flags, option key, description]`. One table, so hiding and warning cannot drift. */
+const RETIRED_COMPILED_CHECK_FLAGS = [
+    ['--uip', 'uip', 'retired: resolve missing schemas with the UiPath CLI'],
+    ['--max-errors <count>', 'maxErrors', 'retired: stop after this many compiled-check errors'],
+    ['--script-determinism', 'scriptDeterminism', 'retired: check script blocks for non-deterministic calls'],
+    ['--quiet', 'quiet', 'retired: suppress warnings and information'],
+    ['--debug-internal', 'debugInternal', 'retired: include internal compile context'],
+    ['--dump-ir', 'dumpIr', 'retired: print the generated intermediate representation'],
+];
+function retiredFlagsPassed(options) {
+    return RETIRED_COMPILED_CHECK_FLAGS
+        .filter(([, key]) => options[key] !== undefined && options[key] !== false)
+        .map(([flags]) => flags.split(' ')[0]);
+}
 export function registerFlowCommands(program) {
     const flow = program.command('flow').description('Build and check Flow artifacts.');
     flow.command('compile')
@@ -19,24 +34,21 @@ export function registerFlowCommands(program) {
             argv.push('--no-check');
         await invoke('flow compile', () => loadTool(import.meta.url, '../../compile-cli.js'), argv);
     });
-    flow.command('check')
-        .description('Check authored TypeScript or a compiled .flow artifact.')
-        .argument('<input>', 'source or compiled artifact')
+    const check = flow.command('check')
+        .description('Check authored TypeScript. Check a compiled .flow with `uip maestro flow validate`.')
+        .argument('<input>', 'a .flow.ts path or bare name')
         .option('--source', 'check authored TypeScript')
-        .option('--compiled', 'check the emitted artifact')
+        .addOption(retiredCompiledOption())
         .option('--library <dir>', 'connector library directory')
-        .option('--connectors-local <dir>', 'connection-resolved connector overlay')
-        .option('--json', 'print compiled-check diagnostics as JSON')
-        .option('--uip', 'resolve missing schemas with the UiPath CLI')
-        .option('--max-errors <count>', 'stop after this many compiled-check errors')
-        .option('--script-determinism', 'check script blocks for non-deterministic calls')
-        .option('--quiet', 'suppress warnings and information')
-        .option('--debug-internal', 'include internal compile context')
-        .option('--dump-ir', 'print the generated intermediate representation')
+        .option('--connectors-local <dir>', 'connection-resolved connector overlay');
+    // Hidden, not removed: scripts that pass these keep parsing.
+    for (const [flags, , description] of RETIRED_COMPILED_CHECK_FLAGS) {
+        check.addOption(new Option(flags, description).hideHelp());
+    }
+    check
         .action(async (input, options) => {
         if (emitOnlyEnabled()) {
-            console.error('flow-sdk flow check: disabled by emit-only mode; use `uip maestro flow validate` or `uip maestro flow debug`');
-            process.exitCode = 2;
+            refuse('flow-sdk flow check: disabled by emit-only mode; use `uip maestro flow validate` or `uip maestro flow debug`');
             return;
         }
         let mode;
@@ -44,11 +56,16 @@ export function registerFlowCommands(program) {
             mode = inferCheckMode('flow', input, options.source === true, options.compiled === true);
         }
         catch (error) {
-            console.error(`flow-sdk flow check: ${error instanceof Error ? error.message : String(error)}`);
-            process.exitCode = 2;
+            refuse(`flow-sdk flow check: ${error instanceof Error ? error.message : String(error)}`);
             return;
         }
         if (mode === 'source') {
+            const ignored = retiredFlagsPassed(options);
+            // Not under `--quiet`: a caller asking for less output (an older
+            // `uip` still forwards it) must not get a new line because of it.
+            if (ignored.length > 0 && options.quiet !== true) {
+                console.error(`flow-sdk flow check: ignoring ${ignored.join(', ')} (used only by the retired compiled check)`);
+            }
             const argv = [input];
             addValue(argv, '--library', options.library);
             addValue(argv, '--connectors-local', options.connectorsLocal);
@@ -63,11 +80,10 @@ export function registerFlowCommands(program) {
         // and every current authoring flow uses — this path already refused, with the same two
         // suggestions repeated here. What is checked at author time is `check.ts`, reached above by
         // the `source` arm, and that is untouched.
-        console.error('flow-sdk flow check: checking a COMPILED .flow is no longer supported here. ' +
+        refuse('flow-sdk flow check: checking a COMPILED .flow is no longer supported here. ' +
             'Use `uip maestro flow validate <file.flow>` for the product static check, or ' +
             '`uip maestro flow debug` / `flow-debug <file.flow>` to run it. ' +
             'Authoring-time checks still work on a .flow.ts source (--source).');
-        process.exitCode = 2;
     });
     flow.command('decompile')
         .description('Convert a .flow artifact to authored TypeScript.')
@@ -88,11 +104,19 @@ export function registerFlowCommands(program) {
     });
     flow.command('merge')
         .description('Merge an edited flow with its original artifact.')
-        .argument('<original>', 'original .flow path')
         .argument('<edited>', 'edited .flow path')
+        .option('--original <file>', '(required) original .flow path, the artifact to merge into')
         .option('-o, --output <file>', 'merged output path')
         .option('--baseline <file>', 'compiled pristine decompile')
-        .action(async (original, edited, options) => {
+        .allowExcessArguments()
+        .action(async (_edited, options, command) => {
+        const pair = namedOrLegacySecond(command, {
+            label: 'flow merge', flag: '--original', named: options.original, legacyNamedFirst: true,
+            usage: 'flow merge <edited> --original <file>',
+        });
+        if (!pair)
+            return;
+        const [edited, original] = pair;
         const argv = [original, edited];
         addValue(argv, '-o', options.output);
         addValue(argv, '--baseline', options.baseline);

package/dist/cli/commands/registry.js

@@ -1,4 +1,4 @@
-import { addValue, invoke, loadTool } from '../common.js';
+import { addValue, invoke, loadTool, namedOrLegacySecond } from '../common.js';
 /** Commander hands a repeatable option one value at a time. */
 function collect(value, previous) {
     return [...previous, value];
@@ -124,7 +124,8 @@ export function registerRegistryCommands(program) {
     family.command('prepare')
         .description("Resolve one operation's schema against a live connection into ./connectors-local.")
         .argument('<connector-key>', 'connector key, e.g. uipath-salesforce')
-        .argument('<action>', 'operation to resolve, e.g. InsertRecord')
+        .option('--action <name>', '(required) operation to resolve, e.g. InsertRecord')
+        .allowExcessArguments()
         // Optional: without one the command discovers the connection itself from
         // `uip is connections list` and writes both keys into bindings.json.
         .option('--connection-id <id>', 'connection to read the schema through')
@@ -158,7 +159,14 @@ export function registerRegistryCommands(program) {
         .option('--refresh-lookups', 're-resolve lookups already recorded in resolutions.json')
         .option('--source <flow.ts>', 'the flow whose import to repoint at the prepared descriptor')
         .option('--no-source-rewrite', 'print the import line instead of editing the source')
-        .action(async (connectorKey, action, options) => {
+        .action(async (_connectorKey, options, command) => {
+        const pair = namedOrLegacySecond(command, {
+            label: 'registry prepare', flag: '--action', named: options.action, legacyNamedFirst: false,
+            usage: 'registry prepare <connector-key> --action <name>',
+        });
+        if (!pair)
+            return;
+        const [connectorKey, action] = pair;
         const argv = [connectorKey, action];
         addValue(argv, '--connection-id', options.connectionId);
         addValue(argv, '--connection', options.connection);

package/dist/cli/common.d.ts

@@ -1,3 +1,4 @@
+import { type Command, Option } from 'commander';
 export type ToolRun = (argv: string[]) => Promise<number> | number;
 export declare function loadTool(baseUrl: string, relativePath: string): Promise<{
     run: ToolRun;
@@ -5,6 +6,24 @@ export declare function loadTool(baseUrl: string, relativePath: string): Promise
 export declare function invoke(label: string, load: () => Promise<{
     run: ToolRun;
 }>, argv: string[]): Promise<void>;
+/**
+ * Refuse the verb before any tool runs: the message on stderr, the exit code
+ * (2, a usage error or blocked mode, unless given), and the message as the
+ * `--json` object's `error`.
+ */
+export declare function refuse(message: string, exitCode?: number): void;
+/** Record why the verb failed before any tool ran, for the `--json` object. */
+export declare function recordJsonError(message: string): void;
+/** Turn `--json` on for this run (the umbrella's `preAction` hook). */
+export declare function requestJsonResult(): void;
+export declare function jsonResultRequested(): boolean;
+/**
+ * Print the verb's result as one JSON object on stdout: `ok` (the exit code
+ * was 0) plus whatever the tool reported. Printed even when the verb refused
+ * before reaching a tool (a usage error, emit-only mode), so a `--json` caller
+ * always gets one object to parse.
+ */
+export declare function emitJsonResult(): void;
 export declare function addValue(argv: string[], flag: string, value: unknown): void;
 /**
  * Is emit-only mode on for the PROJECT containing `cwd`?
@@ -28,3 +47,25 @@ export declare function addValue(argv: string[], flag: string, value: unknown):
 export declare function emitOnlyEnabled(cwd?: string, env?: NodeJS.ProcessEnv): boolean;
 export type CheckMode = 'source' | 'compiled';
 export declare function inferCheckMode(family: 'flow' | 'case' | 'bpmn', input: string, source: boolean, compiled: boolean): CheckMode;
+/**
+ * `--compiled` on `<family> check`: hidden from `--help`, still accepted so a
+ * script that passes it gets the redirect to `uip maestro <family> validate`.
+ */
+export declare function retiredCompiledOption(): Option;
+/**
+ * The primary positional and a named second value (`--original`, `--action`),
+ * also accepting the deprecated two-positional form with a warning.
+ * `legacyNamedFirst` says where the named value sat in that form: first for
+ * merge (`<original> <edited>`), second for prepare (`<key> <action>`). The
+ * verb must call `allowExcessArguments()` so the legacy value reaches
+ * `command.args`.
+ *
+ * Returns `[primary, named]`, or `null` after reporting a usage error (exit 2).
+ */
+export declare function namedOrLegacySecond(command: Command, spec: {
+    label: string;
+    flag: string;
+    named: string | undefined;
+    legacyNamedFirst: boolean;
+    usage: string;
+}): [string, string] | null;

package/dist/cli/common.js

@@ -1,9 +1,14 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { Option } from 'commander';
 export function loadTool(baseUrl, relativePath) {
     return import(new URL(relativePath, baseUrl).href);
 }
 export async function invoke(label, load, argv) {
+    // In `--json` mode stdout carries exactly one JSON object, printed by
+    // `emitJsonResult` once the verb is done. The tool's own human lines go to
+    // stderr meanwhile, so they are still seen but never mixed into it.
+    const restore = jsonResultRequested() ? routeStdoutToStderr() : () => { };
     try {
         const code = await (await load()).run(argv);
         if (code !== 0)
@@ -12,8 +17,63 @@ export async function invoke(label, load, argv) {
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         console.error(`flow-sdk ${label}: ${message}`);
+        resultSlot().fields.error ??= message;
         process.exitCode = 1;
     }
+    finally {
+        restore();
+    }
+}
+/**
+ * The slot `src/cli-result.ts` writes (`reportResult`). Read here through the
+ * same `Symbol.for` key, since `dist/cli/` and `dist/` are separate builds.
+ */
+const RESULT_SLOT = Symbol.for('uipath.maestro-builder-sdk.cli-result');
+function resultSlot() {
+    const global = globalThis;
+    global[RESULT_SLOT] ??= { json: false, fields: {} };
+    return global[RESULT_SLOT];
+}
+/**
+ * Refuse the verb before any tool runs: the message on stderr, the exit code
+ * (2, a usage error or blocked mode, unless given), and the message as the
+ * `--json` object's `error`.
+ */
+export function refuse(message, exitCode = 2) {
+    console.error(message);
+    recordJsonError(message);
+    process.exitCode = exitCode;
+}
+/** Record why the verb failed before any tool ran, for the `--json` object. */
+export function recordJsonError(message) {
+    resultSlot().fields.error ??= message.replace(/^error: /, '');
+}
+/** Turn `--json` on for this run (the umbrella's `preAction` hook). */
+export function requestJsonResult() {
+    resultSlot().json = true;
+}
+export function jsonResultRequested() {
+    return resultSlot().json;
+}
+/** Route `process.stdout.write` to stderr; returns the undo. */
+function routeStdoutToStderr() {
+    const original = process.stdout.write;
+    process.stdout.write = ((chunk, ...rest) => process.stderr.write(chunk, ...rest));
+    return () => {
+        process.stdout.write = original;
+    };
+}
+/**
+ * Print the verb's result as one JSON object on stdout: `ok` (the exit code
+ * was 0) plus whatever the tool reported. Printed even when the verb refused
+ * before reaching a tool (a usage error, emit-only mode), so a `--json` caller
+ * always gets one object to parse.
+ */
+export function emitJsonResult() {
+    if (!jsonResultRequested())
+        return;
+    const ok = (process.exitCode ?? 0) === 0;
+    process.stdout.write(`${JSON.stringify({ ok, ...resultSlot().fields })}\n`);
 }
 export function addValue(argv, flag, value) {
     if (typeof value === 'string')
@@ -90,3 +150,40 @@ export function inferCheckMode(family, input, source, compiled) {
     }
     return source ? 'source' : compiled ? 'compiled' : inferred;
 }
+/**
+ * `--compiled` on `<family> check`: hidden from `--help`, still accepted so a
+ * script that passes it gets the redirect to `uip maestro <family> validate`.
+ */
+export function retiredCompiledOption() {
+    return new Option('--compiled', 'retired: a compiled artifact is checked by `uip maestro <family> validate`').hideHelp();
+}
+/**
+ * The primary positional and a named second value (`--original`, `--action`),
+ * also accepting the deprecated two-positional form with a warning.
+ * `legacyNamedFirst` says where the named value sat in that form: first for
+ * merge (`<original> <edited>`), second for prepare (`<key> <action>`). The
+ * verb must call `allowExcessArguments()` so the legacy value reaches
+ * `command.args`.
+ *
+ * Returns `[primary, named]`, or `null` after reporting a usage error (exit 2).
+ */
+export function namedOrLegacySecond(command, spec) {
+    const [first, extra, ...rest] = command.args;
+    const usageError = (message) => {
+        refuse(`flow-sdk ${spec.label}: ${message} (usage: ${spec.usage})`);
+        return null;
+    };
+    if (rest.length > 0)
+        return usageError(`unexpected argument '${rest[0]}'`);
+    if (spec.named !== undefined) {
+        if (extra !== undefined)
+            return usageError(`pass ${spec.flag} or a second argument, not both`);
+        return [first, spec.named];
+    }
+    if (extra === undefined)
+        return usageError(`missing ${spec.flag}`);
+    // Spelled for this package's bin: a `uip` release without the named form
+    // (before UiPath/cli#4526) rejects it, while `npx flow-sdk …` always works.
+    console.error(`flow-sdk ${spec.label}: the two-argument form is deprecated; use \`npx flow-sdk ${spec.usage}\``);
+    return spec.legacyNamedFirst ? [extra, first] : [first, extra];
+}

package/dist/cli/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
-import { Command } from 'commander';
+import { Command, CommanderError } from 'commander';
+import { emitJsonResult, recordJsonError, requestJsonResult } from './common.js';
 import { registerBpmnCommands } from './commands/bpmn.js';
 import { registerCaseCommands } from './commands/case.js';
 import { registerFlowCommands } from './commands/flow.js';
@@ -15,4 +16,41 @@ registerFlowCommands(program);
 registerCaseCommands(program);
 registerBpmnCommands(program);
 registerRegistryCommands(program);
-await program.parseAsync(process.argv);
+// `--json` on every verb (#809): one JSON object on stdout, human lines on
+// stderr. Added here, once, so a new verb cannot ship without it.
+const addJson = (command) => {
+    if (command.commands.length > 0) {
+        command.commands.forEach(addJson);
+        return;
+    }
+    if (!command.options.some((option) => option.long === '--json')) {
+        command.option('--json', 'print the result as one JSON object on stdout (human lines go to stderr)');
+    }
+};
+program.commands.forEach(addJson);
+program.hook('preAction', (_program, action) => {
+    if (action.opts().json === true)
+        requestJsonResult();
+});
+// A parse error (unknown option, extra argument) is raised before any hook
+// runs, so `--json` is read from argv for that case: the caller still gets its
+// one object. Help and version are the exception — they are text by request.
+program.exitOverride();
+program.commands.forEach(function override(command) {
+    command.exitOverride();
+    command.commands.forEach(override);
+});
+try {
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    if (!(error instanceof CommanderError))
+        throw error;
+    process.exitCode = error.exitCode;
+    const text = error.code === 'commander.helpDisplayed' || error.code === 'commander.version' || error.code === 'commander.help';
+    if (!text && process.argv.includes('--json')) {
+        requestJsonResult();
+        recordJsonError(error.message);
+    }
+}
+emitJsonResult();

package/dist/cli-result.d.ts

@@ -0,0 +1,22 @@
+/**
+ * cli-result — the structured result a verb reports for `--json`. One
+ * `globalThis` slot because `dist/cli/` and `dist/` are separate builds.
+ */
+/**
+ * Record fields of this verb's result. Later calls add to earlier ones.
+ *
+ * Cheap and harmless without `--json`: the fields are kept and never printed.
+ *
+ * @param fields - JSON-serializable values, e.g. `{ path, nodes, edges }`.
+ */
+export declare function reportResult(fields: Record<string, unknown>): void;
+/**
+ * Report a check's diagnostics as `{ errors, warnings, diagnostics }`, the one
+ * shape every family's check (and compile's check pass) uses.
+ */
+export declare function reportDiagnostics(diags: ReadonlyArray<{
+    level: string;
+    code: string;
+    message: string;
+    suggestion?: string;
+}>): void;

package/dist/cli-result.js

@@ -0,0 +1,31 @@
+/**
+ * cli-result — the structured result a verb reports for `--json`. One
+ * `globalThis` slot because `dist/cli/` and `dist/` are separate builds.
+ */
+const SLOT = Symbol.for('uipath.maestro-builder-sdk.cli-result');
+function slot() {
+    const global = globalThis;
+    global[SLOT] ??= { json: false, fields: {} };
+    return global[SLOT];
+}
+/**
+ * Record fields of this verb's result. Later calls add to earlier ones.
+ *
+ * Cheap and harmless without `--json`: the fields are kept and never printed.
+ *
+ * @param fields - JSON-serializable values, e.g. `{ path, nodes, edges }`.
+ */
+export function reportResult(fields) {
+    Object.assign(slot().fields, fields);
+}
+/**
+ * Report a check's diagnostics as `{ errors, warnings, diagnostics }`, the one
+ * shape every family's check (and compile's check pass) uses.
+ */
+export function reportDiagnostics(diags) {
+    reportResult({
+        errors: diags.filter((d) => d.level === 'error').length,
+        warnings: diags.filter((d) => d.level !== 'error').length,
+        diagnostics: diags.map((d) => ({ level: d.level, code: d.code, message: d.message, ...(d.suggestion ? { suggestion: d.suggestion } : {}) })),
+    });
+}

package/dist/compile-cli.js

@@ -17,6 +17,7 @@
  * product's own gates are supposed to answer. `.build()` still throws on
  * structural problems; only the diagnostic pass is skipped.
  */
+import { reportDiagnostics, reportResult } from './cli-result.js';
 import { writeFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
@@ -123,6 +124,7 @@ export async function run(argv) {
         for (const d of diags)
             console.error(`  ${d.level === 'error' ? '✗' : '⚠'} [${d.code}] ${d.message}${d.suggestion ? ` (did you mean "${d.suggestion}"?)` : ''}`);
         if (errors.length) {
+            reportDiagnostics(diags);
             console.error(`compile: ${errors.length} error(s); not emitting.`);
             return 1;
         }
@@ -146,6 +148,10 @@ export async function run(argv) {
         for (const w of warnings)
             console.error(`  ⚠ [${w.code}] ${w.message}`);
         console.error(`  ✗ [${error.code}] ${error.message}`);
+        reportDiagnostics([
+            ...warnings.map((w) => ({ level: 'warning', code: w.code, message: w.message })),
+            { level: 'error', code: error.code, message: error.message },
+        ]);
         console.error('compile: 1 error(s); not emitting.');
         return 1;
     }
@@ -155,6 +161,10 @@ export async function run(argv) {
     const out = opt(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;
     writeFileSync(out, JSON.stringify(flowJson, null, 2) + '\n');
     console.log(`compile: wrote ${out} (${flowJson.nodes.length} nodes, ${flowJson.edges.length} edges)`);
+    const written = [];
+    reportResult({ path: resolve(out), nodes: flowJson.nodes.length, edges: flowJson.edges.length, sidecars: written });
+    // Same keys and types as a failed compile: `warnings` a count, `diagnostics` the list.
+    reportDiagnostics(warnings.map((w) => ({ level: 'warning', code: w.code, message: w.message })));
     // An inline agent is TWO artifacts: the node, and the agent's own configuration
     // at `<source>/agent.json` — which is where flow-v1's serializer points the
     // runtime (`entryPoint: "<source>/agent.json"`, resolved relative to the
@@ -168,11 +178,13 @@ export async function run(argv) {
         const target = resolve(outDir, s.path);
         if (target !== outDir && !target.startsWith(outDir + '/')) {
             console.error(`compile: refusing to write a sidecar outside the flow's directory: ${s.path}`);
+            reportResult({ error: `refusing to write a sidecar outside the flow's directory: ${s.path}` });
             return 1;
         }
         mkdirSync(dirname(target), { recursive: true });
         writeFileSync(target, JSON.stringify(s.json, null, 2) + '\n');
         console.log(`compile: wrote ${s.path}`);
+        written.push(target);
     }
     // PRUNE the agent resources this compile owns but did not write this time.
     // Compile otherwise only ever ADDS files, and an agent resource is keyed by a

package/dist/core/actions.d.ts

@@ -3153,8 +3153,7 @@ export declare function dynamicExtract(inputs: DynamicExtractInputs): ActionSpec
  *
  * A connector operation's body fields come from the entity, so the library
  * cannot carry them: run `uip maestro registry prepare uipath-uipath-dataservice
- * get-entity-record-by-id -f entityName=<Entity>` first (`npx flow-sdk registry
- * prepare …` is the same command when invoking the package's own bin directly).
+ * get-entity-record-by-id -f entityName=<Entity>` first.
  * The routing table is in the `data-fabric.md` reference and the parent-field
  * loop in `connector-params.md` — cited by name rather than linked, because this
  * comment renders both into the flat corpus, where those files sit alongside

package/dist/core/actions.js

@@ -918,8 +918,7 @@ export function dynamicExtract(inputs) {
  *
  * A connector operation's body fields come from the entity, so the library
  * cannot carry them: run `uip maestro registry prepare uipath-uipath-dataservice
- * get-entity-record-by-id -f entityName=<Entity>` first (`npx flow-sdk registry
- * prepare …` is the same command when invoking the package's own bin directly).
+ * get-entity-record-by-id -f entityName=<Entity>` first.
  * The routing table is in the `data-fabric.md` reference and the parent-field
  * loop in `connector-params.md` — cited by name rather than linked, because this
  * comment renders both into the flat corpus, where those files sit alongside

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

@@ -26,17 +26,19 @@ export declare function cliSpelling(env?: CliSpellingEnv): string;
 /**
  * A `registry prepare` command line, spelled for whoever is driving.
  *
- * @param args - Everything after `registry prepare`, e.g. the connector key and action.
+ * @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>`.
  * @returns The full command, no trailing newline.
  *
  * @example
  * ```ts
  * prepareCommand('uipath-salesforce-slack', 'send-message-to-user');
- * // -> "npx flow-sdk registry prepare 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"
  * ```
  */
-export declare function prepareCommand(...args: string[]): string;
+export declare function prepareCommand(connectorKey?: string, action?: string, ...rest: string[]): string;
 /**
  * The argument of one `--resolve <field>:<by>=<value>`, single-quoted when the
  * shell would otherwise mangle it.

package/dist/core/cli-spelling.js

@@ -47,18 +47,22 @@ export function cliSpelling(env = ambientEnv()) {
 /**
  * A `registry prepare` command line, spelled for whoever is driving.
  *
- * @param args - Everything after `registry prepare`, e.g. the connector key and action.
+ * @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>`.
  * @returns The full command, no trailing newline.
  *
  * @example
  * ```ts
  * prepareCommand('uipath-salesforce-slack', 'send-message-to-user');
- * // -> "npx flow-sdk registry prepare 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"
  * ```
  */
-export function prepareCommand(...args) {
-    return [cliSpelling(), 'registry', 'prepare', ...args.filter(Boolean)].join(' ');
+export function prepareCommand(connectorKey, action, ...rest) {
+    return [cliSpelling(), 'registry', 'prepare', connectorKey, ...(action ? ['--action', action] : []), ...rest]
+        .filter(Boolean)
+        .join(' ');
 }
 /**
  * Characters that make a `--resolve` argument unsafe to paste unquoted. `[*]`

package/dist/core/lookups.js

@@ -285,7 +285,7 @@ export function refuseLookupToken(value, family, field) {
         `only Flow reads connectors-local/resolutions.json today, so this would be ` +
         `emitted as a raw token where the connector expects an id.\n` +
         `Resolve it first and pass the value:\n` +
-        `  ${prepareCommand()} ${nodeType.replace(/^uipath\.connector\.(?:trigger\.|event\.)?/, '').replace(/\.([^.]+)$/, ' $1')} \\\n` +
+        `  ${prepareCommand()} ${nodeType.replace(/^uipath\.connector\.(?:trigger\.|event\.)?/, '').replace(/\.([^.]+)$/, ' --action $1')} \\\n` +
         `    --resolve ${field}:${by}=${String(wanted)}\n` +
         `then read the id out of connectors-local/resolutions.json.`);
 }

package/dist/decompile-cli.js

@@ -17,6 +17,7 @@
  * agent can run one script for the whole brownfield write-back loop. Pass
  * `--no-pipeline` to skip it.
  */
+import { reportResult } from './cli-result.js';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { decompile } from './decompile.js';
@@ -67,10 +68,12 @@ export function run(argv) {
     const out = opt(argv, '-o') ?? `${baseName(flow)}.flow.ts`;
     writeFileSync(out, ts);
     console.log(`flow-decompile: wrote ${basename(out)}`);
+    reportResult({ path: resolve(out) });
     if (!argv.includes('--no-pipeline')) {
         const pipelinePath = out.replace(/\.flow\.ts$|\.ts$/, '') + '.pipeline.mjs';
         writeFileSync(pipelinePath, pipelineScript(resolve(pos), resolve(out)));
         console.log(`flow-decompile: wrote ${basename(pipelinePath)}`);
+        reportResult({ pipeline: resolve(pipelinePath) });
     }
     return 0;
 }

package/dist/merge-cli.js

@@ -11,8 +11,9 @@
  * omit it for a two-way merge (take the edited graph, re-attach original layout).
  * See merge.ts.
  */
+import { reportResult } from './cli-result.js';
 import { readFileSync, writeFileSync } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, resolve } from 'node:path';
 import { mergeFlow } from './merge.js';
 import { runWhenInvokedDirectly } from './cli-run.js';
 function opt(argv, name) {
@@ -42,6 +43,7 @@ export function run(argv) {
     const out = opt(argv, '-o') ?? 'merged.flow';
     writeFileSync(out, JSON.stringify(merged, null, 2) + '\n');
     console.log(`flow-merge: wrote ${basename(out)} (${(merged.nodes ?? []).length} nodes, ${(merged.edges ?? []).length} edges)`);
+    reportResult({ path: resolve(out), nodes: (merged.nodes ?? []).length, edges: (merged.edges ?? []).length });
     return 0;
 }
 runWhenInvokedDirectly(import.meta.url, 'flow-merge', run);

package/dist/registry/generators/markdown/sections/choosing-object.js

@@ -24,7 +24,7 @@ export function choosingObjectLines(j, nodeType) {
             "casing), then one command matches it deterministically:",
         "",
         "```bash",
-        `npx flow-sdk registry prepare ${connectorKey} ${mdAction} --object <name-as-the-task-said-it>`,
+        `npx flow-sdk registry prepare ${connectorKey} --action ${mdAction} --object <name-as-the-task-said-it>`,
         "```",
         "",
         "The name is matched, never equality-tested: exact, then " +

package/dist/registry/generators/markdown/sections/example.js

@@ -208,7 +208,7 @@ export function exampleLines(j, fields, symbol, invariant, v1def) {
         if (pyTruthy(operation.objectFromDiscovery)) {
             out.push("The descriptor comes from `./connectors-local/` and this " +
                 "import resolves only after " +
-                `\`npx flow-sdk registry prepare ${connectorKey} ${action} ` +
+                `\`npx flow-sdk registry prepare ${connectorKey} --action ${action} ` +
                 "--object <name>` runs. That never blocks authoring: write " +
                 "the step first with the string form and " +
                 "`{ object: '<name-as-the-task-said-it>' }` — `check` " +
@@ -217,7 +217,7 @@ export function exampleLines(j, fields, symbol, invariant, v1def) {
         else {
             out.push("The descriptor comes from `./connectors-local/` and this " +
                 "import resolves only after " +
-                `\`npx flow-sdk registry prepare ${connectorKey} ${action}\` ` +
+                `\`npx flow-sdk registry prepare ${connectorKey} --action ${action}\` ` +
                 "runs. That never blocks authoring: the fields in this " +
                 "catalog are authorable immediately, and `check` flags any " +
                 "input outside them with this same command.");

package/dist/registry/generators/markdown/sections/lookups.js

@@ -128,7 +128,7 @@ export function lookupLines(connectorKey, action, fields, symbol, invariant) {
         out.push("");
         // ONE command carrying every --resolve, and no `--connection-id`.
         out.push("```bash");
-        out.push(`npx flow-sdk registry prepare ${connectorKey} ${action} \\`);
+        out.push(`npx flow-sdk registry prepare ${connectorKey} --action ${action} \\`);
         // The WIRE name (`users[*]`), which is what prepare's lookup table is keyed
         // on — the authoring name (`users`) is refused as RESOLVE_UNKNOWN_FIELD.
         const resolves = resolvable.map(([f, reference]) => {