dataiku-sdk 3.1.0 → 3.3.0

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

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

package/dist/src/cli/commands/project-folder.js

@@ -0,0 +1,197 @@
+import { requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
+import { isNotFoundError, planResult, skipResult, } from "../output.js";
+import { requireArgs, UsageError, } from "../usage.js";
+const PLAN_FAILURE_CODES = { usage: 1, error: 2, transient: 3, };
+function folderEndpoint(folderId, suffix = "") {
+    return `/public/api/project-folders/${encodeURIComponent(folderId)}${suffix}`;
+}
+/**
+ * Positional ids are server keys: an empty string would silently target the
+ * parent collection (e.g. DELETE /public/api/project-folders/ = the root
+ * folder) instead of failing as a usage error. Runs for live, --plan, and
+ * --dry-run alike with zero network.
+ */
+function nonEmptyPositionals(args, names, usage) {
+    args.forEach((value, index) => {
+        if (value.trim().length === 0) {
+            throw new UsageError(`<${names[index] ?? `arg${String(index + 1)}`}> must be a non-empty identifier. Usage: ${usage}`);
+        }
+    });
+}
+const GET_USAGE = "dss project-folder get <folderId>";
+const SETTINGS_GET_USAGE = "dss project-folder settings-get <folderId>";
+const SETTINGS_SET_USAGE = "dss project-folder settings-set <folderId> (--data JSON|--data-file PATH|--stdin) [--dry-run]";
+const MOVE_USAGE = "dss project-folder move <folderId> <destinationFolderId> [--dry-run]";
+const DELETE_USAGE = "dss project-folder delete <folderId> [--if-exists] [--dry-run]";
+const CREATE_CHILD_USAGE = "dss project-folder create-child <parentFolderId> --name NAME [--dry-run]";
+const MOVE_PROJECT_USAGE = "dss project-folder move-project <folderId> <projectKey> <destinationFolderId> [--dry-run]";
+export const projectFolderCommands = {
+    root: {
+        handler: (c) => c.projectFolders.root(),
+        usage: "dss project-folder root",
+        description: "Get the root project folder definition (visible children and projects).",
+        examples: ["dss project-folder root",],
+    },
+    get: {
+        validate: (a) => {
+            requireArgs(a, 1, GET_USAGE);
+            nonEmptyPositionals(a, ["folderId",], GET_USAGE);
+        },
+        handler: (c, a) => c.projectFolders.get(a[0]),
+        usage: GET_USAGE,
+        description: "Get a project folder definition (children and project keys).",
+        examples: ["dss project-folder get KdLmPU6",],
+    },
+    "settings-get": {
+        validate: (a) => {
+            requireArgs(a, 1, SETTINGS_GET_USAGE);
+            nonEmptyPositionals(a, ["folderId",], SETTINGS_GET_USAGE);
+        },
+        handler: (c, a) => c.projectFolders.getSettings(a[0]),
+        usage: SETTINGS_GET_USAGE,
+        description: "Get project folder settings (name, owner, permissions). Admin required.",
+        examples: ["dss project-folder settings-get KdLmPU6",],
+    },
+    "settings-set": {
+        validate: (a) => {
+            requireArgs(a, 1, SETTINGS_SET_USAGE);
+            nonEmptyPositionals(a, ["folderId",], SETTINGS_SET_USAGE);
+        },
+        handler: async (c, a, f) => {
+            const settings = requiredJsonInput(f, "--data, --data-file, or --stdin is required (project folder settings).");
+            if (executionMode(f).dryRun) {
+                return planResult("project-folder", "settings-set", {
+                    asyncKind: "none",
+                    method: "PUT",
+                    endpoint: folderEndpoint(a[0], "/settings"),
+                    identifiers: { folderId: a[0], },
+                    payload: settings,
+                    idempotency: "none",
+                    exitCodesOnFailure: PLAN_FAILURE_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            await c.projectFolders.updateSettings(a[0], settings);
+            return { updated: a[0], resource: "project-folder", };
+        },
+        usage: SETTINGS_SET_USAGE,
+        description: "Replace project folder settings (name, owner, permissions). Admin required.",
+        examples: [
+            "dss project-folder settings-set KdLmPU6 --data-file settings.json --dry-run",
+        ],
+    },
+    move: {
+        validate: (a) => {
+            requireArgs(a, 2, MOVE_USAGE);
+            nonEmptyPositionals(a, ["folderId", "destinationFolderId",], MOVE_USAGE);
+        },
+        handler: async (c, a, f) => {
+            if (executionMode(f).dryRun) {
+                return planResult("project-folder", "move", {
+                    asyncKind: "none",
+                    method: "POST",
+                    endpoint: `${folderEndpoint(a[0], "/move")}?destination=${encodeURIComponent(a[1])}`,
+                    identifiers: { folderId: a[0], destination: a[1], },
+                    idempotency: "none",
+                    exitCodesOnFailure: PLAN_FAILURE_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            await c.projectFolders.move(a[0], a[1]);
+            return { moved: a[0], destination: a[1], resource: "project-folder", };
+        },
+        usage: MOVE_USAGE,
+        description: "Move a project folder (and its content) into another project folder. Cannot move into a sub-folder of itself.",
+        examples: ["dss project-folder move KdLmPU6 dgKywsx",],
+    },
+    delete: {
+        validate: (a) => {
+            requireArgs(a, 1, DELETE_USAGE);
+            nonEmptyPositionals(a, ["folderId",], DELETE_USAGE);
+        },
+        handler: async (c, a, f) => {
+            // Dry-run must be a validated plan with zero HTTP: no existence GET.
+            if (executionMode(f).dryRun) {
+                return planResult("project-folder", "delete", {
+                    asyncKind: "none",
+                    method: "DELETE",
+                    endpoint: folderEndpoint(a[0]),
+                    identifiers: { folderId: a[0], },
+                    idempotency: "if-exists",
+                    exitCodesOnFailure: PLAN_FAILURE_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            // --if-exists (live only) pays one existence GET; a 404 becomes a skip.
+            if (f["if-exists"] === true) {
+                const current = await c.projectFolders.get(a[0]).catch((error) => {
+                    if (isNotFoundError(error))
+                        return undefined;
+                    throw error;
+                });
+                if (!current)
+                    return skipResult("project-folder", a[0], "missing");
+            }
+            await c.projectFolders.delete(a[0]);
+            return { deleted: a[0], resource: "project-folder", };
+        },
+        usage: DELETE_USAGE,
+        description: "Delete an empty project folder (no sub-folders, no projects). Admin required.",
+        examples: ["dss project-folder delete KdLmPU6 --dry-run",],
+    },
+    "create-child": {
+        validate: (a, f) => {
+            const name = f["name"];
+            if (typeof name === "string" && name.trim().length === 0) {
+                throw new UsageError(`--name must be a non-empty folder name. Usage: ${CREATE_CHILD_USAGE}`);
+            }
+            if (!a[0] || typeof name !== "string" || name.length === 0) {
+                throw new UsageError(`Usage: ${CREATE_CHILD_USAGE}`);
+            }
+        },
+        handler: async (c, a, f) => {
+            const name = f["name"];
+            if (executionMode(f).dryRun) {
+                return planResult("project-folder", "create-child", {
+                    asyncKind: "none",
+                    method: "POST",
+                    endpoint: `${folderEndpoint(a[0], "/children")}?name=${encodeURIComponent(name)}`,
+                    identifiers: { parentFolderId: a[0], name, },
+                    idempotency: "none",
+                    exitCodesOnFailure: PLAN_FAILURE_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            const created = await c.projectFolders.createChild(a[0], name);
+            return { created: created.id ?? name, resource: "project-folder", ...created, };
+        },
+        usage: CREATE_CHILD_USAGE,
+        description: "Create a sub-project folder. WRITE_CONTENTS required on the parent.",
+        examples: ["dss project-folder create-child KdLmPU6 --name my_sub_folder",],
+    },
+    "move-project": {
+        validate: (a) => {
+            requireArgs(a, 3, MOVE_PROJECT_USAGE);
+            nonEmptyPositionals(a, ["folderId", "projectKey", "destinationFolderId",], MOVE_PROJECT_USAGE);
+        },
+        handler: async (c, a, f) => {
+            if (executionMode(f).dryRun) {
+                return planResult("project-folder", "move-project", {
+                    asyncKind: "none",
+                    method: "POST",
+                    endpoint: `${folderEndpoint(a[0], `/projects/${encodeURIComponent(a[1])}/move`)}?destination=${encodeURIComponent(a[2])}`,
+                    identifiers: { folderId: a[0], projectKey: a[1], destination: a[2], },
+                    idempotency: "none",
+                    exitCodesOnFailure: PLAN_FAILURE_CODES,
+                    plannedAndDryRun: true,
+                });
+            }
+            await c.projectFolders.moveProject(a[0], a[1], a[2]);
+            return { moved: a[1], destination: a[2], resource: "project-folder", };
+        },
+        usage: MOVE_PROJECT_USAGE,
+        description: "Move a project from its project folder to another project folder. WRITE_CONTENTS on destination and project admin required.",
+        examples: ["dss project-folder move-project KdLmPU6 MYPROJECT dgKywsx",],
+    },
+};

package/dist/src/cli/commands/project-git.js

@@ -1,4 +1,5 @@
 import { validateGitReferencePath, } from "../../resources/project-git.js";
+import { sanitizeErrorSecrets, sanitizeSecrets, } from "../../utils/secret-sanitize.js";
 import { num, parseBooleanOption, requiredStringFlag, } from "../coerce.js";
 import { CommandResultFailure, } from "../output.js";
 import { requireArgs, requireNoArgs, UsageError, } from "../usage.js";
@@ -28,48 +29,17 @@ const SENSITIVE_GIT_OUTPUT_KEYS = {
     password: true,
     token: true,
 };
+const GIT_SANITIZE_OPTIONS = {
+    sensitiveKeys: SENSITIVE_GIT_OUTPUT_KEYS,
+    redactUrlUserinfo: true,
+};
 /**
  * DSS may already contain legacy remotes with credentials in the URL, and Git
  * error text can echo them. Sanitize every server-derived Project Git value
  * before it reaches stdout or a structured command failure.
  */
-function redactGitUrlUserinfo(text) {
-    return text.replace(/https?:[\\/]{1,2}[^\s"'<>]+/giu, (url) => {
-        const schemeEnd = url.indexOf(":") + 1;
-        let authorityStart = schemeEnd;
-        while (url[authorityStart] === "/" || url[authorityStart] === "\\")
-            authorityStart++;
-        const slash = url.slice(authorityStart).search(/[\\/]/u);
-        const authorityEnd = slash === -1 ? url.length : authorityStart + slash;
-        const at = url.lastIndexOf("@", authorityEnd - 1);
-        if (at < authorityStart)
-            return url;
-        return `${url.slice(0, authorityStart)}[redacted]@${url.slice(at + 1)}`;
-    });
-}
 function sanitizeProjectGitOutput(value, secrets = []) {
-    if (typeof value === "string") {
-        let sanitized = redactGitUrlUserinfo(value);
-        for (const secret of secrets) {
-            if (secret !== "")
-                sanitized = sanitized.split(secret).join("[redacted]");
-        }
-        return sanitized;
-    }
-    if (Array.isArray(value)) {
-        return value.map((item) => sanitizeProjectGitOutput(item, secrets));
-    }
-    if (value !== null && typeof value === "object") {
-        const sanitized = {};
-        for (const [key, item,] of Object.entries(value)) {
-            const normalizedKey = key.replace(/[-_]/g, "").toLowerCase();
-            sanitized[key] = SENSITIVE_GIT_OUTPUT_KEYS[normalizedKey] === true
-                ? "[redacted]"
-                : sanitizeProjectGitOutput(item, secrets);
-        }
-        return sanitized;
-    }
-    return value;
+    return sanitizeSecrets(value, { ...GIT_SANITIZE_OPTIONS, secrets, });
 }
 /**
  * Most Git actions answer HTTP 200 with `{success: false}` and the Git stderr
@@ -84,16 +54,7 @@ function assertGitActionSucceeded(result, action) {
     return sanitized;
 }
 function sanitizeProjectGitError(error) {
-    if (!(error instanceof Error))
-        return error;
-    error.message = sanitizeProjectGitOutput(error.message);
-    if (error.stack !== undefined)
-        error.stack = sanitizeProjectGitOutput(error.stack);
-    const errorWithBody = error;
-    if (typeof errorWithBody.body === "string") {
-        errorWithBody.body = sanitizeProjectGitOutput(errorWithBody.body);
-    }
-    return error;
+    return sanitizeErrorSecrets(error, { ...GIT_SANITIZE_OPTIONS, });
 }
 /**
  * External library credentials are read only from the environment variable
@@ -533,17 +494,16 @@ export const projectGitCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, FUTURE_WAIT_USAGE);
             try {
-                const result = sanitizeProjectGitOutput(await c.projectGit.waitForFuture(a[0], {
+                // The official Python client returns the future result verbatim
+                // (wait_for_result never inspects result fields): a completed
+                // future's payload is caller-interpreted data, and a
+                // {success:false} bag from DSS means "no diagnostics to show",
+                // not an operation failure. Only the git ACTION endpoints carry
+                // the {success:false} = failed convention.
+                return sanitizeProjectGitOutput(await c.projectGit.waitForFuture(a[0], {
                     pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
                     timeoutMs: num(f["timeout"], "--timeout"),
                 }));
-                if (result !== null
-                    && typeof result === "object"
-                    && !Array.isArray(result)
-                    && result.success === false) {
-                    return assertGitActionSucceeded(result, "future-wait");
-                }
-                return result;
             }
             catch (error) {
                 throw sanitizeProjectGitError(error);

package/dist/src/cli/commands/project-library.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import { encodeLibraryPath, EXPECT_SHA256_PATTERN, validateLibraryDestinationPath, validateLibraryName, validateLibraryPath, } from "../../resources/project-library.js";
 import { numFlag, readStdinText, sha256Hex, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, planResult, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 const PROJECT_LIBRARY_EXIT_CODES = { usage: 1, error: 2, transient: 3, };
@@ -100,7 +101,7 @@ export const projectLibraryCommands = {
             requireArgs(a, 1, "dss project-library create-file <path> [--if-not-exists] [--dry-run] [--project-key KEY]");
             const pk = f["project-key"];
             validateLibraryPath(a[0]);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return projectLibraryPlan("create-file", {
                     method: "POST",
                     endpoint: projectLibraryContentsEndpoint(c, pk, a[0]),
@@ -126,7 +127,7 @@ export const projectLibraryCommands = {
             requireArgs(a, 1, "dss project-library create-folder <path> [--if-not-exists] [--dry-run] [--project-key KEY]");
             const pk = f["project-key"];
             validateLibraryPath(a[0]);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return projectLibraryPlan("create-folder", {
                     method: "POST",
                     endpoint: projectLibraryFolderEndpoint(c, pk, a[0]),
@@ -153,7 +154,7 @@ export const projectLibraryCommands = {
             const pk = f["project-key"];
             const expectSha256 = expectSha256FromFlags(f);
             validateLibraryPath(a[0]);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return projectLibraryPlan("put", {
                     method: "POST",
                     endpoint: projectLibraryContentsEndpoint(c, pk, a[0]),
@@ -206,7 +207,7 @@ export const projectLibraryCommands = {
             requireArgs(a, 1, "dss project-library delete <path> [--dry-run] [--project-key KEY]");
             const pk = f["project-key"];
             validateLibraryPath(a[0]);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return projectLibraryPlan("delete", {
                     method: "DELETE",
                     endpoint: projectLibraryContentsEndpoint(c, pk, a[0]),
@@ -226,7 +227,7 @@ export const projectLibraryCommands = {
             const pk = f["project-key"];
             const validPath = validateLibraryPath(a[0]);
             const validName = validateLibraryName(a[1]);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return projectLibraryPlan("rename", {
                     method: "POST",
                     endpoint: projectLibraryActionEndpoint(c, pk, "rename/"),
@@ -247,7 +248,7 @@ export const projectLibraryCommands = {
             const pk = f["project-key"];
             const validPath = validateLibraryPath(a[0]);
             const destination = validateLibraryDestinationPath(a[1]);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return projectLibraryPlan("move", {
                     method: "POST",
                     endpoint: projectLibraryActionEndpoint(c, pk, "move"),

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

@@ -3,6 +3,7 @@ import { deepMerge, } from "../../utils/deep-merge.js";
 import { inspectProjectArchive, } from "../../utils/project-archive.js";
 import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
 import { jsonInput, num, requiredJsonInput, requiredStringFlag, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { CommandResultFailure, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 const INSPECT_ARCHIVE_USAGE = "dss project inspect-archive <file>";
@@ -91,7 +92,7 @@ export const projectCommands = {
                 throw new UsageError("--expect-project-incarnation must be a 64-character lowercase SHA-256 hash.", "validation_failed");
             }
             const guarded = f["if-exists"] === true
-                || f["dry-run"] === true
+                || executionMode(f).dryRun
                 || expectedIncarnation !== undefined;
             if (!guarded) {
                 // Purely user-requested delete without any guard flag: keep the
@@ -128,7 +129,7 @@ export const projectCommands = {
                 }
                 throw error;
             }
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     deleted: false,
                     dryRun: true,
@@ -213,12 +214,6 @@ export const projectCommands = {
         description: "Read-only local inspection of a project export archive: member names, sizes, manifest validity, archive issues, and the source project key. Never contacts DSS.",
         examples: ["dss project inspect-archive ./my_proj.zip",],
     },
-    "permissions-get": {
-        handler: (c, _a, f) => c.projects.getPermissions(f["project-key"]),
-        usage: "dss project permissions-get [--project-key KEY]",
-        description: "Get a project's permissions.",
-        examples: ["dss project permissions-get --project-key MY_PROJ",],
-    },
     "permissions-set": {
         handler: async (c, _a, f) => {
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (permissions object).");
@@ -229,6 +224,58 @@ export const projectCommands = {
         description: "Replace a project's permissions.",
         examples: ["dss project permissions-set --data-file perms.json --project-key MY_PROJ",],
     },
+    "permissions-get": {
+        handler: (c, _a, f) => c.projects.getPermissions(f["project-key"]),
+        usage: "dss project permissions-get [--project-key KEY]",
+        description: "Get a project's permissions.",
+        examples: ["dss project permissions-get --project-key MY_PROJ",],
+    },
+    "metadata-set": {
+        handler: async (c, _a, f) => {
+            const metadata = requiredJsonInput(f, "--data, --data-file, or --stdin is required (full metadata object).");
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "metadata-set",
+                    resource: "project",
+                    next: metadata,
+                };
+            }
+            await c.projects.setMetadata(f["project-key"], metadata);
+            return { updated: true, };
+        },
+        usage: "dss project metadata-set (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
+        description: "Replace project metadata with a full object obtained from a previous metadata GET. Fields absent from the payload are removed.",
+        examples: [
+            "dss project metadata-set --data-file metadata.json --project-key MY_PROJ --dry-run",
+        ],
+    },
+    "tags-get": {
+        handler: (c, _a, f) => c.projects.tags(f["project-key"]),
+        usage: "dss project tags-get [--project-key KEY]",
+        description: "Get project-level tags as a dictionary of tag name to display settings.",
+        examples: ["dss project tags-get", "dss project tags-get --project-key MY_PROJ",],
+    },
+    "tags-set": {
+        handler: async (c, _a, f) => {
+            const tags = requiredJsonInput(f, "--data, --data-file, or --stdin is required (full tags object).");
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "tags-set",
+                    resource: "project",
+                    next: tags,
+                };
+            }
+            await c.projects.setTags(f["project-key"], tags);
+            return { updated: true, };
+        },
+        usage: "dss project tags-set (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
+        description: "Replace project tags with a full object obtained from a previous tags GET. Tags absent from the payload are removed.",
+        examples: [
+            'dss project tags-set --data \'{"tags":{"production":{"color":"#28aadd"}}}\' --project-key MY_PROJ --dry-run',
+        ],
+    },
     "settings-get": {
         handler: (c, _a, f) => c.projects.getSettings(f["project-key"]),
         usage: "dss project settings-get [--project-key KEY]",

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

@@ -2,7 +2,8 @@ import { readFileSync, } from "node:fs";
 import { writeFile, } from "node:fs/promises";
 import { join, } from "node:path";
 import { deepMerge, } from "../../utils/deep-merge.js";
-import { jobLogFilterFromFlag, jsonInput, maxLogLinesFromFlags, normalizeLineEndings, num, recipeInputDatasetsFromFlags, requiredStringFlag, rewritePairsFromFlags, sha256Hex, splitCsvFlag, stableHash, } from "../coerce.js";
+import { jobLogFilterFromFlag, jsonInput, maxLogLinesFromFlags, normalizeLineEndings, num, recipeInputDatasetsFromFlags, requiredJsonInput, requiredStringFlag, rewritePairsFromFlags, sha256Hex, splitCsvFlag, stableHash, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { moveCreatedItemsToZone, resolveFlowZoneIdFromFlags, } from "../helpers/flow-zone.js";
 import { ensureRecipeBackupDir, readRecipeBackup, recipeBackupDocument, recipeBackupPath, recipeCodeEnv, recipeGraph, recipeInputItemRef, recipeRoleInputItems, recipeRunShouldWait, writeRecipeBackup, } from "../helpers/recipe.js";
 import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
@@ -65,6 +66,41 @@ export const recipeCommands = {
         description: "List all recipes in a project.",
         examples: ["dss recipe list",],
     },
+    metadata: {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss recipe metadata <name>");
+            return c.recipes.metadata(a[0], {
+                projectKey: f["project-key"],
+            });
+        },
+        usage: "dss recipe metadata <name> [--project-key KEY]",
+        description: "Get recipe metadata (label, description, tags, custom fields).",
+        examples: ["dss recipe metadata compute_orders",],
+    },
+    "metadata-set": {
+        handler: async (c, a, f) => {
+            const usage = "dss recipe metadata-set <name> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]";
+            requireArgs(a, 1, usage);
+            const metadata = requiredJsonInput(f, "--data, --data-file, or --stdin is required (full metadata object).");
+            const pk = f["project-key"];
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "metadata-set",
+                    resource: "recipe",
+                    name: a[0],
+                    next: metadata,
+                };
+            }
+            await c.recipes.setMetadata(a[0], metadata, { projectKey: pk, });
+            return { updated: a[0], resource: "recipe", };
+        },
+        usage: "dss recipe metadata-set <name> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
+        description: "Replace recipe metadata with a full object obtained from a previous metadata GET. Fields absent from the payload are removed.",
+        examples: [
+            'dss recipe metadata-set compute_orders --data \'{"label":"Orders"}\' --dry-run',
+        ],
+    },
     get: {
         handler: (c, a, f) => {
             requireArgs(a, 1, "dss recipe get <name>");
@@ -109,7 +145,7 @@ export const recipeCommands = {
                 summary: f["summary"] === true,
                 wait,
             };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const outputs = await c.recipes.resolveRunOutputs(a[0], {
                     partition: options.partition,
                     projectKey: pk,
@@ -139,11 +175,11 @@ export const recipeCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss recipe delete <name>");
             const pk = f["project-key"];
-            if (f["dry-run"] === true || f["if-exists"] === true) {
+            if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.recipes.get(a[0], { projectKey: pk, includePayload: true, }));
                 if (!current)
                     return skipResult("recipe", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "recipe", name: a[0], current, };
                 }
             }
@@ -241,13 +277,13 @@ export const recipeCommands = {
             const zoneMove = zoneId && name
                 ? [{ objectId: name, objectType: "RECIPE", },]
                 : undefined;
-            if ((f["if-not-exists"] === true || f["dry-run"] === true) && name) {
+            if ((f["if-not-exists"] === true || executionMode(f).dryRun) && name) {
                 const list = await c.recipes.list(pk);
                 const existing = list.find((r) => r.name === name);
-                if (existing && f["if-not-exists"] === true && f["dry-run"] !== true) {
+                if (existing && f["if-not-exists"] === true && !executionMode(f).dryRun) {
                     return skipResult("recipe", name, "exists", { current: existing, });
                 }
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "create",
@@ -259,7 +295,7 @@ export const recipeCommands = {
                     };
                 }
             }
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "create",
@@ -328,7 +364,7 @@ export const recipeCommands = {
                 throw new UsageError("Cannot reuse --path or --metastore-table for multiple cloned output datasets.", "invalid_enum");
             }
             const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "clone",
@@ -391,7 +427,7 @@ export const recipeCommands = {
                 throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss recipe update <name> [--data '{...}' | --data-file PATH | --stdin]");
             }
             const pk = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.recipes.get(a[0], { projectKey: pk, includePayload: true, });
                 const currentRecipe = current.recipe;
                 const next = {
@@ -430,7 +466,7 @@ export const recipeCommands = {
             }
             const nextItems = [...items, { ref: a[1], deps: [], },];
             const inputs = nextItems.map(recipeInputItemRef).filter((ref) => Boolean(ref));
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "add-input",
@@ -467,7 +503,7 @@ export const recipeCommands = {
             }
             const nextItems = items.filter((item) => recipeInputItemRef(item) !== a[1]);
             const inputs = nextItems.map(recipeInputItemRef).filter((ref) => Boolean(ref));
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "remove-input",
@@ -542,7 +578,7 @@ export const recipeCommands = {
                 projectKey: pk,
                 includePayload: true,
             });
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "set-payload",
@@ -593,7 +629,7 @@ export const recipeCommands = {
             const next = f["payload-only"] === true || !restoredRecipe
                 ? { ...current, payload, }
                 : { ...current, recipe: restoredRecipe, payload, };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "restore",

package/dist/src/cli/commands/saved-model.d.ts

@@ -1,2 +1,7 @@
 import type { CommandMeta } from "../types.js";
+/**
+ * Mutating actions accept --plan (buildMutationPlan in contract.ts owns the
+ * --plan path centrally); the handlers below keep --dry-run support with a
+ * zero-request planned payload, mirroring set-active/delete.
+ */
 export declare const savedModelCommands: Record<string, CommandMeta>;