@uipath/data-fabric-tool 1.195.0 → 1.196.0

package/src/commands/records.ts

@@ -9,9 +9,9 @@ import {
 } from "@uipath/common";
 import { getFileSystem } from "@uipath/filesystem";
 import type { EntityRecord } from "@uipath/uipath-typescript";
-import type { Command } from "commander";
+import { type Command, Option } from "commander";
 import { readFileBinary, readJsonInput } from "../utils/input";
-import { fail } from "../utils/output";
+import { fail, requireDestructiveConfirmation } from "../utils/output";
 import { connectOrFail } from "../utils/sdk-client";
 
 interface ListOptions {
@@ -39,6 +39,9 @@ interface UpdateOptions {
 
 interface DeleteOptions {
     tenant?: string;
+    yes?: boolean;
+    confirm?: boolean;
+    reason?: string;
 }
 
 interface QueryOptions {
@@ -311,7 +314,7 @@ export const registerRecordsCommand = (program: Command) => {
         )
         .option(
             "--body <json>",
-            "Inline JSON record data (object or array of objects)",
+            "Inline JSON record data (object or array of objects; use `-` to read from stdin)",
         )
         .examples(RECORDS_INSERT_EXAMPLES)
         .trackedAction(
@@ -394,7 +397,7 @@ export const registerRecordsCommand = (program: Command) => {
         )
         .option(
             "--body <json>",
-            "Inline JSON record data (must include Id field)",
+            "Inline JSON record data (must include Id field; use `-` to read from stdin)",
         )
         .examples(RECORDS_UPDATE_EXAMPLES)
         .trackedAction(
@@ -509,7 +512,7 @@ export const registerRecordsCommand = (program: Command) => {
         )
         .option(
             "--body <json>",
-            "Inline JSON query options (filterGroup, selectedFields, sortOptions, aggregates, groupBy)",
+            "Inline JSON query options (filterGroup, selectedFields, sortOptions, aggregates, groupBy; use `-` to read from stdin)",
         )
         .option(
             "-l, --limit <number>",
@@ -689,6 +692,14 @@ export const registerRecordsCommand = (program: Command) => {
         .addOption(
             createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
         )
+        .option("-y, --yes", "Acknowledge this is an irreversible operation")
+        .addOption(
+            new Option("--confirm", "Deprecated alias for --yes").hideHelp(),
+        )
+        .option(
+            "--reason <reason>",
+            "Reason for the deletion — echoed back in the response so the caller can log it",
+        )
         .examples(RECORDS_DELETE_EXAMPLES)
         .trackedAction(
             processContext,
@@ -697,6 +708,13 @@ export const registerRecordsCommand = (program: Command) => {
                 recordIds: string[],
                 options: DeleteOptions,
             ) => {
+                const reason = requireDestructiveConfirmation(
+                    options,
+                    `delete ${recordIds.length} record(s) from entity '${entityId}'`,
+                    'Pass --reason "<text>" to record why the records are being deleted.',
+                );
+                if (reason === null) return;
+
                 const sdk = await connectOrFail(options.tenant);
                 if (!sdk) return;
 
@@ -721,6 +739,7 @@ export const registerRecordsCommand = (program: Command) => {
                         FailureCount: failureCount,
                         SuccessRecords: r.successRecords ?? [],
                         FailureRecords: r.failureRecords ?? [],
+                        Reason: reason,
                     },
                 });
                 if (failureCount > 0) {

package/src/utils/input.spec.ts

@@ -0,0 +1,127 @@
+import { EventEmitter } from "node:events";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const readFile = vi.fn();
+
+vi.mock("@uipath/filesystem", () => ({
+    getFileSystem: () => ({ readFile }),
+}));
+
+import { readJsonInput } from "./input";
+
+const realStdin = process.stdin;
+const realPlatform = process.platform;
+
+// Replaces process.stdin with a fake stream. Pass null to simulate a TTY (no
+// piped input); pass a string to simulate piped data.
+function mockStdin(data: string | null): void {
+    const stream = new EventEmitter() as unknown as NodeJS.ReadStream;
+    (stream as unknown as { isTTY: boolean }).isTTY = data === null;
+    stream.setEncoding = vi.fn().mockReturnValue(stream);
+    Object.defineProperty(process, "stdin", {
+        value: stream,
+        configurable: true,
+    });
+    if (data !== null) {
+        queueMicrotask(() => {
+            stream.emit("data", data);
+            stream.emit("end");
+        });
+    }
+}
+
+function setPlatform(platform: string): void {
+    Object.defineProperty(process, "platform", {
+        value: platform,
+        configurable: true,
+    });
+}
+
+describe("readJsonInput", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    afterEach(() => {
+        Object.defineProperty(process, "stdin", {
+            value: realStdin,
+            configurable: true,
+        });
+        Object.defineProperty(process, "platform", {
+            value: realPlatform,
+            configurable: true,
+        });
+    });
+
+    it("parses inline JSON", async () => {
+        await expect(readJsonInput(undefined, '{"a":1}')).resolves.toEqual({
+            a: 1,
+        });
+    });
+
+    it("reads and parses a JSON file", async () => {
+        readFile.mockResolvedValue('{"fromFile":true}');
+        await expect(readJsonInput("payload.json")).resolves.toEqual({
+            fromFile: true,
+        });
+        expect(readFile).toHaveBeenCalledWith("payload.json", "utf-8");
+    });
+
+    it("throws the missing-input message when nothing is provided", async () => {
+        await expect(readJsonInput(undefined, undefined)).rejects.toThrow(
+            "Provide either --file <path> or inline data.",
+        );
+    });
+
+    it("uses a custom missing-input message", async () => {
+        await expect(
+            readJsonInput(undefined, undefined, "Provide --body or --file."),
+        ).rejects.toThrow("Provide --body or --file.");
+    });
+
+    it("reads JSON from stdin when --body is `-` (UV-14637)", async () => {
+        // Payload contains `&`, the char that cmd.exe mangles on the CLI line.
+        mockStdin('[{"name":"A&B"}]');
+        await expect(readJsonInput(undefined, "-")).resolves.toEqual([
+            { name: "A&B" },
+        ]);
+        expect(readFile).not.toHaveBeenCalled();
+    });
+
+    it("reads JSON from stdin when --file is `-`", async () => {
+        mockStdin('{"piped":true}');
+        await expect(readJsonInput("-")).resolves.toEqual({ piped: true });
+        expect(readFile).not.toHaveBeenCalled();
+    });
+
+    it("errors when `-` is given but stdin is a TTY", async () => {
+        mockStdin(null);
+        await expect(readJsonInput(undefined, "-")).rejects.toThrow(
+            "Expected JSON on stdin but got none",
+        );
+    });
+
+    it("errors when `-` is given but stdin is empty", async () => {
+        mockStdin("   ");
+        await expect(readJsonInput(undefined, "-")).rejects.toThrow(
+            "Expected JSON on stdin but got none",
+        );
+    });
+
+    it("reports invalid JSON without a Windows hint on non-Windows", async () => {
+        setPlatform("linux");
+        await expect(readJsonInput(undefined, "{bad")).rejects.toThrow(
+            /^Invalid JSON input:/,
+        );
+        await expect(readJsonInput(undefined, "{bad")).rejects.not.toThrow(
+            /cmd\/PowerShell/,
+        );
+    });
+
+    it("appends a shell-quoting hint on Windows", async () => {
+        setPlatform("win32");
+        await expect(readJsonInput(undefined, "{bad")).rejects.toThrow(
+            /cmd\/PowerShell.*--file.*--body -/s,
+        );
+    });
+});

package/src/utils/input.ts

@@ -1,5 +1,8 @@
+import { readStdin } from "@uipath/common";
 import { getFileSystem } from "@uipath/filesystem";
 
+const STDIN_SENTINEL = "-";
+
 export async function readFileBinary(filePath: string): Promise<Uint8Array> {
     const fs = getFileSystem();
     const content = await fs.readFile(filePath);
@@ -17,6 +20,19 @@ export async function readJsonInput(
     if (!filePath && !inline) {
         throw new Error(missingMsg);
     }
+
+    // `--body -` / `--file -` reads the JSON payload from stdin. Stdin bypasses
+    // the shell, so characters like `&` are never mangled by cmd.exe (UV-14637).
+    if (inline === STDIN_SENTINEL || filePath === STDIN_SENTINEL) {
+        const stdinData = await readStdin();
+        if (stdinData === null) {
+            throw new Error(
+                "Expected JSON on stdin but got none. Pipe data in, e.g. `... --body - < payload.json`.",
+            );
+        }
+        return parseJson(stdinData);
+    }
+
     let raw: string;
     if (filePath) {
         const fs = getFileSystem();
@@ -28,5 +44,18 @@ export async function readJsonInput(
     } else {
         raw = inline as string;
     }
-    return JSON.parse(raw);
+    return parseJson(raw);
+}
+
+function parseJson(raw: string): unknown {
+    try {
+        return JSON.parse(raw);
+    } catch (err: unknown) {
+        const detail = err instanceof Error ? err.message : String(err);
+        const hint =
+            process.platform === "win32"
+                ? " On Windows cmd/PowerShell, characters like & | < > ^ split the command — use `--file <path>` or pipe JSON via `--body -`."
+                : "";
+        throw new Error(`Invalid JSON input: ${detail}.${hint}`);
+    }
 }

package/src/utils/output.spec.ts

@@ -31,6 +31,7 @@ describe("fail", () => {
 });
 
 describe("requireDestructiveConfirmation", () => {
+    const operation = "delete entity 'abc'";
     const reasonInstruction = "Pass --reason to explain.";
 
     beforeEach(() => {
@@ -38,32 +39,44 @@ describe("requireDestructiveConfirmation", () => {
         process.exitCode = undefined;
     });
 
-    it("returns the trimmed reason when --confirm and --reason are present", () => {
+    it("returns the trimmed reason when --yes and --reason are present", () => {
         const result = requireDestructiveConfirmation(
-            { confirm: true, reason: "  cleanup  " },
+            { yes: true, reason: "  cleanup  " },
+            operation,
             reasonInstruction,
         );
         expect(result).toBe("cleanup");
         expect(OutputFormatter.error).not.toHaveBeenCalled();
     });
 
-    it("fails and returns null when --confirm is missing", () => {
+    it("accepts the deprecated --confirm alias for --yes", () => {
+        const result = requireDestructiveConfirmation(
+            { confirm: true, reason: "cleanup" },
+            operation,
+            reasonInstruction,
+        );
+        expect(result).toBe("cleanup");
+        expect(OutputFormatter.error).not.toHaveBeenCalled();
+    });
+
+    it("fails and returns null when neither --yes nor --confirm is present", () => {
+        // The confirmation error is emitted by @uipath/common's
+        // requireConfirmation (covered by confirmation.spec.ts); it routes
+        // through common's own OutputFormatter, which this suite's module-level
+        // mock doesn't intercept. Assert the observable contract here.
         const result = requireDestructiveConfirmation(
             { reason: "cleanup" },
+            operation,
             reasonInstruction,
         );
         expect(result).toBeNull();
-        expect(OutputFormatter.error).toHaveBeenCalledWith(
-            expect.objectContaining({
-                Message: "Confirmation required for destructive operation",
-            }),
-        );
         expect(process.exitCode).toBe(1);
     });
 
     it("fails and returns null when --reason is missing or blank", () => {
         const result = requireDestructiveConfirmation(
-            { confirm: true, reason: "   " },
+            { yes: true, reason: "   " },
+            operation,
             reasonInstruction,
         );
         expect(result).toBeNull();

package/src/utils/output.ts

@@ -1,4 +1,10 @@
-import { OutputFormatter, processContext, RESULTS } from "@uipath/common";
+import {
+    OutputFormatter,
+    processContext,
+    RESULTS,
+    requireConfirmation,
+    warnDeprecatedOptionAlias,
+} from "@uipath/common";
 
 /**
  * Emit a standard failure result and set a non-zero exit code.
@@ -17,27 +23,39 @@ export function fail(message: string, instructions: string): void {
 }
 
 export interface DestructiveOptions {
+    yes?: boolean;
+    // Legacy hidden alias for `yes`. The canonical flag is `--yes`; `--confirm`
+    // keeps working (with a deprecation warning) so existing scripts don't break.
     confirm?: boolean;
     reason?: string;
 }
 
 /**
- * Validate the `--confirm`/`--reason` flags required for a destructive
- * operation. On failure, emits the appropriate error, sets the exit code, and
- * returns `null`. On success, returns the trimmed reason.
+ * Validate the `--yes`/`--reason` flags required for a destructive operation.
+ * `--confirm` is accepted as a deprecated alias for `--yes`. On failure, emits
+ * the appropriate structured error, sets the exit code, and returns `null`. On
+ * success, returns the trimmed reason.
  *
+ * @param operation - short description of what will happen, e.g.
+ *   `"delete entity 'abc'"`, surfaced in the confirmation error.
  * @param reasonInstruction - Instruction text shown when `--reason` is missing,
  *   e.g. `'Pass --reason "<text>" to record why the choice set is being deleted.'`
  */
 export function requireDestructiveConfirmation(
     options: DestructiveOptions,
+    operation: string,
     reasonInstruction: string,
 ): string | null {
-    if (options.confirm !== true) {
-        fail(
-            "Confirmation required for destructive operation",
-            "Pass --confirm to acknowledge this is irreversible.",
-        );
+    // --confirm is a deprecated alias for the canonical --yes.
+    if (options.confirm === true && options.yes !== true) {
+        warnDeprecatedOptionAlias("--confirm", "--yes");
+    }
+    if (
+        !requireConfirmation(
+            { yes: options.yes === true || options.confirm === true },
+            operation,
+        )
+    ) {
         return null;
     }