@uipath/data-fabric-tool 1.1.0 → 1.196.0

package/src/tool.ts

@@ -1,6 +1,9 @@
 import type { Command } from "commander";
 import pkg from "../package.json" with { type: "json" };
-import { registerChoiceSetsCommand } from "./commands/choice-sets";
+import {
+    registerChoiceSetsCommand,
+    registerChoiceSetValuesCommand,
+} from "./commands/choice-sets";
 import { registerEntitiesCommand } from "./commands/entities";
 import { registerFilesCommand } from "./commands/files";
 import { registerRecordsCommand } from "./commands/records";
@@ -18,4 +21,5 @@ export const registerCommands = async (program: Command): Promise<void> => {
     registerRecordsCommand(program);
     registerFilesCommand(program);
     registerChoiceSetsCommand(program);
+    registerChoiceSetValuesCommand(program);
 };

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

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@uipath/common", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("@uipath/common")>();
+    return {
+        ...actual,
+        OutputFormatter: { success: vi.fn(), error: vi.fn() },
+    };
+});
+
+import { OutputFormatter } from "@uipath/common";
+import { fail, requireDestructiveConfirmation } from "./output";
+
+describe("fail", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("emits a failure result and sets a non-zero exit code", () => {
+        fail("Something broke", "Try again.");
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Something broke",
+                Instructions: "Try again.",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("requireDestructiveConfirmation", () => {
+    const operation = "delete entity 'abc'";
+    const reasonInstruction = "Pass --reason to explain.";
+
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("returns the trimmed reason when --yes and --reason are present", () => {
+        const result = requireDestructiveConfirmation(
+            { yes: true, reason: "  cleanup  " },
+            operation,
+            reasonInstruction,
+        );
+        expect(result).toBe("cleanup");
+        expect(OutputFormatter.error).not.toHaveBeenCalled();
+    });
+
+    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(process.exitCode).toBe(1);
+    });
+
+    it("fails and returns null when --reason is missing or blank", () => {
+        const result = requireDestructiveConfirmation(
+            { yes: true, reason: "   " },
+            operation,
+            reasonInstruction,
+        );
+        expect(result).toBeNull();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Message: "Reason required for destructive operation",
+                Instructions: reasonInstruction,
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});

package/src/utils/output.ts

@@ -0,0 +1,69 @@
+import {
+    OutputFormatter,
+    processContext,
+    RESULTS,
+    requireConfirmation,
+    warnDeprecatedOptionAlias,
+} from "@uipath/common";
+
+/**
+ * Emit a standard failure result and set a non-zero exit code.
+ *
+ * Returns `void` so a handler can halt in one line: `return fail(msg, instr);`
+ * (`processContext.exit` only sets `process.exitCode`, so the caller must still
+ * return to stop execution).
+ */
+export function fail(message: string, instructions: string): void {
+    OutputFormatter.error({
+        Result: RESULTS.Failure,
+        Message: message,
+        Instructions: instructions,
+    });
+    processContext.exit(1);
+}
+
+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 `--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 {
+    // --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;
+    }
+
+    const reason = options.reason?.trim();
+    if (reason === undefined || reason === "") {
+        fail("Reason required for destructive operation", reasonInstruction);
+        return null;
+    }
+
+    return reason;
+}

package/src/utils/sdk-client.spec.ts

@@ -0,0 +1,59 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@uipath/auth", () => ({
+    getLoginStatusAsync: vi.fn(),
+}));
+
+vi.mock("@uipath/uipath-typescript", () => ({
+    UiPath: class {},
+}));
+
+vi.mock("@uipath/common", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("@uipath/common")>();
+    return {
+        ...actual,
+        OutputFormatter: { success: vi.fn(), error: vi.fn() },
+    };
+});
+
+import { getLoginStatusAsync } from "@uipath/auth";
+import { OutputFormatter } from "@uipath/common";
+import { connectOrFail } from "./sdk-client";
+
+describe("connectOrFail", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("returns a client when logged in", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue({
+            loginStatus: "Logged in",
+            accessToken: "token",
+            baseUrl: "https://cloud.uipath.com",
+            organizationName: "org",
+            tenantName: "tenant",
+        } as never);
+
+        const sdk = await connectOrFail();
+        expect(sdk).toBeDefined();
+        expect(OutputFormatter.error).not.toHaveBeenCalled();
+    });
+
+    it("emits a connection error and returns undefined when not logged in", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue({
+            loginStatus: "LoggedOut",
+            hint: "Run 'uip login' first.",
+        } as never);
+
+        const sdk = await connectOrFail();
+        expect(sdk).toBeUndefined();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error connecting to Data Fabric",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});

package/src/utils/sdk-client.ts

@@ -1,5 +1,7 @@
 import { getLoginStatusAsync } from "@uipath/auth";
+import { catchError, extractErrorMessage } from "@uipath/common";
 import { UiPath } from "@uipath/uipath-typescript";
+import { fail } from "./output";
 
 export const createDataFabricClient = async (
     tenantOverride?: string,
@@ -21,3 +23,24 @@ export const createDataFabricClient = async (
         tenantName: tenantOverride ?? status.tenantName,
     });
 };
+
+/**
+ * Create a Data Fabric client, or emit a standard connection error and return
+ * `undefined`. Lets a handler open with: `const sdk = await connectOrFail(t);
+ * if (!sdk) return;`
+ */
+export const connectOrFail = async (
+    tenantOverride?: string,
+): Promise<UiPath | undefined> => {
+    const [clientError, sdk] = await catchError(
+        createDataFabricClient(tenantOverride),
+    );
+    if (clientError) {
+        fail(
+            "Error connecting to Data Fabric",
+            await extractErrorMessage(clientError),
+        );
+        return undefined;
+    }
+    return sdk;
+};

package/src/utils/pagination.ts

@@ -1,10 +0,0 @@
-/** Normalises an SDK pagination cursor to a plain string for CLI output.
- *  The SDK returns `PaginationCursor = { value: string }` but we want
- *  to expose just the string so the user can pass it directly to --cursor. */
-export function extractCursorValue(cursor: unknown): string | undefined {
-    if (cursor === undefined || cursor === null) return undefined;
-    if (typeof cursor === "string") return cursor;
-    const c = cursor as Record<string, unknown>;
-    if (typeof c.value === "string") return c.value;
-    return undefined;
-}