dataiku-sdk 3.0.0 → 3.2.0

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

@@ -1,18 +1,43 @@
 import { readFileSync, } from "node:fs";
-import { mkdir, writeFile, } from "node:fs/promises";
+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 { executionMode, } from "../flags.js";
 import { moveCreatedItemsToZone, resolveFlowZoneIdFromFlags, } from "../helpers/flow-zone.js";
-import { readRecipeBackup, recipeBackupDocument, recipeBackupPath, recipeCodeEnv, recipeGraph, recipeInputItemRef, recipeRoleInputItems, recipeRunShouldWait, } from "../helpers/recipe.js";
+import { ensureRecipeBackupDir, readRecipeBackup, recipeBackupDocument, recipeBackupPath, recipeCodeEnv, recipeGraph, recipeInputItemRef, recipeRoleInputItems, recipeRunShouldWait, writeRecipeBackup, } from "../helpers/recipe.js";
 import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
+/** Read a local recipe file before any DSS request, mapping read failures to usage validation. */
+function readRecipeFile(filePath, flagName) {
+    try {
+        return readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new UsageError(`Could not read ${flagName} ${filePath}: ${reason}.`, "not_found", "Verify the file path and that it is readable.");
+    }
+}
+/** Read a set-payload backup file before any DSS request, mapping read failures to usage validation. */
+function readRecipeBackupFile(backupPath) {
+    try {
+        return readRecipeBackup(backupPath);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new UsageError(`Could not read --backup ${backupPath}: ${reason}.`, "not_found", "Verify the backup file path and that it is readable.");
+    }
+}
 function formatLineDiff(remoteName, localPath, remoteContent, localContent) {
-    if (localContent === remoteContent) {
+    // Line-ending differences are not content differences: compare and split on
+    // CRLF-normalized text, mirroring assert-unchanged's normalized payload hash.
+    const normalizedLocal = normalizeLineEndings(localContent);
+    const normalizedRemote = normalizeLineEndings(remoteContent);
+    if (normalizedLocal === normalizedRemote) {
         return "No differences.";
     }
-    const localLines = localContent.split("\n");
-    const remoteLines = remoteContent.split("\n");
+    const localLines = normalizedLocal.split("\n");
+    const remoteLines = normalizedRemote.split("\n");
     const lines = [`--- remote:${remoteName}`, `+++ local:${localPath}`, "",];
     const maxLen = Math.max(localLines.length, remoteLines.length);
     for (let i = 0; i < maxLen; i++) {
@@ -85,7 +110,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,
@@ -104,7 +129,7 @@ export const recipeCommands = {
             return c.recipes.run(a[0], options);
         },
         usage: "dss recipe run <name> [--wait|--no-wait] [--build-mode MODE] [--include-logs] [--log-filter stdout|stderr|user|errors] [--summary] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--partition PARTITION] [--dry-run] [--project-key KEY]",
-        description: "Run a recipe by resolving its outputs and submitting the correct dataset or managed-folder build job.",
+        description: "Run a recipe by resolving its outputs and submitting the correct dataset or managed-folder build job. --timeout defaults to 120000 ms and --poll-interval to 2000 ms.",
         examples: [
             "dss recipe run compute_orders --wait",
             "dss recipe run compute_exports --include-logs --log-filter stdout --summary --timeout 600000",
@@ -115,11 +140,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, };
                 }
             }
@@ -217,13 +242,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",
@@ -235,7 +260,7 @@ export const recipeCommands = {
                     };
                 }
             }
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "create",
@@ -304,7 +329,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",
@@ -344,6 +369,8 @@ export const recipeCommands = {
             if (!filePath) {
                 throw new UsageError("--file is required. Usage: dss recipe diff <name> --file PATH");
             }
+            // Read and validate the local file before any DSS request.
+            const localContent = readRecipeFile(filePath, "--file");
             const result = await c.recipes.get(a[0], {
                 includePayload: true,
                 projectKey: f["project-key"],
@@ -351,7 +378,6 @@ export const recipeCommands = {
             if (!result.payload) {
                 throw new Error(`Recipe "${a[0]}" has no code payload to diff.`);
             }
-            const localContent = readFileSync(filePath, "utf-8");
             return formatLineDiff(a[0], filePath, result.payload, localContent);
         },
         usage: "dss recipe diff <name> --file PATH [--project-key KEY]",
@@ -366,7 +392,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 = {
@@ -405,7 +431,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",
@@ -442,7 +468,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",
@@ -506,7 +532,7 @@ export const recipeCommands = {
             const filePath = f["file"];
             if (!filePath)
                 throw new UsageError("--file is required.");
-            const content = readFileSync(filePath, "utf-8");
+            const content = readRecipeFile(filePath, "--file");
             const pk = f["project-key"];
             const shouldBackup = f["no-backup"] !== true;
             const backupDir = shouldBackup
@@ -517,7 +543,7 @@ export const recipeCommands = {
                 projectKey: pk,
                 includePayload: true,
             });
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "set-payload",
@@ -530,8 +556,8 @@ export const recipeCommands = {
                 };
             }
             if (backupDir && backupPath) {
-                await mkdir(backupDir, { recursive: true, });
-                await writeFile(backupPath, `${JSON.stringify(recipeBackupDocument(a[0], pk, current), null, 2)}\n`, "utf-8");
+                ensureRecipeBackupDir(backupDir);
+                writeRecipeBackup(backupPath, `${JSON.stringify(recipeBackupDocument(a[0], pk, current), null, 2)}\n`);
             }
             await c.recipes.replace(a[0], { ...current, payload: content, }, pk);
             return {
@@ -555,7 +581,7 @@ export const recipeCommands = {
             const usage = "dss recipe restore <name> --backup FILE [--payload-only] [--dry-run] [--project-key KEY]";
             requireArgs(a, 1, usage);
             const backupPath = requiredStringFlag(f, "backup", usage);
-            const backup = readRecipeBackup(backupPath);
+            const backup = readRecipeBackupFile(backupPath);
             const payload = typeof backup.payload === "string" ? backup.payload : "";
             const pk = f["project-key"];
             const current = await c.recipes.get(a[0], { includePayload: true, projectKey: pk, });
@@ -568,7 +594,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",
@@ -598,7 +624,7 @@ export const recipeCommands = {
             const usage = "dss recipe assert-unchanged <name> --since BACKUP [--project-key KEY]";
             requireArgs(a, 1, usage);
             const backupPath = requiredStringFlag(f, "since", usage);
-            const backup = readRecipeBackup(backupPath);
+            const backup = readRecipeBackupFile(backupPath);
             const current = await c.recipes.get(a[0], {
                 includePayload: true,
                 projectKey: f["project-key"],

package/dist/src/cli/commands/saved-model.js

@@ -1,3 +1,4 @@
+import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
 import { requireArgs, } from "../usage.js";
 export const savedModelCommands = {
@@ -40,7 +41,7 @@ export const savedModelCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 2, "dss saved-model set-active <modelId> <versionId> [--dry-run] [--project-key KEY]");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "set-active",
@@ -64,11 +65,11 @@ export const savedModelCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss saved-model delete <modelId> [--if-exists] [--dry-run] [--project-key KEY]");
             const projectKey = 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.savedModels.get(a[0], projectKey));
                 if (!current)
                     return skipResult("saved-model", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "saved-model", id: a[0], current, };
                 }
             }

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

@@ -1,5 +1,6 @@
 import { scenarioUpdatePreview, } from "../../resources/scenarios.js";
 import { jsonInput, num, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const scenarioCommands = {
@@ -26,7 +27,7 @@ export const scenarioCommands = {
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
                 timeoutMs: num(f["timeout"], "--timeout"),
             };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "run",
@@ -54,7 +55,7 @@ export const scenarioCommands = {
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
                 timeoutMs: num(f["timeout"], "--timeout"),
             };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "run-and-wait",
@@ -87,11 +88,11 @@ export const scenarioCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss scenario delete <id>");
             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.scenarios.get(a[0], { projectKey: pk, }));
                 if (!current)
                     return skipResult("scenario", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "scenario", id: a[0], current, };
                 }
             }
@@ -112,13 +113,13 @@ export const scenarioCommands = {
                 scenarioType: f["type"],
                 projectKey: pk,
             };
-            if (f["if-not-exists"] === true || f["dry-run"] === true) {
+            if (f["if-not-exists"] === true || executionMode(f).dryRun) {
                 const list = await c.scenarios.list(pk);
                 const existing = list.find((s) => s.id === a[0]);
-                if (existing && f["if-not-exists"] === true && f["dry-run"] !== true) {
+                if (existing && f["if-not-exists"] === true && !executionMode(f).dryRun) {
                     return skipResult("scenario", a[0], "exists", { current: existing, });
                 }
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "create",
@@ -150,7 +151,7 @@ export const scenarioCommands = {
                 throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin]");
             }
             const pk = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.scenarios.get(a[0], { projectKey: pk, });
                 const preview = scenarioUpdatePreview(current, data);
                 return {

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

@@ -1,2 +1,12 @@
 import type { CommandMeta } from "../types.js";
+export declare function resolveSqlInput(args: string[], flags: Record<string, string | boolean>): string;
+export interface SqlQueryInvocation {
+    query: string;
+    connection?: string;
+    datasetFullName?: string;
+    database?: string;
+    projectKey?: string;
+    type: "sql";
+}
+export declare function resolveSqlQueryInvocation(args: string[], flags: Record<string, string | boolean>, projectKeyOverride?: string): SqlQueryInvocation;
 export declare const sqlCommands: Record<string, CommandMeta>;

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

@@ -1,7 +1,9 @@
 import { readFileSync, } from "node:fs";
-import { mkdir, writeFile, } from "node:fs/promises";
+import { mkdir, } from "node:fs/promises";
 import { dirname, resolve, } from "node:path";
+import { writeResponseToFile, } from "../../utils/response-file.js";
 import { readStdinText, stripUtf8Bom, } from "../coerce.js";
+import { enqueueCliWarning, } from "../output.js";
 import { UsageError, } from "../usage.js";
 const SQL_QUERY_USAGE = "dss sql query (SQL | --sql QUERY | --sql-file PATH | --sql - | --stdin) (--connection CONN | --dataset FULL_NAME) [--database DB] [--output PATH|--output-file PATH] [--preview N] [--start-retries N] [--request-timeout MS] [--project-key KEY]";
 const DEFAULT_SQL_PREVIEW_ROWS = 5;
@@ -34,7 +36,7 @@ function parseSqlStartRetries(value) {
     }
     return parsed;
 }
-function resolveSqlInput(args, flags) {
+export function resolveSqlInput(args, flags) {
     const sources = [];
     if (typeof flags["sql"] === "string") {
         sources.push({
@@ -69,37 +71,58 @@ function resolveSqlInput(args, flags) {
     }
     return query;
 }
+export function resolveSqlQueryInvocation(args, flags, projectKeyOverride) {
+    const connection = flags["connection"];
+    const datasetFullName = flags["dataset"];
+    if ((connection ? 1 : 0) + (datasetFullName ? 1 : 0) !== 1) {
+        throw new UsageError(`Pass exactly one of --connection or --dataset. Usage: ${SQL_QUERY_USAGE}`);
+    }
+    return {
+        query: resolveSqlInput(args, flags),
+        connection,
+        datasetFullName,
+        database: flags["database"],
+        projectKey: projectKeyOverride ?? flags["project-key"],
+        type: "sql",
+    };
+}
 export const sqlCommands = {
     query: {
         handler: async (c, a, f) => {
-            const connection = f["connection"];
-            const datasetFullName = f["dataset"];
-            if ((connection ? 1 : 0) + (datasetFullName ? 1 : 0) !== 1) {
-                throw new UsageError(`Pass exactly one of --connection or --dataset. Usage: ${SQL_QUERY_USAGE}`);
-            }
             const outputFile = f["output"]
                 ?? f["output-file"];
             const previewProvided = f["preview"] !== undefined;
-            if (previewProvided && !outputFile) {
-                throw new UsageError(`--preview requires --output or --output-file. Usage: ${SQL_QUERY_USAGE}`, "validation_failed");
-            }
             const previewCount = previewProvided
                 ? parseSqlPreviewCount(f["preview"])
                 : DEFAULT_SQL_PREVIEW_ROWS;
-            const query = resolveSqlInput(a, f);
             const result = await c.sql.query({
-                query,
-                connection,
-                datasetFullName,
-                database: f["database"],
-                projectKey: f["project-key"],
+                ...resolveSqlQueryInvocation(a, f),
                 retryMaxAttempts: parseSqlStartRetries(f["start-retries"]),
             });
-            if (!outputFile)
+            if (!outputFile && !previewProvided)
                 return result;
+            if (!outputFile) {
+                const truncated = result.rows.length > previewCount;
+                if (truncated) {
+                    enqueueCliWarning({
+                        code: "sql_preview_truncated",
+                        rowCount: result.rows.length,
+                        previewRows: previewCount,
+                        hint: "Use --output PATH to write the full result without placing it on stdout.",
+                    });
+                }
+                return {
+                    queryId: result.queryId,
+                    schema: result.schema,
+                    columns: result.columns ?? result.schema,
+                    rowCount: result.rows.length,
+                    preview: result.rows.slice(0, previewCount),
+                    truncated,
+                };
+            }
             const outputPath = resolve(outputFile);
             await mkdir(dirname(outputPath), { recursive: true, });
-            await writeFile(outputPath, `${JSON.stringify(result, null, 2)}\n`, "utf-8");
+            await writeResponseToFile(outputPath, new Response(`${JSON.stringify(result, null, 2)}\n`), "preserve");
             return {
                 queryId: result.queryId,
                 schema: result.schema,
@@ -111,7 +134,7 @@ export const sqlCommands = {
             };
         },
         usage: SQL_QUERY_USAGE,
-        description: "Run a SQL query against a DSS connection or dataset. --start-retries may execute the SQL more than once; use it only when repetition is safe.",
+        description: "Run potentially mutating SQL against a DSS connection or dataset. Use --preview N for bounded stdout or --output PATH for full rows. --start-retries may execute SQL more than once; use it only when repetition is safe.",
         examples: [
             "dss sql query 'SELECT * FROM orders LIMIT 10' --connection my_pg",
             "dss sql query --sql-file query.sql --connection my_pg",

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

@@ -1,4 +1,5 @@
 import { requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, planResult, } from "../output.js";
 import { requireArgs, } from "../usage.js";
 const STATISTICS_PLAN_EXIT_CODES = { usage: 1, error: 2, transient: 3, };
@@ -51,7 +52,7 @@ export const statisticsCommands = {
             requireArgs(a, 1, "dss statistics create-worksheet <dataset> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (worksheet definition).");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("create-worksheet", {
                     method: "POST",
                     endpoint: statisticsWorksheetsEndpoint(c, a[0], projectKey),
@@ -72,7 +73,7 @@ export const statisticsCommands = {
             requireArgs(a, 2, "dss statistics update-worksheet <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (worksheet definition).");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("update-worksheet", {
                     method: "PUT",
                     endpoint: statisticsWorksheetEndpoint(c, a[0], a[1], projectKey),
@@ -90,7 +91,7 @@ export const statisticsCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 2, "dss statistics delete-worksheet <dataset> <worksheetId> [--dry-run] [--project-key KEY]");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("delete-worksheet", {
                     method: "DELETE",
                     endpoint: statisticsWorksheetEndpoint(c, a[0], a[1], projectKey),
@@ -108,7 +109,7 @@ export const statisticsCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 2, "dss statistics run-worksheet <dataset> <worksheetId> [--dry-run] [--project-key KEY]");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("run-worksheet", {
                     method: "POST",
                     endpoint: `${statisticsWorksheetEndpoint(c, a[0], a[1], projectKey)}/actions/run-card`,
@@ -127,7 +128,7 @@ export const statisticsCommands = {
             requireArgs(a, 2, "dss statistics run-card <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
             const card = requiredJsonInput(f, "--data, --data-file, or --stdin is required (card settings).");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("run-card", {
                     method: "POST",
                     endpoint: `${statisticsWorksheetEndpoint(c, a[0], a[1], projectKey)}/actions/run-card`,
@@ -147,7 +148,7 @@ export const statisticsCommands = {
             requireArgs(a, 2, "dss statistics run-computation <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
             const computation = requiredJsonInput(f, "--data, --data-file, or --stdin is required (computation settings).");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("run-computation", {
                     method: "POST",
                     endpoint: `${statisticsWorksheetEndpoint(c, a[0], a[1], projectKey)}/actions/run-computation`,

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

@@ -1,4 +1,5 @@
 import { json, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { UsageError, } from "../usage.js";
 export const variableCommands = {
     get: {
@@ -15,7 +16,7 @@ export const variableCommands = {
             if (standard === undefined && local === undefined) {
                 throw new UsageError("--standard and/or --local is required.");
             }
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.variables.get(pk);
                 const next = f["replace"] === true
                     ? { standard: standard ?? {}, local: local ?? {}, }

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

@@ -1,5 +1,19 @@
-import { requiredJsonInput, } from "../coerce.js";
+import { ClientValidationError, } from "../../errors.js";
+import { deepMerge, } from "../../utils/deep-merge.js";
+import { stableHash, } from "../../utils/stable-hash.js";
+import { num, requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { requireArgs, } from "../usage.js";
+const UPDATE_SETTINGS_USAGE = "dss webapp update-settings <webappId> (--data JSON|--data-file PATH|--stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]";
+const RESTART_USAGE = "dss webapp restart-backend <webappId> [--wait] [--timeout MS] [--poll-interval MS] [--project-key KEY]";
+function validateExpectHash(value) {
+    if (value === undefined || value === false)
+        return undefined;
+    if (typeof value !== "string" || !/^[0-9a-fA-F]{64}$/.test(value)) {
+        throw new ClientValidationError("Expected webapp hash must be a 64-character SHA-256 hex digest.", "validation_failed", "Run this update with --dry-run and capture currentHash before retrying.");
+    }
+    return value;
+}
 export const webappCommands = {
     list: {
         handler: (c, _a, f) => c.webapps.list(f["project-key"]),
@@ -26,14 +40,45 @@ export const webappCommands = {
         examples: ["dss webapp create --data-file webapp.json",],
     },
     "update-settings": {
-        handler: (c, a, f) => {
-            requireArgs(a, 1, "dss webapp update-settings <webappId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, UPDATE_SETTINGS_USAGE);
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (webapp settings).");
-            return c.webapps.updateSettings(a[0], body, f["project-key"]);
+            const projectKey = f["project-key"];
+            const expectHash = validateExpectHash(f["expect-hash"]);
+            if (executionMode(f).dryRun) {
+                const current = await c.webapps.getSettings(a[0], projectKey);
+                const currentHash = stableHash(current);
+                if (expectHash !== undefined && currentHash !== expectHash.toLowerCase()) {
+                    throw new ClientValidationError(`The webapp ${JSON.stringify(a[0])} changed since it was read.`, "validation_failed", "Re-read the webapp settings and retry with the current hash value.", {
+                        id: a[0],
+                        expectedHash: expectHash.toLowerCase(),
+                        actualHash: currentHash,
+                    });
+                }
+                const next = deepMerge(current, body);
+                return {
+                    dryRun: true,
+                    action: "update-settings",
+                    resource: "webapp",
+                    id: a[0],
+                    current,
+                    next,
+                    currentHash,
+                    nextHash: stableHash(next),
+                    ...(expectHash !== undefined
+                        ? { expectHash: expectHash.toLowerCase(), provenanceVerified: true, }
+                        : {}),
+                };
+            }
+            const updated = await c.webapps.updateSettings(a[0], body, projectKey, { expectHash, });
+            return { updated: a[0], ...updated, };
         },
-        usage: "dss webapp update-settings <webappId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
-        description: "Replace a webapp's settings.",
-        examples: ["dss webapp update-settings WEBAPP_ID --data-file webapp.json",],
+        usage: UPDATE_SETTINGS_USAGE,
+        description: "Merge supplied fields into a webapp's settings (GET-merge-PUT) and PUT the full object, so fields outside the patch are never dropped. --expect-hash refuses the write when the object changed since it was fetched; --dry-run reports current, next, and both hashes without writing.",
+        examples: [
+            "dss webapp update-settings WEBAPP_ID --data-file webapp.json",
+            'dss webapp update-settings WEBAPP_ID --dry-run --data=\'{"params":{"designOptions":{"namingRule":"x"}}}\'',
+        ],
     },
     "stop-backend": {
         handler: async (c, a, f) => {
@@ -47,13 +92,23 @@ export const webappCommands = {
     },
     "restart-backend": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss webapp restart-backend <webappId> [--project-key KEY]");
-            await c.webapps.startOrRestartBackend(a[0], f["project-key"]);
-            return { restarted: true, };
+            requireArgs(a, 1, RESTART_USAGE);
+            const projectKey = f["project-key"];
+            if (f["wait"] === true) {
+                return c.webapps.restartBackendAndWait(a[0], projectKey, {
+                    pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
+                    timeoutMs: num(f["timeout"], "--timeout"),
+                });
+            }
+            const future = await c.webapps.startOrRestartBackend(a[0], projectKey);
+            return { restarted: true, future, };
         },
-        usage: "dss webapp restart-backend <webappId> [--project-key KEY]",
-        description: "Start or restart a webapp's backend.",
-        examples: ["dss webapp restart-backend WEBAPP_ID",],
+        usage: RESTART_USAGE,
+        description: "Start or restart a webapp's backend. The documented endpoint returns a restart future; --wait settles it and returns the FutureWaitResult.",
+        examples: [
+            "dss webapp restart-backend WEBAPP_ID",
+            "dss webapp restart-backend WEBAPP_ID --wait --timeout=60000",
+        ],
     },
     "backend-state": {
         handler: (c, a, f) => {

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

@@ -1,5 +1,6 @@
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { jsonInput, textInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const wikiCommands = {
@@ -31,12 +32,12 @@ export const wikiCommands = {
                 throw new UsageError("--name is required. Usage: dss wiki create --name NAME");
             const content = textInput(f);
             const pk = f["project-key"];
-            if (f["if-not-exists"] === true || f["dry-run"] === true) {
+            if (f["if-not-exists"] === true || executionMode(f).dryRun) {
                 const existing = (await c.wiki.list(pk)).find((article) => article.article.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("wiki", existing.article.id, "exists", { current: existing, });
                 }
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "create",
@@ -75,7 +76,7 @@ export const wikiCommands = {
             if (!data && content === undefined && name === undefined) {
                 throw new UsageError("--name, --content, --file, --data, --data-file, or --stdin is required.");
             }
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.wiki.get(a[0], f["project-key"]);
                 const next = deepMerge(current, data ?? {});
                 if (name !== undefined) {
@@ -105,11 +106,11 @@ export const wikiCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss wiki delete <id-or-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.wiki.get(a[0], pk));
                 if (!current)
                     return skipResult("wiki", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "wiki", article: a[0], current, };
                 }
             }