dataiku-sdk 0.10.1 → 0.12.0

package/dist/src/cli/commands/dataset.js

@@ -0,0 +1,288 @@
+import { buildDatasetCloneSettings, } from "../../resources/datasets.js";
+import { deepMerge, } from "../../utils/deep-merge.js";
+import { jsonInput, num, schemaColumnsInput, } from "../coerce.js";
+import { datasetSourceSummary, } from "../helpers/dataset.js";
+import { moveCreatedItemsToZone, resolveFlowZoneIdFromFlags, } from "../helpers/flow-zone.js";
+import { enqueueCliWarning, readIfExists, skipResult, } from "../output.js";
+import { requireArgs, UsageError, } from "../usage.js";
+export const datasetCommands = {
+    list: {
+        handler: (c, _a, f) => c.datasets.list(f["project-key"]),
+        usage: "dss dataset list [--project-key KEY]",
+        description: "List all datasets in a project.",
+        examples: ["dss dataset list", "dss dataset list --project-key MYPROJ",],
+    },
+    rename: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 2, "dss dataset rename <oldName> <newName> [--project-key KEY]");
+            await c.datasets.rename(a[0], a[1], f["project-key"]);
+            return { renamed: a[0], to: a[1], };
+        },
+        usage: "dss dataset rename <oldName> <newName> [--project-key KEY]",
+        description: "Rename a dataset (updates downstream flow references).",
+        examples: ["dss dataset rename old_ds new_ds",],
+    },
+    "list-partitions": {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss dataset list-partitions <name> [--project-key KEY]");
+            return c.datasets.listPartitions(a[0], f["project-key"]);
+        },
+        usage: "dss dataset list-partitions <name> [--project-key KEY]",
+        description: "List the partitions of a partitioned dataset.",
+        examples: ["dss dataset list-partitions events",],
+    },
+    clear: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss dataset clear <name> [--partitions SPEC] [--project-key KEY]");
+            const partitions = f["partitions"];
+            await c.datasets.clear(a[0], partitions, f["project-key"]);
+            return { cleared: a[0], partitions: partitions ?? "ALL", };
+        },
+        usage: "dss dataset clear <name> [--partitions SPEC] [--project-key KEY]",
+        description: "Clear a dataset's data (all, or a partition spec); keeps the dataset.",
+        examples: ["dss dataset clear staging", "dss dataset clear events --partitions 2024-01",],
+    },
+    get: {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss dataset get <name>");
+            return c.datasets.get(a[0], f["project-key"]);
+        },
+        usage: "dss dataset get <name> [--project-key KEY]",
+        description: "Get full settings for a dataset.",
+        examples: ["dss dataset get orders", "dss dataset get orders --project-key MYPROJ",],
+    },
+    schema: {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss dataset schema <name>");
+            return c.datasets.schema(a[0], f["project-key"]);
+        },
+        usage: "dss dataset schema <name> [--project-key KEY]",
+        description: "Show the column schema of a dataset.",
+        examples: ["dss dataset schema orders",],
+    },
+    source: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss dataset source <name>");
+            return datasetSourceSummary(await c.datasets.get(a[0], f["project-key"]));
+        },
+        usage: "dss dataset source <name> [--project-key KEY]",
+        description: "Show backing connection, catalog/schema/table, path, and format for a dataset.",
+        examples: ["dss dataset source orders",],
+    },
+    "refresh-schema": {
+        handler: async (c, a, f) => {
+            const usage = "dss dataset refresh-schema <name> [--data JSON | --data-file PATH | --stdin] [--dry-run] [--project-key KEY]";
+            requireArgs(a, 1, usage);
+            const columns = schemaColumnsInput(f, usage);
+            const pk = f["project-key"];
+            if (f["dry-run"] === true) {
+                const current = await c.datasets.schema(a[0], pk);
+                return {
+                    dryRun: true,
+                    action: "refresh-schema",
+                    resource: "dataset",
+                    name: a[0],
+                    current,
+                    next: { columns, },
+                };
+            }
+            await c.datasets.updateSchema(a[0], columns, pk);
+            return { updated: a[0], resource: "dataset", schema: { columns, }, };
+        },
+        usage: "dss dataset refresh-schema <name> [--data JSON | --data-file PATH | --stdin] [--dry-run] [--project-key KEY]",
+        description: "Replace a dataset schema through the DSS schema endpoint.",
+        examples: [
+            `dss dataset refresh-schema orders --data '{"columns":[{"name":"id","type":"bigint"}]}' --dry-run`,
+        ],
+    },
+    "validate-build": {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss dataset validate-build <name>");
+            return c.datasets.validateBuildSettings(a[0], f["project-key"]);
+        },
+        usage: "dss dataset validate-build <name> [--project-key KEY]",
+        description: "Check common dataset settings that can make file-backed builds fail.",
+        examples: ["dss dataset validate-build orders",],
+    },
+    preview: {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss dataset preview <name>");
+            return c.datasets.preview(a[0], {
+                maxRows: num(f["max-rows"]),
+                projectKey: f["project-key"],
+                timeoutMs: num(f["timeout"]),
+            });
+        },
+        usage: "dss dataset preview <name> [--max-rows N] [--rows N] [--project-key KEY] [--timeout MS]",
+        description: "Preview dataset rows (--rows is an alias for --max-rows).",
+        examples: ["dss dataset preview orders", "dss dataset preview orders --rows 5",],
+    },
+    metadata: {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss dataset metadata <name>");
+            return c.datasets.metadata(a[0], f["project-key"]);
+        },
+        usage: "dss dataset metadata <name> [--project-key KEY]",
+        description: "Get dataset-level metadata.",
+        examples: ["dss dataset metadata orders",],
+    },
+    download: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss dataset download <name>");
+            const result = await c.datasets.download(a[0], {
+                outputPath: f["output"],
+                projectKey: f["project-key"],
+                limit: num(f["limit"]),
+            });
+            if (result.truncated) {
+                enqueueCliWarning({
+                    code: "dataset_download_truncated",
+                    message: `Download of '${a[0]}' stopped at the ${result.limit}-row cap; the dataset has more rows. `
+                        + "Re-run with --limit N for more, or read inside a recipe (get_dataframe) for the full data.",
+                    dataset: a[0],
+                    rows: result.rows,
+                    limit: result.limit,
+                    path: result.path,
+                });
+            }
+            if (!f["output"]) {
+                enqueueCliWarning({
+                    code: "dataset_download_default_location",
+                    message: `No --output was given, so '${a[0]}' was written to '${result.path}' in the current directory. `
+                        + "Pass --output PATH to control the destination and avoid writing into your working tree.",
+                    dataset: a[0],
+                    path: result.path,
+                });
+            }
+            return result;
+        },
+        usage: "dss dataset download <name> [--output PATH] [--limit N] [--project-key KEY]",
+        description: "Download up to --limit rows (default 100k) as CSV; returns { path, rows, truncated, limit }. When truncated, a dataset_download_truncated warning is written to stderr; when --output is omitted, a dataset_download_default_location warning names the file's path in the working directory so the write is never silent.",
+        examples: ["dss dataset download orders", "dss dataset download orders --output ./data/",],
+    },
+    create: {
+        handler: async (c, _a, f) => {
+            const pk = f["project-key"];
+            const name = f["name"];
+            const connection = f["connection"];
+            const dsType = f["type"];
+            if (!name || !connection || !dsType) {
+                throw new UsageError("--name, --connection, and --type are required. Usage: dss dataset create --name NAME --connection CONN --type TYPE");
+            }
+            const payload = {
+                datasetName: name,
+                connection,
+                dsType,
+                projectKey: pk,
+            };
+            const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
+            if (f["if-not-exists"] === true || f["dry-run"] === true) {
+                const list = await c.datasets.list(pk);
+                const existing = list.find((d) => d.name === name);
+                if (existing && f["if-not-exists"] === true && f["dry-run"] !== true) {
+                    return skipResult("dataset", name, "exists", { current: existing, });
+                }
+                if (f["dry-run"] === true) {
+                    return {
+                        dryRun: true,
+                        action: "create",
+                        resource: "dataset",
+                        name,
+                        payload,
+                        ...(existing ? { current: existing, } : {}),
+                        ...(zoneId ? { zoneId, zoneMove: [{ objectId: name, objectType: "DATASET", },], } : {}),
+                    };
+                }
+            }
+            await c.datasets.create(payload);
+            const moved = await moveCreatedItemsToZone(c, f, [{ objectId: name, objectType: "DATASET", },], pk);
+            return { created: name, resource: "dataset", ...moved, };
+        },
+        usage: "dss dataset create --name NAME --connection CONN --type TYPE [--zone ZONE|--zone-id ID] [--if-not-exists] [--dry-run] [--project-key KEY]",
+        description: "Create a new dataset.",
+        examples: [
+            "dss dataset create --name orders --connection filesystem --type Filesystem",
+            "dss dataset create --name orders --connection filesystem --type Filesystem --zone Experiments --dry-run",
+        ],
+    },
+    clone: {
+        handler: async (c, a, f) => {
+            const usage = "dss dataset clone <source> <target> [--path PATH] [--table TABLE] [--metastore-table TABLE] [--allow-same-path] [--zone ZONE|--zone-id ID] [--dry-run] [--project-key KEY]";
+            requireArgs(a, 2, usage);
+            const pk = f["project-key"];
+            const opts = {
+                projectKey: pk,
+                path: f["path"],
+                table: f["table"],
+                metastoreTableName: f["metastore-table"],
+                allowSamePath: f["allow-same-path"] === true,
+            };
+            const current = await c.datasets.get(a[0], pk);
+            const next = buildDatasetCloneSettings(current, a[1], pk ?? c.resolveProjectKey(pk), opts);
+            const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
+            if (f["dry-run"] === true) {
+                return {
+                    dryRun: true,
+                    action: "clone",
+                    resource: "dataset",
+                    source: a[0],
+                    target: a[1],
+                    current,
+                    next,
+                    ...(zoneId ? { zoneId, zoneMove: [{ objectId: a[1], objectType: "DATASET", },], } : {}),
+                };
+            }
+            const cloned = await c.datasets.clone(a[0], a[1], opts);
+            const moved = await moveCreatedItemsToZone(c, f, [{ objectId: a[1], objectType: "DATASET", },], pk);
+            return { ...cloned, resource: "dataset", ...moved, };
+        },
+        usage: "dss dataset clone <source> <target> [--path PATH] [--table TABLE] [--metastore-table TABLE] [--allow-same-path] [--zone ZONE|--zone-id ID] [--dry-run] [--project-key KEY]",
+        description: "Clone dataset settings into a new dataset, with storage/table overrides.",
+        examples: [
+            "dss dataset clone source_ds experiment_ds --path /dataiku/TEST/experiment_ds --dry-run",
+            "dss dataset clone source_ds experiment_ds --allow-same-path",
+        ],
+    },
+    delete: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss dataset delete <name>");
+            const pk = f["project-key"];
+            if (f["dry-run"] === true || f["if-exists"] === true) {
+                const current = await readIfExists(() => c.datasets.get(a[0], pk));
+                if (!current)
+                    return skipResult("dataset", a[0], "missing");
+                if (f["dry-run"] === true) {
+                    return { dryRun: true, action: "delete", resource: "dataset", name: a[0], current, };
+                }
+            }
+            await c.datasets.delete(a[0], pk);
+            return { deleted: a[0], resource: "dataset", };
+        },
+        usage: "dss dataset delete <name> [--if-exists] [--dry-run] [--project-key KEY]",
+        description: "Delete a dataset.",
+        examples: ["dss dataset delete orders", "dss dataset delete orders --if-exists",],
+    },
+    update: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin]");
+            const data = jsonInput(f);
+            if (!data) {
+                throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin]");
+            }
+            const pk = f["project-key"];
+            if (f["dry-run"] === true) {
+                const current = await c.datasets.get(a[0], pk);
+                const next = deepMerge(current, data);
+                return { dryRun: true, action: "update", resource: "dataset", name: a[0], current, next, };
+            }
+            await c.datasets.update(a[0], data, pk);
+            return { updated: a[0], resource: "dataset", };
+        },
+        usage: "dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin] [--dry-run] [--project-key KEY]",
+        description: "Update dataset settings via JSON merge.",
+        examples: [
+            'dss dataset update orders --data \'{"tags":["production"]}\' --dry-run',
+            "echo '{\"tags\":[]}' | dss dataset update orders --stdin",
+        ],
+    },
+};

package/dist/src/cli/commands/discussion.d.ts

@@ -0,0 +1,2 @@
+import type { CommandMeta } from "../types.js";
+export declare const discussionCommands: Record<string, CommandMeta>;

package/dist/src/cli/commands/discussion.js

@@ -0,0 +1,47 @@
+import { requireArgs, UsageError, } from "../usage.js";
+export const discussionCommands = {
+    list: {
+        handler: (c, a, f) => {
+            requireArgs(a, 2, "dss discussion list <objectType> <objectId> [--project-key KEY]");
+            return c.discussions.list(a[0], a[1], f["project-key"]);
+        },
+        usage: "dss discussion list <objectType> <objectId> [--project-key KEY]",
+        description: "List discussions attached to a project object.",
+        examples: ["dss discussion list DATASET customers",],
+    },
+    get: {
+        handler: (c, a, f) => {
+            requireArgs(a, 3, "dss discussion get <objectType> <objectId> <discussionId> [--project-key KEY]");
+            return c.discussions.get(a[0], a[1], a[2], f["project-key"]);
+        },
+        usage: "dss discussion get <objectType> <objectId> <discussionId> [--project-key KEY]",
+        description: "Get one discussion with its replies.",
+        examples: ["dss discussion get DATASET customers d123",],
+    },
+    create: {
+        handler: (c, a, f) => {
+            requireArgs(a, 2, "dss discussion create <objectType> <objectId> --topic TEXT --reply TEXT [--project-key KEY]");
+            const topic = f["topic"];
+            const reply = f["reply"];
+            if (!topic || !reply) {
+                throw new UsageError("--topic and --reply are required.", "missing_required_flag");
+            }
+            return c.discussions.create(a[0], a[1], topic, reply, f["project-key"]);
+        },
+        usage: "dss discussion create <objectType> <objectId> --topic TEXT --reply TEXT [--project-key KEY]",
+        description: "Create a discussion with its first reply.",
+        examples: ["dss discussion create DATASET customers --topic Schema --reply Please-review",],
+    },
+    reply: {
+        handler: (c, a, f) => {
+            requireArgs(a, 3, "dss discussion reply <objectType> <objectId> <discussionId> --text TEXT [--project-key KEY]");
+            const text = f["text"];
+            if (!text)
+                throw new UsageError("--text is required.", "missing_required_flag");
+            return c.discussions.reply(a[0], a[1], a[2], text, f["project-key"]);
+        },
+        usage: "dss discussion reply <objectType> <objectId> <discussionId> --text TEXT [--project-key KEY]",
+        description: "Add a reply to an existing discussion.",
+        examples: ["dss discussion reply DATASET customers d123 --text Done",],
+    },
+};

package/dist/src/cli/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+import type { CommandMeta } from "../types.js";
+export declare const doctorCommands: Record<string, CommandMeta>;

package/dist/src/cli/commands/doctor.js

@@ -0,0 +1,9 @@
+import { runDoctor, } from "../doctor.js";
+export const doctorCommands = {
+    run: {
+        handler: async (_c, _a, f) => (await runDoctor(f)).result,
+        usage: "dss doctor [--project-key KEY] [--capabilities] [--fast]",
+        description: "Run JSON diagnostics for DSS credentials, connectivity, and project access.",
+        examples: ["dss doctor", "dss doctor --project-key MYPROJ", "dss doctor --capabilities --fast",],
+    },
+};

package/dist/src/cli/commands/flow-zone.d.ts

@@ -0,0 +1,2 @@
+import type { CommandMeta } from "../types.js";
+export declare const flowZoneCommands: Record<string, CommandMeta>;

package/dist/src/cli/commands/flow-zone.js

@@ -0,0 +1,282 @@
+import { deepMerge, } from "../../utils/deep-merge.js";
+import { ensureFlowZonePlanTarget, findFlowZoneForPlan, flowZoneColor, flowZoneContains, flowZoneCurrentPosition, flowZoneDetailSummary, flowZoneId, flowZoneMoveItems, flowZoneName, flowZoneOrganizeStep, flowZonePlanItemKeys, flowZonePruneItems, flowZoneSamePosition, flowZoneSummary, readFlowZoneOrganizePlan, resolveFlowZoneIdFromFlags, throwFlowZoneValidationError, validateFlowZoneOrganizeObjects, } from "../helpers/flow-zone.js";
+import { readIfExists, skipResult, } from "../output.js";
+import { requireArgs, UsageError, } from "../usage.js";
+export const flowZoneCommands = {
+    list: {
+        handler: async (c, _a, f) => {
+            const zones = await c.flowZones.list(f["project-key"]);
+            if (f["summary"] !== true)
+                return zones;
+            const objects = flowZoneMoveItems(f);
+            const object = objects.length === 1 ? objects[0] : undefined;
+            return zones.map((zone) => flowZoneSummary(zone, object));
+        },
+        usage: "dss flow-zone list [--summary] [--object TYPE:ID] [--project-key KEY]",
+        description: "List flow zones in a project, optionally as compact summaries.",
+        examples: ["dss flow-zone list", "dss flow-zone list --summary --object RECIPE:compute_orders",],
+    },
+    find: {
+        handler: async (c, a, f) => {
+            const zones = await c.flowZones.list(f["project-key"]);
+            const objects = flowZoneMoveItems(f);
+            const query = a[0]?.trim();
+            if (query && objects.length === 0) {
+                const normalized = query.toLowerCase();
+                return zones
+                    .filter((zone) => zone.id.toLowerCase().includes(normalized)
+                    || zone.name.toLowerCase().includes(normalized))
+                    .map((zone) => flowZoneDetailSummary(zone));
+            }
+            if (objects.length !== 1) {
+                throw new UsageError("Exactly one zone name/id or object is required. Use <name>, --object TYPE:ID, --dataset DS, or --recipe R.");
+            }
+            const object = objects[0];
+            return zones
+                .filter((zone) => flowZoneContains(zone, object))
+                .map((zone) => flowZoneSummary(zone, object));
+        },
+        usage: "dss flow-zone find [name-or-id] [--object TYPE:ID | --dataset DS | --recipe R | --folder F] [--project-key KEY]",
+        description: "Find flow zones by name/id or by contained flow object.",
+        examples: [
+            "dss flow-zone find ATH_SNW_MAP_FRG49",
+            "dss flow-zone find --object RECIPE:compute_orders",
+            "dss flow-zone find --dataset orders",
+        ],
+    },
+    get: {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss flow-zone get <id>");
+            return c.flowZones.get(flowZoneId(a[0]), f["project-key"]);
+        },
+        usage: "dss flow-zone get <id> [--project-key KEY]",
+        description: "Get a flow zone by id.",
+        examples: ["dss flow-zone get ZONE_ID",],
+    },
+    create: {
+        handler: async (c, _a, f) => {
+            const pk = f["project-key"];
+            const name = flowZoneName(f["name"]);
+            const payload = {
+                name,
+                color: flowZoneColor(f["color"]),
+                projectKey: pk,
+            };
+            if (f["if-not-exists"] === true || f["dry-run"] === true) {
+                const list = await c.flowZones.list(pk);
+                const existing = list.find((zone) => zone.name === name);
+                if (existing && f["if-not-exists"] === true && f["dry-run"] !== true) {
+                    return skipResult("flow-zone", existing.id, "exists", { current: existing, });
+                }
+                if (f["dry-run"] === true) {
+                    return {
+                        dryRun: true,
+                        action: "create",
+                        resource: "flow-zone",
+                        name,
+                        payload,
+                        ...(existing ? { current: existing, } : {}),
+                    };
+                }
+            }
+            const created = await c.flowZones.create(payload);
+            return { created: created.id, resource: "flow-zone", ...created, };
+        },
+        usage: "dss flow-zone create --name NAME [--color #RRGGBB] [--if-not-exists] [--dry-run] [--project-key KEY]",
+        description: "Create a flow zone.",
+        examples: [
+            "dss flow-zone create --name Exports",
+            "dss flow-zone create --name Exports --color '#2ab1ac' --dry-run",
+        ],
+    },
+    update: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss flow-zone update <id> [--name NAME] [--color #RRGGBB]");
+            if (typeof f["name"] !== "string" && typeof f["color"] !== "string") {
+                throw new UsageError("--name and/or --color is required.");
+            }
+            const zoneId = flowZoneId(a[0]);
+            const pk = f["project-key"];
+            const patch = {
+                name: typeof f["name"] === "string" ? flowZoneName(f["name"]) : undefined,
+                color: flowZoneColor(f["color"]),
+                projectKey: pk,
+            };
+            if (f["dry-run"] === true) {
+                const current = await c.flowZones.get(zoneId, pk);
+                const next = deepMerge(current, patch);
+                return { dryRun: true, action: "update", resource: "flow-zone", id: zoneId, current, next, };
+            }
+            return c.flowZones.update(zoneId, patch);
+        },
+        usage: "dss flow-zone update <id> [--name NAME] [--color #RRGGBB] [--dry-run] [--project-key KEY]",
+        description: "Update flow zone settings.",
+        examples: ["dss flow-zone update ZONE_ID --name Exports --color '#2ab1ac' --dry-run",],
+    },
+    delete: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss flow-zone delete <id>");
+            const zoneId = flowZoneId(a[0]);
+            if (f["dry-run"] === true || f["if-exists"] === true) {
+                const current = await readIfExists(() => c.flowZones.get(zoneId, f["project-key"]));
+                if (!current)
+                    return skipResult("flow-zone", zoneId, "missing");
+                if (f["dry-run"] === true) {
+                    return { dryRun: true, action: "delete", resource: "flow-zone", id: zoneId, current, };
+                }
+            }
+            await c.flowZones.delete(zoneId, f["project-key"]);
+            return { deleted: zoneId, resource: "flow-zone", };
+        },
+        usage: "dss flow-zone delete <id> [--if-exists] [--dry-run] [--project-key KEY]",
+        description: "Delete a flow zone. DSS moves zone items back to the default zone.",
+        examples: [
+            "dss flow-zone delete ZONE_ID --dry-run",
+            "dss flow-zone delete ZONE_ID --if-exists",
+        ],
+    },
+    move: {
+        handler: async (c, a, f) => {
+            const pk = f["project-key"];
+            const zoneId = a[0] ? flowZoneId(a[0]) : await resolveFlowZoneIdFromFlags(c, f, pk);
+            if (!zoneId) {
+                throw new UsageError("A zone id or --zone/--zone-id is required. Usage: dss flow-zone move <id> [--dataset DS] [--recipe R] [--folder F] [--object TYPE:ID]");
+            }
+            const items = flowZoneMoveItems(f);
+            if (items.length === 0) {
+                throw new UsageError("At least one object is required. Use --dataset, --recipe, --folder, or --object TYPE:ID.");
+            }
+            if (f["dry-run"] === true) {
+                return {
+                    dryRun: true,
+                    action: "move",
+                    resource: "flow-zone",
+                    id: zoneId,
+                    items,
+                };
+            }
+            return c.flowZones.moveItems(zoneId, items, pk);
+        },
+        usage: "dss flow-zone move [id] [--zone ZONE|--zone-id ID] [--dataset DS[,DS2]] [--recipe R] [--folder F] [--object TYPE:ID] [--dry-run] [--project-key KEY]",
+        description: "Move datasets, recipes, managed folders, or other flow objects into a zone by id or --zone name.",
+        examples: [
+            "dss flow-zone move ZONE_ID --dataset orders --dry-run",
+            "dss flow-zone move --zone ATH_SNW_MAP_FRG49 --dataset raw_orders,clean_orders --recipe prepare_orders",
+            "dss flow-zone move ZONE_ID --folder FOLDER_ID",
+            "dss flow-zone move ZONE_ID --object SAVED_MODEL:model_id",
+        ],
+    },
+    organize: {
+        handler: async (c, _a, f) => {
+            const usage = "dss flow-zone organize (--data JSON|--data-file PATH|--file PATH|--stdin) [--sync] [--validate-objects] [--dry-run] [--project-key KEY]";
+            const pk = f["project-key"];
+            const plan = readFlowZoneOrganizePlan(f, usage);
+            const sync = f["sync"] === true;
+            const validateObjects = f["validate-objects"] === true;
+            const zones = await c.flowZones.list(pk);
+            const plannedItemKeys = flowZonePlanItemKeys(plan);
+            const planned = plan.zones.map((zonePlan) => flowZoneOrganizeStep(zonePlan, findFlowZoneForPlan(zones, zonePlan), sync, plannedItemKeys));
+            const validation = validateObjects
+                ? await validateFlowZoneOrganizeObjects(c, plan, pk)
+                : undefined;
+            if (validation)
+                throwFlowZoneValidationError(validation);
+            const itemCount = plan.zones.reduce((count, zonePlan) => count + zonePlan.items.length, 0);
+            const pruneItemCount = planned.reduce((count, step) => {
+                const pruneItems = Array.isArray(step.pruneItems) ? step.pruneItems : [];
+                return count + pruneItems.length;
+            }, 0);
+            if (f["dry-run"] === true) {
+                return {
+                    dryRun: true,
+                    action: "organize",
+                    resource: "flow-zone",
+                    projectKey: pk,
+                    sync,
+                    validateObjects,
+                    zoneCount: plan.zones.length,
+                    itemCount,
+                    pruneItemCount,
+                    ...(validation ? { validation, } : {}),
+                    planned,
+                };
+            }
+            const currentZones = [...zones,];
+            const created = [];
+            const updated = [];
+            const moved = [];
+            const pruned = [];
+            for (const zonePlan of plan.zones) {
+                let zone = findFlowZoneForPlan(currentZones, zonePlan);
+                ensureFlowZonePlanTarget(zonePlan, zone);
+                const pruneItems = sync ? flowZonePruneItems(zone, plannedItemKeys) : [];
+                if (!zone) {
+                    zone = await c.flowZones.create({
+                        name: zonePlan.name,
+                        color: zonePlan.color,
+                        position: zonePlan.position,
+                        projectKey: pk,
+                    });
+                    currentZones.push(zone);
+                    created.push(zone);
+                }
+                else {
+                    const patch = {
+                        ...(zonePlan.name && zonePlan.name !== zone.name ? { name: zonePlan.name, } : {}),
+                        ...(zonePlan.color && zonePlan.color !== zone.color ? { color: zonePlan.color, } : {}),
+                        ...(zonePlan.position !== undefined
+                            && !flowZoneSamePosition(flowZoneCurrentPosition(zone), zonePlan.position)
+                            ? { position: zonePlan.position, }
+                            : {}),
+                        projectKey: pk,
+                    };
+                    if (patch.name !== undefined || patch.color !== undefined || patch.position !== undefined) {
+                        zone = await c.flowZones.update(zone.id, patch);
+                        const index = currentZones.findIndex((candidate) => candidate.id === zone.id);
+                        if (index !== -1)
+                            currentZones[index] = zone;
+                        updated.push(zone);
+                    }
+                }
+                if (zonePlan.items.length > 0) {
+                    await c.flowZones.moveItems(zone.id, zonePlan.items, pk);
+                    moved.push({ zoneId: zone.id, name: zone.name, items: zonePlan.items, });
+                }
+                if (pruneItems.length > 0) {
+                    await c.flowZones.moveItems("default", pruneItems, pk);
+                    pruned.push({ zoneId: "default", fromZoneId: zone.id, name: zone.name, items: pruneItems, });
+                }
+            }
+            return {
+                organized: true,
+                action: "organize",
+                resource: "flow-zone",
+                projectKey: pk,
+                sync,
+                validateObjects,
+                zoneCount: plan.zones.length,
+                itemCount,
+                pruneItemCount,
+                created,
+                updated,
+                moved,
+                pruned,
+            };
+        },
+        usage: "dss flow-zone organize (--data JSON|--data-file PATH|--file PATH|--stdin) [--sync] [--validate-objects] [--dry-run] [--project-key KEY]",
+        description: "Create/update flow zones and move objects from a declarative visual organization plan.",
+        examples: [
+            "dss flow-zone organize --file flow-zones.json --dry-run",
+            `dss flow-zone organize --data '{"zones":[{"name":"Raw","color":"#64748b","datasets":["raw_orders"]}]}'`,
+        ],
+    },
+    graph: {
+        handler: (c, a, f) => {
+            const id = a[0] === undefined ? undefined : flowZoneId(a[0]);
+            return c.flowZones.graph(id, f["project-key"]);
+        },
+        usage: "dss flow-zone graph [<id>] [--project-key KEY]",
+        description: "Get the full flow graph or the graph for a single flow zone.",
+        examples: ["dss flow-zone graph", "dss flow-zone graph ZONE_ID",],
+    },
+};

package/dist/src/cli/commands/folder.d.ts

@@ -0,0 +1,2 @@
+import type { CommandMeta } from "../types.js";
+export declare const folderCommands: Record<string, CommandMeta>;