@uipath/data-fabric-tool 1.198.0 → 1.199.0-preview.104

package/src/commands/directory.ts

@@ -0,0 +1,325 @@
+import {
+    type CommandExample,
+    catchError,
+    createHiddenDeprecatedTenantOption,
+    extractErrorMessage,
+    OutputFormatter,
+    processContext,
+    RESULTS,
+} from "@uipath/common";
+import { type Command, Option } from "commander";
+import { fail, requireDestructiveConfirmation } from "../utils/output";
+import { connectOrFail } from "../utils/sdk-client";
+
+// The directory/role support types (enums, option/response aliases) are missing
+// from the SDK's export barrel: the main entry exports no DataFabric symbols, and
+// the /entities subpath exports only the two service classes, not these types. So
+// derive the principal-type input from the client's method signature instead of
+// importing it. Fix belongs in @uipath/uipath-typescript (export these types).
+type DataFabricClient = NonNullable<Awaited<ReturnType<typeof connectOrFail>>>;
+type PrincipalTypeInput = Parameters<
+    DataFabricClient["entities"]["directory"]["assignRoles"]
+>[1];
+
+const PRINCIPAL_TYPES = ["User", "Group", "Application"] as const;
+
+interface ListOptions {
+    tenant?: string;
+    limit: string;
+    offset: string;
+}
+
+interface AssignOptions {
+    tenant?: string;
+    type: string;
+    roleIds: string;
+    replace?: boolean;
+    uiAccess: boolean;
+}
+
+interface RevokeOptions {
+    tenant?: string;
+    yes?: boolean;
+    confirm?: boolean;
+    reason?: string;
+}
+
+const DIRECTORY_LIST_EXAMPLES: CommandExample[] = [
+    {
+        Description:
+            "List Data Fabric directory principals and their assigned roles.",
+        Command: "uip df directory list --limit 50",
+        Output: {
+            Code: "DirectoryList",
+            Data: {
+                TotalCount: 1,
+                Results: [
+                    {
+                        ExternalId: "d1e2f3a4-0000-0000-0000-000000000001",
+                        Name: "Automation Users",
+                        Type: "Group",
+                        Roles: [
+                            {
+                                Id: "c1d2e3f4-0000-0000-0000-000000000001",
+                                Name: "DataWriter",
+                            },
+                        ],
+                        IsUIEnabled: true,
+                    },
+                ],
+            },
+        },
+    },
+];
+
+const DIRECTORY_ASSIGN_ROLES_EXAMPLES: CommandExample[] = [
+    {
+        Description: "Assign a Data Fabric role to an identity group.",
+        Command:
+            "uip df directory assign-roles d1e2f3a4-0000-0000-0000-000000000001 --type Group --role-ids c1d2e3f4-0000-0000-0000-000000000001",
+        Output: {
+            Code: "DirectoryRolesAssigned",
+            Data: [
+                {
+                    PrincipalId: "d1e2f3a4-0000-0000-0000-000000000001",
+                    RoleIds: ["c1d2e3f4-0000-0000-0000-000000000001"],
+                },
+            ],
+        },
+    },
+];
+
+const DIRECTORY_REVOKE_ROLES_EXAMPLES: CommandExample[] = [
+    {
+        Description: "Revoke all direct Data Fabric roles from a principal.",
+        Command:
+            'uip df directory revoke-roles d1e2f3a4-0000-0000-0000-000000000001 --yes --reason "Offboarding"',
+        Output: {
+            Code: "DirectoryRolesRevoked",
+            Data: {
+                PrincipalIds: ["d1e2f3a4-0000-0000-0000-000000000001"],
+                Reason: "Offboarding",
+            },
+        },
+    },
+];
+
+const parsePrincipalType = (value: string): PrincipalTypeInput | null => {
+    const match = PRINCIPAL_TYPES.find(
+        (t) => t.toLowerCase() === value.toLowerCase(),
+    );
+    return match !== undefined ? (match as PrincipalTypeInput) : null;
+};
+
+const parseRoleIds = (value: string): string[] =>
+    value
+        .split(",")
+        .map((id) => id.trim())
+        .filter((id) => id !== "");
+
+// Strict integer parse: `Number.parseInt` accepts trailing junk ("10abc" → 10)
+// and truncates floats ("1.5" → 1), so validate the whole string is an integer
+// first. Returns null on anything that isn't a plain (optionally signed) integer.
+const parseIntegerOption = (value: string): number | null => {
+    const trimmed = value.trim();
+    if (!/^-?\d+$/.test(trimmed)) {
+        return null;
+    }
+    const parsed = Number(trimmed);
+    return Number.isSafeInteger(parsed) ? parsed : null;
+};
+
+/**
+ * Internal manage-access surface — hidden from help output and not part of
+ * the documented `uip df` command set.
+ */
+export const registerDirectoryCommand = (program: Command) => {
+    const directory = program
+        .command("directory", { hidden: true })
+        .description(
+            "Manage Data Fabric directory principals and their role assignments",
+        );
+
+    directory
+        .command("list")
+        .description(
+            "List Data Fabric directory principals and their assigned roles",
+        )
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
+        .option(
+            "--limit <count>",
+            "Maximum number of principals to return",
+            "50",
+        )
+        .option("--offset <count>", "Number of principals to skip", "0")
+        .examples(DIRECTORY_LIST_EXAMPLES)
+        .trackedAction(processContext, async (options: ListOptions) => {
+            const top = parseIntegerOption(options.limit);
+            if (top === null || top <= 0) {
+                return fail(
+                    `Invalid --limit value '${options.limit}'`,
+                    "Provide a positive integer for --limit.",
+                );
+            }
+
+            const skip = parseIntegerOption(options.offset);
+            if (skip === null || skip < 0) {
+                return fail(
+                    `Invalid --offset value '${options.offset}'`,
+                    "Provide a non-negative integer for --offset.",
+                );
+            }
+
+            const sdk = await connectOrFail(options.tenant);
+            if (!sdk) return;
+
+            const [listError, result] = await catchError(
+                sdk.entities.directory.list({ skip, top }),
+            );
+
+            if (listError) {
+                return fail(
+                    "Error listing directory principals",
+                    await extractErrorMessage(listError),
+                );
+            }
+
+            OutputFormatter.success({
+                Result: RESULTS.Success,
+                Code: "DirectoryList",
+                Data: result,
+            });
+        });
+
+    directory
+        .command("assign-roles")
+        .description("Assign Data Fabric roles to one or more principals")
+        .argument("<principal-ids...>", "Principal external ID(s)")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
+        .requiredOption(
+            "--type <type>",
+            "Principal type: User, Group, or Application",
+        )
+        .requiredOption(
+            "--role-ids <ids>",
+            "Comma-separated Data Fabric role IDs to assign (see 'df roles list')",
+        )
+        .option(
+            "--replace",
+            "Replace the principals' existing Data Fabric roles instead of preserving them",
+        )
+        .option(
+            "--no-ui-access",
+            "Do not enable Data Fabric UI access for the assigned principals",
+        )
+        .examples(DIRECTORY_ASSIGN_ROLES_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (principalIds: string[], options: AssignOptions) => {
+                const principalType = parsePrincipalType(options.type);
+                if (principalType === null) {
+                    return fail(
+                        `Invalid --type value '${options.type}'`,
+                        `Provide one of: ${PRINCIPAL_TYPES.join(", ")}.`,
+                    );
+                }
+
+                const roleIds = parseRoleIds(options.roleIds);
+                if (roleIds.length === 0) {
+                    return fail(
+                        "No role IDs provided",
+                        "Provide at least one role ID via --role-ids. Use 'df roles list' to see available roles.",
+                    );
+                }
+
+                const sdk = await connectOrFail(options.tenant);
+                if (!sdk) return;
+
+                const [assignError, result] = await catchError(
+                    sdk.entities.directory.assignRoles(
+                        principalIds,
+                        principalType,
+                        roleIds,
+                        {
+                            ...(options.replace === true && {
+                                preserveExisting: false,
+                            }),
+                            ...(options.uiAccess === false && {
+                                uiEnabled: false,
+                            }),
+                        },
+                    ),
+                );
+
+                if (assignError) {
+                    return fail(
+                        "Error assigning roles",
+                        await extractErrorMessage(assignError),
+                    );
+                }
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "DirectoryRolesAssigned",
+                    Data: result ?? [],
+                });
+            },
+        );
+
+    directory
+        .command("revoke-roles")
+        .description(
+            "Revoke all direct Data Fabric roles from one or more principals",
+        )
+        .argument("<principal-ids...>", "Principal external ID(s)")
+        .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 revocation — echoed back in the response so the caller can log it",
+        )
+        .examples(DIRECTORY_REVOKE_ROLES_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (principalIds: string[], options: RevokeOptions) => {
+                const reason = requireDestructiveConfirmation(
+                    options,
+                    `revoke all Data Fabric roles from ${principalIds.length} principal(s)`,
+                    'Pass --reason "<text>" to record why the roles are being revoked.',
+                );
+                if (reason === null) return;
+
+                const sdk = await connectOrFail(options.tenant);
+                if (!sdk) return;
+
+                const [revokeError] = await catchError(
+                    sdk.entities.directory.revokeRoles(principalIds),
+                );
+
+                if (revokeError) {
+                    return fail(
+                        "Error revoking roles",
+                        await extractErrorMessage(revokeError),
+                    );
+                }
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "DirectoryRolesRevoked",
+                    Data: {
+                        PrincipalIds: principalIds,
+                        Reason: reason,
+                    },
+                });
+            },
+        );
+};

package/src/commands/entities.spec.ts

@@ -329,6 +329,44 @@ describe("entities create", () => {
         );
     });
 
+    it("should accept MULTILINE_MAX as a field type on create", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.create).mockResolvedValue("doc-entity-id");
+        vi.mocked(readJsonInput).mockResolvedValue({
+            fields: [
+                { fieldName: "title", type: "STRING" },
+                { fieldName: "body", type: "MULTILINE_MAX" },
+            ],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "create",
+            "Document",
+            "--body",
+            '{"fields":[{"fieldName":"title","type":"STRING"},{"fieldName":"body","type":"MULTILINE_MAX"}]}',
+        ]);
+
+        expect(sdk.entities.create).toHaveBeenCalledWith(
+            "Document",
+            [
+                { fieldName: "title", type: "STRING" },
+                { fieldName: "body", type: "MULTILINE_MAX" },
+            ],
+            undefined,
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "EntityCreated",
+                Data: expect.objectContaining({ ID: "doc-entity-id" }),
+            }),
+        );
+    });
+
     it("should create entity with displayName, description, and isRbacEnabled", async () => {
         const sdk = mockSdk();
         vi.mocked(sdk.entities.create).mockResolvedValue("entity-with-opts");
@@ -733,6 +771,117 @@ describe("entities create", () => {
         );
         expect(process.exitCode).toBe(1);
     });
+
+    it("should reject an entity name that starts with a digit", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            fields: [{ fieldName: "title", type: "STRING" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "create",
+            "1Bad",
+            "--body",
+            '{"fields":[{"fieldName":"title","type":"STRING"}]}',
+        ]);
+
+        expect(sdk.entities.create).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining("Invalid entity name '1Bad'"),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should reject an entity name that is a reserved keyword", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            fields: [{ fieldName: "title", type: "STRING" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "create",
+            "Class",
+            "--body",
+            '{"fields":[{"fieldName":"title","type":"STRING"}]}',
+        ]);
+
+        expect(sdk.entities.create).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining("reserved C# or VB keyword"),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should reject a fieldName that is a reserved system field", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            fields: [{ fieldName: "Id", type: "STRING" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "create",
+            "MyEntity",
+            "--body",
+            '{"fields":[{"fieldName":"Id","type":"STRING"}]}',
+        ]);
+
+        expect(sdk.entities.create).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining("Field name 'Id' is reserved"),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should reject a UI-broken field type", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            fields: [{ fieldName: "count", type: "INTEGER" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "create",
+            "MyEntity",
+            "--body",
+            '{"fields":[{"fieldName":"count","type":"INTEGER"}]}',
+        ]);
+
+        expect(sdk.entities.create).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining(
+                    "type 'INTEGER' which the Data Fabric UI cannot render",
+                ),
+                Instructions: expect.stringContaining("DECIMAL"),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
 });
 
 describe("entities update", () => {
@@ -1540,7 +1689,7 @@ describe("entities update", () => {
         vi.mocked(readJsonInput).mockResolvedValue({
             addFields: [
                 { fieldName: "dup", type: "STRING" },
-                { fieldName: "dup", type: "INTEGER" },
+                { fieldName: "dup", type: "DECIMAL" },
             ],
         });
 
@@ -1552,7 +1701,7 @@ describe("entities update", () => {
             "update",
             "entity-id",
             "--body",
-            '{"addFields":[{"fieldName":"dup","type":"STRING"},{"fieldName":"dup","type":"INTEGER"}]}',
+            '{"addFields":[{"fieldName":"dup","type":"STRING"},{"fieldName":"dup","type":"DECIMAL"}]}',
         ]);
 
         expect(sdk.entities.updateById).not.toHaveBeenCalled();
@@ -1826,6 +1975,94 @@ describe("entities update", () => {
         );
         expect(process.exitCode).toBe(1);
     });
+
+    it("should reject a UI-broken type in addFields", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            addFields: [{ fieldName: "count", type: "FLOAT" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "update",
+            "entity-id",
+            "--body",
+            '{"addFields":[{"fieldName":"count","type":"FLOAT"}]}',
+        ]);
+
+        expect(sdk.entities.updateById).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining(
+                    "type 'FLOAT' which the Data Fabric UI cannot render",
+                ),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should reject a reserved keyword in addFields", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            addFields: [{ fieldName: "New", type: "STRING" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "update",
+            "entity-id",
+            "--body",
+            '{"addFields":[{"fieldName":"New","type":"STRING"}]}',
+        ]);
+
+        expect(sdk.entities.updateById).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining("reserved C# or VB keyword"),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should reject isUnique in updateFields", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            updateFields: [{ id: "field-uuid", isUnique: true }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "update",
+            "entity-id",
+            "--body",
+            '{"updateFields":[{"id":"field-uuid","isUnique":true}]}',
+        ]);
+
+        expect(sdk.entities.updateById).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining(
+                    "Cannot change 'isUnique' on field 'field-uuid'",
+                ),
+                Instructions: expect.stringContaining(
+                    "fixed at field creation",
+                ),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
 });
 
 describe("entities delete", () => {