@uipath/maestro-builder-sdk 6.9.5 → 6.10.1

package/dist/cli/common.d.ts

@@ -1,4 +1,4 @@
-import { Option } from 'commander';
+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;
@@ -6,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`?
@@ -34,3 +52,20 @@ export declare function inferCheckMode(family: 'flow' | 'case' | 'bpmn', input:
  * 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

@@ -5,6 +5,10 @@ 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)
@@ -13,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')
@@ -98,3 +157,33 @@ export function inferCheckMode(family, input, source, compiled) {
 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/decompile.js

@@ -1923,15 +1923,37 @@ function armCb(param, segs) {
  * fall-off End the serializer always appends; it now decompiles to an explicit
  * `.return({}, { version })` so the End's exact definition version survives the
  * round trip (design §5.3) — recompiling emits the identical node.
+ *
+ * An End written by the designer or the product CLI carries its returned value
+ * ONLY in `outputs[name].source` — it writes no `variableUpdates` row. Reading
+ * updates alone decompiled such an End to `.return({})` and silently dropped the
+ * value it returned (a Decision's two Ends returning `'nice day'` /
+ * `'bring a jacket'` both came back empty). So an output whose source is not the
+ * identity `$vars.<name>` mapping `endOutputs` fills in is a returned value too.
  */
 function returnSeg(node, ctx) {
     const updates = ctx.flow.variables?.variableUpdates?.[node.id] ?? [];
     const opts = returnOptsArg(node);
-    if (updates.length === 0)
-        return `.return({}${opts})`;
     const entries = updates.map((u) => `${key(u.variableId)}: ${emitVal(u.expression, ctx.imp, ctx.inputNames)}`);
+    const written = new Set(updates.map((u) => u.variableId));
+    for (const [name, out] of Object.entries(node.outputs ?? {})) {
+        if (written.has(name))
+            continue;
+        const source = out?.source;
+        const raw = unwrapSource(source);
+        if (raw === undefined || isIdentityEndSource(raw, name))
+            continue;
+        entries.push(`${key(name)}: ${emitVal(source, ctx.imp, ctx.inputNames)}`);
+    }
+    if (entries.length === 0)
+        return `.return({}${opts})`;
     return `.return({ ${entries.join(', ')} }${opts})`;
 }
+/** The fill-in mapping `endOutputs` writes for an output no `.return` named: `=js:$vars.<name>`. */
+function isIdentityEndSource(raw, name) {
+    const body = raw.startsWith('=js:') ? raw.slice(4) : raw;
+    return body.trim() === `$vars.${name}`;
+}
 /**
  * The options argument for a `.return(...)` — `version`, plus the End's `name`
  * and `label` when they are not what the serializer would derive on its own.

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]) => {

package/dist/registry/generators/markdown/sections/schema-dynamic.js

@@ -54,14 +54,14 @@ export function schemaDynamicLines(j, nodeType) {
     out.push("> ```bash");
     // ONE spelling on every page, the one `check` prints; no `--connection-id`.
     if (discovery) {
-        out.push(`> npx flow-sdk registry prepare ${key} ${action} ${supply}`);
+        out.push(`> npx flow-sdk registry prepare ${key} --action ${action} ${supply}`);
     }
     else if (supply) {
-        out.push(`> npx flow-sdk registry prepare ${key} ${action} \\`);
+        out.push(`> npx flow-sdk registry prepare ${key} --action ${action} \\`);
         out.push(`>   ${supply}`);
     }
     else {
-        out.push(`> npx flow-sdk registry prepare ${key} ${action}`);
+        out.push(`> npx flow-sdk registry prepare ${key} --action ${action}`);
     }
     out.push("> ```");
     out.push(">");

package/dist/registry/library-build/cli.js

@@ -13,6 +13,8 @@
  * tenant, which is the only way its exit codes can be pinned.
  */
 import { rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { reportResult } from "../../cli-result.js";
 import { UsageError, exitCodeOf, messageOf } from "../errors.js";
 import { consoleReporter } from "../reporter.js";
 import { OfflineUipClient, defaultUipClient } from "../uip/client.js";
@@ -173,6 +175,7 @@ export async function run(argv, deps = {}) {
             }
         }
         reporter.info("Done!");
+        reportResult({ outputDir: resolve(options.outputDir) });
         return 0;
     }
     catch (error) {

package/dist/registry/materialize-cli.js

@@ -1,3 +1,5 @@
+import { resolve } from "node:path";
+import { reportResult } from "../cli-result.js";
 import { exitCodeOf, messageOf } from "./errors.js";
 import { materializeRegistry } from "./materializer.js";
 /**
@@ -51,6 +53,11 @@ export async function run(argv) {
             checkSymbols: argv.includes("--check-symbols"),
             checkOrphans: argv.includes("--check-orphans"),
         });
+        reportResult({
+            libraryJson: resolve(libraryJsonPath),
+            ...(libraryMarkdownPath ? { libraryMarkdown: resolve(libraryMarkdownPath) } : {}),
+            ...(connectorsPath ? { connectors: resolve(connectorsPath) } : {}),
+        });
         return 0;
     }
     catch (error) {

package/dist/registry/path-cli.js

@@ -1,3 +1,4 @@
+import { reportResult } from '../cli-result.js';
 import { join } from "node:path";
 import { CURRENT_LINK, currentEntrySha, libraryCacheRoot, resolveCachedLibrary, resolveCachedMarkdown, } from "./cache.js";
 /**
@@ -27,7 +28,11 @@ export async function run(argv) {
     const libraryJson = resolveCachedLibrary();
     const libraryMarkdown = resolveCachedMarkdown();
     const sha256 = currentEntrySha();
-    const single = (value) => {
+    // With one flag, `--json` reports just that field, like the text output. A
+    // caller capturing one value (`uip maestro registry path --sha --output
+    // plain`, which prints each Data value) must still get exactly one.
+    const single = (field, value) => {
+        reportResult({ [field]: value ?? null });
         if (!value) {
             console.error("No connector library in the cache yet. Run `flow-sdk registry pull`.");
             return 1;
@@ -36,20 +41,22 @@ export async function run(argv) {
         return 0;
     };
     if (argv.includes("--library-json"))
-        return single(libraryJson);
+        return single("libraryJson", libraryJson);
     if (argv.includes("--library-md"))
-        return single(libraryMarkdown);
+        return single("libraryMarkdown", libraryMarkdown);
     if (argv.includes("--root"))
-        return single(root);
+        return single("root", root);
     if (argv.includes("--sha"))
-        return single(sha256);
-    console.log(JSON.stringify({
+        return single("sha256", sha256);
+    const all = {
         root,
         current: join(root, CURRENT_LINK),
         sha256: sha256 ?? null,
         libraryJson: libraryJson ?? null,
         libraryMarkdown: libraryMarkdown ?? null,
-    }, null, 2));
+    };
+    reportResult(all);
+    console.log(JSON.stringify(all, null, 2));
     // Not an error: a caller asking for the whole picture is entitled to be told
     // the cache is empty, rather than getting a non-zero exit for a plain report.
     return 0;