@uipath/tasks-tool 1.201.0-preview.115 → 1.201.0-preview.121

package/src/commands/tasks.spec.ts

@@ -1,9 +1,20 @@
 import { Command } from "commander";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { registerCatalogsCommand } from "./catalogs";
+import { registerCommentsCommand } from "./comments";
+import { registerDataCommand } from "./data";
+import { registerLabelsCommand } from "./labels";
+import { registerMetadataCommand } from "./metadata";
 import { registerTasksCommand } from "./tasks";
 
 vi.mock("../utils/sdk-client", () => ({
     createTasksClient: vi.fn(),
+    createTaskCatalogsClient: vi.fn(),
+}));
+
+vi.mock("./_shared/folder-resolver", () => ({
+    resolveFolderIdByKey: vi.fn(),
+    resolveFolderIdByPath: vi.fn(),
 }));
 
 vi.mock("@uipath/common", async (importOriginal) => {
@@ -18,12 +29,24 @@ vi.mock("@uipath/common", async (importOriginal) => {
 });
 
 import { OutputFormatter } from "@uipath/common";
-import { createTasksClient } from "../utils/sdk-client";
+import {
+    createTaskCatalogsClient,
+    createTasksClient,
+} from "../utils/sdk-client";
+import {
+    resolveFolderIdByKey,
+    resolveFolderIdByPath,
+} from "./_shared/folder-resolver";
 
 function buildProgram(): Command {
     const program = new Command();
     program.name("test").exitOverride();
     registerTasksCommand(program);
+    registerCatalogsCommand(program);
+    registerCommentsCommand(program);
+    registerLabelsCommand(program);
+    registerMetadataCommand(program);
+    registerDataCommand(program);
     return program;
 }
 
@@ -37,6 +60,12 @@ function mockSdk(overrides: Record<string, unknown> = {}) {
             unassign: vi.fn().mockResolvedValue({ success: true, data: [] }),
             complete: vi.fn().mockResolvedValue({ success: true }),
             getUsers: vi.fn().mockResolvedValue([]),
+            getComments: vi.fn().mockResolvedValue([]),
+            createComment: vi.fn().mockResolvedValue({}),
+            saveTags: vi.fn().mockResolvedValue(undefined),
+            editMetadata: vi.fn().mockResolvedValue(undefined),
+            getDataById: vi.fn().mockResolvedValue({}),
+            saveData: vi.fn().mockResolvedValue(undefined),
             ...overrides,
         },
     };
@@ -44,6 +73,19 @@ function mockSdk(overrides: Record<string, unknown> = {}) {
     return sdk;
 }
 
+// Task catalogs live on their own service (createTaskCatalogsClient), not sdk.tasks.
+function mockCatalogs(overrides: Record<string, unknown> = {}) {
+    const catalogs = {
+        getAll: vi.fn().mockResolvedValue([]),
+        getById: vi.fn().mockResolvedValue({}),
+        create: vi.fn().mockResolvedValue({}),
+        updateById: vi.fn().mockResolvedValue(undefined),
+        ...overrides,
+    };
+    vi.mocked(createTaskCatalogsClient).mockReturnValue(catalogs as never);
+    return catalogs;
+}
+
 describe("tasks command registration", () => {
     it("should register all commands on program", () => {
         const program = buildProgram();
@@ -55,6 +97,34 @@ describe("tasks command registration", () => {
         expect(subcommands).toContain("unassign");
         expect(subcommands).toContain("complete");
         expect(subcommands).toContain("users");
+        expect(subcommands).toContain("catalogs");
+        expect(subcommands).toContain("comments");
+        expect(subcommands).toContain("labels");
+        expect(subcommands).toContain("metadata");
+        expect(subcommands).toContain("data");
+    });
+
+    it("should register the catalogs subcommands", () => {
+        const program = buildProgram();
+        const catalogs = program.commands.find((c) => c.name() === "catalogs");
+        const subcommands = catalogs?.commands.map((c) => c.name()) ?? [];
+        expect(subcommands).toEqual(
+            expect.arrayContaining(["list", "get", "create", "update"]),
+        );
+    });
+
+    it("should register the comments subcommands", () => {
+        const program = buildProgram();
+        const comments = program.commands.find((c) => c.name() === "comments");
+        const subcommands = comments?.commands.map((c) => c.name()) ?? [];
+        expect(subcommands).toEqual(expect.arrayContaining(["list", "add"]));
+    });
+
+    it("should register the data subcommands", () => {
+        const program = buildProgram();
+        const data = program.commands.find((c) => c.name() === "data");
+        const subcommands = data?.commands.map((c) => c.name()) ?? [];
+        expect(subcommands).toEqual(expect.arrayContaining(["get", "save"]));
     });
 });
 
@@ -862,3 +932,1488 @@ describe("tasks users", () => {
         expect(process.exitCode).toBe(1);
     });
 });
+
+describe("tasks catalogs list", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should list catalogs for a folder", async () => {
+        const catalogData = [
+            { id: 1, name: "Invoices" },
+            { id: 2, name: "Receipts" },
+        ];
+        mockSdk();
+        const catalogs = mockCatalogs({
+            getAll: vi.fn().mockResolvedValue(catalogData),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "list",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(catalogs.getAll).toHaveBeenCalledWith(
+            expect.objectContaining({ folderId: 42, pageSize: 100 }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "TaskCatalogList",
+                Data: catalogData,
+            }),
+        );
+    });
+
+    it("should apply the --limit option", async () => {
+        mockSdk();
+        mockCatalogs({
+            getAll: vi
+                .fn()
+                .mockResolvedValue([{ id: 1 }, { id: 2 }, { id: 3 }]),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "list",
+            "--folder-id",
+            "42",
+            "--limit",
+            "2",
+        ]);
+
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Code: "TaskCatalogList",
+                Data: [{ id: 1 }, { id: 2 }],
+            }),
+        );
+    });
+
+    it("should reject an invalid --folder-id", async () => {
+        mockSdk();
+        mockCatalogs();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "list",
+            "--folder-id",
+            "abc",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Invalid --folder-id: abc",
+            }),
+        );
+    });
+
+    it("should propagate API errors", async () => {
+        mockSdk();
+        mockCatalogs({
+            getAll: vi.fn().mockRejectedValue(new Error("boom")),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "list",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error listing task catalogs",
+            }),
+        );
+    });
+});
+
+describe("tasks catalogs get", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should get a catalog by id", async () => {
+        const catalog = { id: 7, name: "Invoices" };
+        mockSdk();
+        const catalogs = mockCatalogs({
+            getById: vi.fn().mockResolvedValue(catalog),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "get",
+            "7",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(catalogs.getById).toHaveBeenCalledWith(7, {
+            folderId: 42,
+        });
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Code: "TaskCatalogDetails",
+                Data: catalog,
+            }),
+        );
+    });
+
+    it("should reject an invalid <id>", async () => {
+        mockSdk();
+        mockCatalogs();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "get",
+            "0",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Invalid <id>: 0",
+            }),
+        );
+    });
+
+    it("should propagate API errors", async () => {
+        mockSdk();
+        mockCatalogs({
+            getById: vi.fn().mockRejectedValue(new Error("not found")),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "get",
+            "7",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error getting task catalog '7'",
+            }),
+        );
+    });
+});
+
+describe("tasks catalogs create", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should create a catalog", async () => {
+        const created = { id: 9, name: "New Catalog" };
+        mockSdk();
+        const catalogs = mockCatalogs({
+            create: vi.fn().mockResolvedValue(created),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "create",
+            "--folder-id",
+            "42",
+            "--name",
+            "New Catalog",
+            "--description",
+            "desc",
+        ]);
+
+        expect(catalogs.create).toHaveBeenCalledWith("New Catalog", {
+            folderId: 42,
+            description: "desc",
+        });
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Code: "TaskCatalogCreated",
+                Data: created,
+            }),
+        );
+    });
+
+    it("should fail when --name is missing", async () => {
+        mockSdk();
+
+        const program = buildProgram();
+        await expect(
+            program.parseAsync([
+                "node",
+                "test",
+                "catalogs",
+                "create",
+                "--folder-id",
+                "42",
+            ]),
+        ).rejects.toThrow();
+    });
+
+    it("should pass retention and encryption options", async () => {
+        mockSdk();
+        const catalogs = mockCatalogs();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "create",
+            "--folder-id",
+            "42",
+            "--name",
+            "Invoices",
+            "--encrypted",
+            "--retention-action",
+            "Archive",
+            "--retention-period",
+            "30",
+            "--retention-bucket-id",
+            "7",
+        ]);
+
+        expect(catalogs.create).toHaveBeenCalledWith("Invoices", {
+            folderId: 42,
+            encrypted: true,
+            retentionAction: "Archive",
+            retentionPeriod: 30,
+            retentionBucketId: 7,
+        });
+    });
+
+    it("should reject an invalid --retention-action", async () => {
+        mockSdk();
+        const catalogs = mockCatalogs();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "create",
+            "--folder-id",
+            "42",
+            "--name",
+            "Invoices",
+            "--retention-action",
+            "Nope",
+        ]);
+
+        expect(catalogs.create).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Invalid --retention-action 'Nope'",
+            }),
+        );
+    });
+});
+
+describe("tasks catalogs update", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should update a catalog", async () => {
+        mockSdk();
+        const catalogs = mockCatalogs();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "update",
+            "9",
+            "--folder-id",
+            "42",
+            "--name",
+            "Renamed",
+        ]);
+
+        expect(catalogs.updateById).toHaveBeenCalledWith(9, {
+            folderId: 42,
+            name: "Renamed",
+        });
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "TaskCatalogUpdated" }),
+        );
+    });
+
+    it("should reject an update with no mutable fields", async () => {
+        mockSdk();
+        const catalogs = mockCatalogs();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "update",
+            "9",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(catalogs.updateById).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Message: "No catalog changes provided" }),
+        );
+    });
+
+    it("should reject an empty --retention-action instead of a no-op update", async () => {
+        mockSdk();
+        const catalogs = mockCatalogs();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "update",
+            "9",
+            "--folder-id",
+            "42",
+            "--retention-action",
+            "",
+        ]);
+
+        expect(catalogs.updateById).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Message: "Invalid --retention-action ''",
+            }),
+        );
+    });
+
+    it("should propagate API errors", async () => {
+        mockSdk();
+        mockCatalogs({
+            updateById: vi.fn().mockRejectedValue(new Error("nope")),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "update",
+            "9",
+            "--folder-id",
+            "42",
+            "--name",
+            "Renamed",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error updating task catalog '9'",
+            }),
+        );
+    });
+});
+
+describe("tasks comments", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should list notes for a task", async () => {
+        const noteData = [
+            { id: 1, text: "First" },
+            { id: 2, text: "Second" },
+        ];
+        const sdk = mockSdk({
+            getComments: vi.fn().mockResolvedValue(noteData),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "comments",
+            "list",
+            "5001",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(sdk.tasks.getComments).toHaveBeenCalledWith(
+            5001,
+            expect.objectContaining({ folderId: 42, pageSize: 100 }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "TaskCommentList",
+                Data: noteData,
+            }),
+        );
+    });
+
+    it("should apply the --limit option", async () => {
+        mockSdk({
+            getComments: vi
+                .fn()
+                .mockResolvedValue([{ id: 1 }, { id: 2 }, { id: 3 }]),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "comments",
+            "list",
+            "5001",
+            "--folder-id",
+            "42",
+            "--limit",
+            "2",
+        ]);
+
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Code: "TaskCommentList",
+                Data: [{ id: 1 }, { id: 2 }],
+            }),
+        );
+    });
+
+    it("should reject an invalid <task-id>", async () => {
+        mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "comments",
+            "list",
+            "abc",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Invalid <task-id>: abc",
+            }),
+        );
+    });
+});
+
+describe("tasks add-comment", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should create a note", async () => {
+        const created = { id: 9, text: "Escalated" };
+        const sdk = mockSdk({
+            createComment: vi.fn().mockResolvedValue(created),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "comments",
+            "add",
+            "5001",
+            "--folder-id",
+            "42",
+            "--text",
+            "Escalated",
+        ]);
+
+        expect(sdk.tasks.createComment).toHaveBeenCalledWith(
+            5001,
+            "Escalated",
+            {
+                folderId: 42,
+            },
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Code: "TaskCommentCreated",
+                Data: created,
+            }),
+        );
+    });
+
+    it("should reject empty --text", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "comments",
+            "add",
+            "5001",
+            "--folder-id",
+            "42",
+            "--text",
+            "",
+        ]);
+
+        expect(sdk.tasks.createComment).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "--text cannot be empty",
+            }),
+        );
+    });
+
+    it("should propagate API errors", async () => {
+        mockSdk({
+            createComment: vi.fn().mockRejectedValue(new Error("nope")),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "comments",
+            "add",
+            "5001",
+            "--folder-id",
+            "42",
+            "--text",
+            "hi",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error adding comment to task '5001'",
+            }),
+        );
+    });
+});
+
+describe("tasks labels", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should set tags", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "labels",
+            "5001",
+            "--folder-id",
+            "42",
+            "--labels",
+            '[{"name":"urgent"}]',
+        ]);
+
+        expect(sdk.tasks.saveTags).toHaveBeenCalledWith(
+            5001,
+            [{ name: "urgent" }],
+            { folderId: 42 },
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "TaskLabelsSaved" }),
+        );
+    });
+
+    it("should clear tags with an empty array", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "labels",
+            "5001",
+            "--folder-id",
+            "42",
+            "--labels",
+            "[]",
+        ]);
+
+        expect(sdk.tasks.saveTags).toHaveBeenCalledWith(5001, [], {
+            folderId: 42,
+        });
+    });
+
+    it("should reject invalid JSON", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "labels",
+            "5001",
+            "--folder-id",
+            "42",
+            "--labels",
+            "not-json",
+        ]);
+
+        expect(sdk.tasks.saveTags).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Message: "Invalid JSON in --labels" }),
+        );
+    });
+
+    it("should reject non-array tags", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "labels",
+            "5001",
+            "--folder-id",
+            "42",
+            "--labels",
+            '{"name":"urgent"}',
+        ]);
+
+        expect(sdk.tasks.saveTags).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Message: "--labels must be a JSON array",
+            }),
+        );
+    });
+
+    it("should propagate API errors", async () => {
+        mockSdk({ saveTags: vi.fn().mockRejectedValue(new Error("nope")) });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "labels",
+            "5001",
+            "--folder-id",
+            "42",
+            "--labels",
+            "[]",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error saving labels on task '5001'",
+            }),
+        );
+    });
+});
+
+describe("tasks metadata", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should edit metadata", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "metadata",
+            "5001",
+            "--folder-id",
+            "42",
+            "--title",
+            "Review invoice",
+            "--priority",
+            "High",
+        ]);
+
+        expect(sdk.tasks.editMetadata).toHaveBeenCalledWith(5001, {
+            folderId: 42,
+            title: "Review invoice",
+            priority: "High",
+        });
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "TaskMetadataEdited" }),
+        );
+    });
+
+    it("should reject an invalid <task-id>", async () => {
+        mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "metadata",
+            "abc",
+            "--folder-id",
+            "42",
+            "--title",
+            "x",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Message: "Invalid <task-id>: abc" }),
+        );
+    });
+
+    it("should reject an invalid priority", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "metadata",
+            "5001",
+            "--folder-id",
+            "42",
+            "--priority",
+            "Urgent",
+        ]);
+
+        expect(sdk.tasks.editMetadata).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Message: "Invalid priority 'Urgent'" }),
+        );
+    });
+
+    it("should propagate API errors", async () => {
+        mockSdk({ editMetadata: vi.fn().mockRejectedValue(new Error("nope")) });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "metadata",
+            "5001",
+            "--folder-id",
+            "42",
+            "--title",
+            "x",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error editing metadata on task '5001'",
+            }),
+        );
+    });
+
+    it("should pass --catalog-id", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "metadata",
+            "5001",
+            "--folder-id",
+            "42",
+            "--catalog-id",
+            "9",
+        ]);
+
+        expect(sdk.tasks.editMetadata).toHaveBeenCalledWith(5001, {
+            folderId: 42,
+            taskCatalogId: 9,
+        });
+    });
+
+    it("should pass --unset-catalog", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "metadata",
+            "5001",
+            "--folder-id",
+            "42",
+            "--unset-catalog",
+        ]);
+
+        expect(sdk.tasks.editMetadata).toHaveBeenCalledWith(5001, {
+            folderId: 42,
+            unlinkTaskCatalog: true,
+        });
+    });
+
+    it("should pass --note", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "metadata",
+            "5001",
+            "--folder-id",
+            "42",
+            "--note",
+            "reclassified",
+        ]);
+
+        expect(sdk.tasks.editMetadata).toHaveBeenCalledWith(5001, {
+            folderId: 42,
+            noteText: "reclassified",
+        });
+    });
+
+    it("should reject --catalog-id together with --unset-catalog", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "metadata",
+            "5001",
+            "--folder-id",
+            "42",
+            "--catalog-id",
+            "9",
+            "--unset-catalog",
+        ]);
+
+        expect(sdk.tasks.editMetadata).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message:
+                    "--catalog-id and --unset-catalog cannot be used together",
+            }),
+        );
+    });
+
+    it("should reject an edit with no metadata flags", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "metadata",
+            "5001",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(sdk.tasks.editMetadata).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "No metadata changes provided",
+            }),
+        );
+    });
+
+    it("should reject an empty --priority instead of a no-op edit", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "metadata",
+            "5001",
+            "--folder-id",
+            "42",
+            "--priority",
+            "",
+        ]);
+
+        expect(sdk.tasks.editMetadata).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Message: "Invalid priority ''" }),
+        );
+    });
+
+    it("should reject an empty --catalog-id instead of a no-op edit", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "metadata",
+            "5001",
+            "--folder-id",
+            "42",
+            "--catalog-id",
+            "",
+        ]);
+
+        expect(sdk.tasks.editMetadata).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalled();
+    });
+});
+
+describe("tasks data", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should get task data", async () => {
+        const taskData = { id: 5001, data: { amount: 1200 } };
+        const sdk = mockSdk({
+            getDataById: vi.fn().mockResolvedValue(taskData),
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "data",
+            "get",
+            "5001",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(sdk.tasks.getDataById).toHaveBeenCalledWith(5001, {
+            folderId: 42,
+        });
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "TaskData", Data: taskData }),
+        );
+    });
+
+    it("should reject an invalid <task-id>", async () => {
+        mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "data",
+            "get",
+            "abc",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Message: "Invalid <task-id>: abc" }),
+        );
+    });
+
+    it("should propagate API errors", async () => {
+        mockSdk({ getDataById: vi.fn().mockRejectedValue(new Error("nope")) });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "data",
+            "get",
+            "5001",
+            "--folder-id",
+            "42",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error getting data for task '5001'",
+            }),
+        );
+    });
+});
+
+describe("tasks save-data", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should save task data", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "data",
+            "save",
+            "5001",
+            "--folder-id",
+            "42",
+            "--data",
+            '{"amount":1200}',
+        ]);
+
+        expect(sdk.tasks.saveData).toHaveBeenCalledWith(
+            5001,
+            { amount: 1200 },
+            { folderId: 42 },
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "TaskDataSaved" }),
+        );
+    });
+
+    it("should reject invalid JSON", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "data",
+            "save",
+            "5001",
+            "--folder-id",
+            "42",
+            "--data",
+            "not-json",
+        ]);
+
+        expect(sdk.tasks.saveData).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Message: "Invalid JSON in --data" }),
+        );
+    });
+
+    it("should reject non-object data", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "data",
+            "save",
+            "5001",
+            "--folder-id",
+            "42",
+            "--data",
+            "[1,2,3]",
+        ]);
+
+        expect(sdk.tasks.saveData).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Message: "--data must be a JSON object",
+            }),
+        );
+    });
+
+    it("should propagate API errors", async () => {
+        mockSdk({ saveData: vi.fn().mockRejectedValue(new Error("nope")) });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "data",
+            "save",
+            "5001",
+            "--folder-id",
+            "42",
+            "--data",
+            "{}",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error saving data for task '5001'",
+            }),
+        );
+    });
+});
+
+describe("folder scope options", () => {
+    const FOLDER_KEY = "12345678-1234-1234-1234-123456789abc";
+    const originalTTY = process.stdout.isTTY;
+
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    afterEach(() => {
+        process.stdout.isTTY = originalTTY;
+    });
+
+    it("should register --folder-path and --folder-key on every folder-scoped command", () => {
+        const program = buildProgram();
+        const folderScoped: Array<[string, string | undefined]> = [
+            ["list", undefined],
+            ["get", undefined],
+            ["complete", undefined],
+            ["users", undefined],
+            ["labels", undefined],
+            ["metadata", undefined],
+            ["catalogs", "list"],
+            ["catalogs", "get"],
+            ["catalogs", "create"],
+            ["catalogs", "update"],
+            ["comments", "list"],
+            ["comments", "add"],
+            ["data", "get"],
+            ["data", "save"],
+        ];
+
+        for (const [name, subName] of folderScoped) {
+            let command = program.commands.find((c) => c.name() === name);
+            if (subName) {
+                command = command?.commands.find((c) => c.name() === subName);
+            }
+            const flags = command?.options.map((o) => o.long) ?? [];
+            expect(flags, `${name} ${subName ?? ""}`).toContain(
+                "--folder-path",
+            );
+            expect(flags, `${name} ${subName ?? ""}`).toContain("--folder-key");
+        }
+    });
+
+    it("should reject --folder-path combined with --folder-id at parse time", async () => {
+        const program = buildProgram();
+        await expect(
+            program.parseAsync([
+                "node",
+                "test",
+                "list",
+                "--folder-id",
+                "42",
+                "--folder-path",
+                "Shared",
+            ]),
+        ).rejects.toThrow(/cannot be used with/);
+        expect(createTasksClient).not.toHaveBeenCalled();
+    });
+
+    it("should reject --folder-path combined with --folder-key at parse time", async () => {
+        const program = buildProgram();
+        await expect(
+            program.parseAsync([
+                "node",
+                "test",
+                "list",
+                "--folder-path",
+                "Shared",
+                "--folder-key",
+                FOLDER_KEY,
+            ]),
+        ).rejects.toThrow(/cannot be used with/);
+        expect(createTasksClient).not.toHaveBeenCalled();
+    });
+
+    it("should reject --folder-key combined with --folder-id at parse time", async () => {
+        const program = buildProgram();
+        await expect(
+            program.parseAsync([
+                "node",
+                "test",
+                "list",
+                "--folder-id",
+                "42",
+                "--folder-key",
+                FOLDER_KEY,
+            ]),
+        ).rejects.toThrow(/cannot be used with/);
+        expect(createTasksClient).not.toHaveBeenCalled();
+    });
+
+    it("should resolve --folder-key for list and pass the numeric id", async () => {
+        const sdk = mockSdk();
+        vi.mocked(resolveFolderIdByKey).mockResolvedValue(55);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "list",
+            "--folder-key",
+            FOLDER_KEY,
+        ]);
+
+        expect(resolveFolderIdByKey).toHaveBeenCalledWith(
+            FOLDER_KEY,
+            undefined,
+        );
+        expect(sdk.tasks.getAll).toHaveBeenCalledWith(
+            expect.objectContaining({ folderId: 55 }),
+        );
+    });
+
+    it("should resolve --folder-path for list and pass the numeric id", async () => {
+        const sdk = mockSdk();
+        vi.mocked(resolveFolderIdByPath).mockResolvedValue(77);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "list",
+            "--folder-path",
+            "Shared/Finance",
+        ]);
+
+        expect(resolveFolderIdByPath).toHaveBeenCalledWith(
+            "Shared/Finance",
+            undefined,
+        );
+        expect(sdk.tasks.getAll).toHaveBeenCalledWith(
+            expect.objectContaining({ folderId: 77 }),
+        );
+    });
+
+    it("should stop list without calling the API when resolution fails", async () => {
+        const sdk = mockSdk();
+        vi.mocked(resolveFolderIdByKey).mockResolvedValue(null);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "list",
+            "--folder-key",
+            FOLDER_KEY,
+        ]);
+
+        expect(sdk.tasks.getAll).not.toHaveBeenCalled();
+    });
+
+    it("should accept --task-type with --folder-path on get", async () => {
+        const sdk = mockSdk();
+        vi.mocked(resolveFolderIdByPath).mockResolvedValue(77);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "get",
+            "123",
+            "--task-type",
+            "FormTask",
+            "--folder-path",
+            "Shared",
+        ]);
+
+        expect(sdk.tasks.getById).toHaveBeenCalledWith(
+            123,
+            expect.objectContaining({ taskType: "FormTask" }),
+            77,
+        );
+    });
+
+    it("should reject --task-type on get without any folder option", async () => {
+        mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "get",
+            "123",
+            "--task-type",
+            "FormTask",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Message: "A folder is required when --task-type is specified",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should resolve --folder-path for complete", async () => {
+        const sdk = mockSdk();
+        vi.mocked(resolveFolderIdByPath).mockResolvedValue(88);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "complete",
+            "5",
+            "--type",
+            "FormTask",
+            "--folder-path",
+            "Shared",
+        ]);
+
+        expect(sdk.tasks.complete).toHaveBeenCalledWith(
+            expect.objectContaining({ taskId: 5, type: "FormTask" }),
+            88,
+        );
+    });
+
+    it("should fail loud on complete without a folder when not interactive", async () => {
+        process.stdout.isTTY = false;
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "complete",
+            "5",
+            "--type",
+            "FormTask",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Message: "A folder is required" }),
+        );
+        expect(process.exitCode).toBe(1);
+        expect(sdk.tasks.complete).not.toHaveBeenCalled();
+    });
+
+    it("should resolve --folder-path for users", async () => {
+        const sdk = mockSdk();
+        vi.mocked(resolveFolderIdByPath).mockResolvedValue(99);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "users",
+            "--folder-path",
+            "Shared/Finance",
+        ]);
+
+        expect(sdk.tasks.getUsers).toHaveBeenCalledWith(
+            99,
+            expect.objectContaining({ pageSize: 100 }),
+        );
+    });
+
+    it("should reject the users folder-id argument combined with --folder-key", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "users",
+            "42",
+            "--folder-key",
+            FOLDER_KEY,
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Message:
+                    "The folder-id argument cannot be used with --folder-path or --folder-key",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+        expect(sdk.tasks.getUsers).not.toHaveBeenCalled();
+    });
+
+    it("should reject --folder-path combined with --folder-key on users at parse time", async () => {
+        const program = buildProgram();
+        await expect(
+            program.parseAsync([
+                "node",
+                "test",
+                "users",
+                "--folder-path",
+                "Shared",
+                "--folder-key",
+                FOLDER_KEY,
+            ]),
+        ).rejects.toThrow(/cannot be used with/);
+        expect(createTasksClient).not.toHaveBeenCalled();
+    });
+
+    it("should fail loud on users without a folder when not interactive", async () => {
+        process.stdout.isTTY = false;
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync(["node", "test", "users"]);
+
+        // The guidance must name the positional argument, not --folder-id,
+        // which this command does not register.
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Message: "A folder is required",
+                Instructions: expect.stringContaining("folder-id argument"),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+        expect(sdk.tasks.getUsers).not.toHaveBeenCalled();
+    });
+
+    it("should resolve --folder-key for catalogs list", async () => {
+        mockSdk();
+        const catalogs = mockCatalogs();
+        vi.mocked(resolveFolderIdByKey).mockResolvedValue(66);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "catalogs",
+            "list",
+            "--folder-key",
+            FOLDER_KEY,
+        ]);
+
+        expect(resolveFolderIdByKey).toHaveBeenCalledWith(
+            FOLDER_KEY,
+            undefined,
+        );
+        expect(catalogs.getAll).toHaveBeenCalledWith(
+            expect.objectContaining({ folderId: 66 }),
+        );
+    });
+});