@uipath/data-fabric-tool 1.195.0 → 1.197.0-preview.59

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 {
@@ -19,26 +19,34 @@ interface ListOptions {
     limit: string;
     offset?: string;
     cursor?: string;
+    folderKey?: string;
 }
 
 interface GetOptions {
     tenant?: string;
+    folderKey?: string;
 }
 
 interface InsertOptions {
     tenant?: string;
     file?: string;
     body?: string;
+    folderKey?: string;
 }
 
 interface UpdateOptions {
     tenant?: string;
     file?: string;
     body?: string;
+    folderKey?: string;
 }
 
 interface DeleteOptions {
     tenant?: string;
+    yes?: boolean;
+    confirm?: boolean;
+    reason?: string;
+    folderKey?: string;
 }
 
 interface QueryOptions {
@@ -48,11 +56,13 @@ interface QueryOptions {
     limit: string;
     offset?: string;
     cursor?: string;
+    folderKey?: string;
 }
 
 interface ImportOptions {
     tenant?: string;
     file?: string;
+    folderKey?: string;
 }
 
 interface BatchResult {
@@ -195,6 +205,10 @@ export const registerRecordsCommand = (program: Command) => {
             "--cursor <cursor>",
             "Pagination cursor from a previous response to fetch the next page",
         )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
+        )
         .examples(RECORDS_LIST_EXAMPLES)
         .trackedAction(
             processContext,
@@ -232,13 +246,18 @@ export const registerRecordsCommand = (program: Command) => {
                 const sdk = await connectOrFail(options.tenant);
                 if (!sdk) return;
 
+                const listPaginationOptions =
+                    options.cursor !== undefined
+                        ? { pageSize, cursor: { value: options.cursor } }
+                        : jumpToPage !== undefined
+                          ? { pageSize, jumpToPage }
+                          : { pageSize };
                 const [listError, result] = await catchError(
                     sdk.entities.getAllRecords(entityId, {
-                        pageSize,
-                        ...(options.cursor !== undefined && {
-                            cursor: { value: options.cursor },
+                        ...listPaginationOptions,
+                        ...(options.folderKey !== undefined && {
+                            folderKey: options.folderKey,
                         }),
-                        ...(jumpToPage !== undefined && { jumpToPage }),
                     }),
                 );
 
@@ -265,6 +284,10 @@ export const registerRecordsCommand = (program: Command) => {
         .addOption(
             createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
         )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
+        )
         .examples(RECORDS_GET_EXAMPLES)
         .trackedAction(
             processContext,
@@ -273,7 +296,13 @@ export const registerRecordsCommand = (program: Command) => {
                 if (!sdk) return;
 
                 const [getError, record] = await catchError(
-                    sdk.entities.getRecordById(entityId, recordId),
+                    sdk.entities.getRecordById(
+                        entityId,
+                        recordId,
+                        options.folderKey !== undefined
+                            ? { folderKey: options.folderKey }
+                            : undefined,
+                    ),
                 );
 
                 if (getError) {
@@ -311,7 +340,11 @@ 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)",
+        )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
         )
         .examples(RECORDS_INSERT_EXAMPLES)
         .trackedAction(
@@ -333,9 +366,18 @@ export const registerRecordsCommand = (program: Command) => {
                     | Record<string, unknown>[];
                 const recordsList = Array.isArray(data) ? data : [data];
 
+                const folderOptions =
+                    options.folderKey !== undefined
+                        ? { folderKey: options.folderKey }
+                        : undefined;
+
                 if (recordsList.length === 1) {
                     const [insertError, result] = await catchError(
-                        sdk.entities.insertRecordById(entityId, recordsList[0]),
+                        sdk.entities.insertRecordById(
+                            entityId,
+                            recordsList[0],
+                            folderOptions,
+                        ),
                     );
 
                     if (insertError) {
@@ -352,7 +394,11 @@ export const registerRecordsCommand = (program: Command) => {
                     });
                 } else {
                     const [insertError, result] = await catchError(
-                        sdk.entities.insertRecordsById(entityId, recordsList),
+                        sdk.entities.insertRecordsById(
+                            entityId,
+                            recordsList,
+                            folderOptions,
+                        ),
                     );
 
                     if (insertError) {
@@ -394,7 +440,11 @@ 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)",
+        )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
         )
         .examples(RECORDS_UPDATE_EXAMPLES)
         .trackedAction(
@@ -416,6 +466,11 @@ export const registerRecordsCommand = (program: Command) => {
                     | Record<string, unknown>[];
                 const recordsList = Array.isArray(data) ? data : [data];
 
+                const folderOptions =
+                    options.folderKey !== undefined
+                        ? { folderKey: options.folderKey }
+                        : undefined;
+
                 if (recordsList.length === 1) {
                     const record = recordsList[0];
                     const recordId =
@@ -432,6 +487,7 @@ export const registerRecordsCommand = (program: Command) => {
                             entityId,
                             String(recordId),
                             record,
+                            folderOptions,
                         ),
                     );
 
@@ -462,6 +518,7 @@ export const registerRecordsCommand = (program: Command) => {
                         sdk.entities.updateRecordsById(
                             entityId,
                             recordsList as EntityRecord[],
+                            folderOptions,
                         ),
                     );
 
@@ -509,7 +566,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>",
@@ -524,6 +581,10 @@ export const registerRecordsCommand = (program: Command) => {
             "--cursor <cursor>",
             "Pagination cursor from a previous response to fetch the next page",
         )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
+        )
         .trackedAction(
             processContext,
             async (entityId: string, options: QueryOptions) => {
@@ -588,14 +649,19 @@ export const registerRecordsCommand = (program: Command) => {
                 const sdk = await connectOrFail(options.tenant);
                 if (!sdk) return;
 
+                const queryPaginationOptions =
+                    options.cursor !== undefined
+                        ? { pageSize, cursor: { value: options.cursor } }
+                        : jumpToPage !== undefined
+                          ? { pageSize, jumpToPage }
+                          : { pageSize };
                 const [queryError, result] = await catchError(
                     sdk.entities.queryRecordsById(entityId, {
                         ...(queryBody !== null && queryBody),
-                        pageSize,
-                        ...(options.cursor !== undefined && {
-                            cursor: { value: options.cursor },
+                        ...queryPaginationOptions,
+                        ...(options.folderKey !== undefined && {
+                            folderKey: options.folderKey,
                         }),
-                        ...(jumpToPage !== undefined && { jumpToPage }),
                     }),
                 );
 
@@ -622,6 +688,10 @@ export const registerRecordsCommand = (program: Command) => {
             createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
         )
         .option("-f, --file <path>", "Path to the CSV file to import")
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
+        )
         .trackedAction(
             processContext,
             async (entityId: string, options: ImportOptions) => {
@@ -651,7 +721,13 @@ export const registerRecordsCommand = (program: Command) => {
                     { type: "text/csv" },
                 );
                 const [importError, result] = await catchError(
-                    sdk.entities.importRecordsById(entityId, csvFile),
+                    sdk.entities.importRecordsById(
+                        entityId,
+                        csvFile,
+                        options.folderKey !== undefined
+                            ? { folderKey: options.folderKey }
+                            : undefined,
+                    ),
                 );
 
                 if (importError) {
@@ -689,6 +765,18 @@ 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",
+        )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
+        )
         .examples(RECORDS_DELETE_EXAMPLES)
         .trackedAction(
             processContext,
@@ -697,11 +785,24 @@ 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;
 
                 const [deleteError, result] = await catchError(
-                    sdk.entities.deleteRecordsById(entityId, recordIds),
+                    sdk.entities.deleteRecordsById(
+                        entityId,
+                        recordIds,
+                        options.folderKey !== undefined
+                            ? { folderKey: options.folderKey }
+                            : undefined,
+                    ),
                 );
 
                 if (deleteError) {
@@ -721,6 +822,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;
     }