dataiku-sdk 0.6.0 → 0.6.1

package/dist/src/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createHash, } from "node:crypto";
 import { readFileSync, } from "node:fs";
 import { mkdir, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve, } from "node:path";
@@ -9,6 +10,9 @@ import { validateCredentials, } from "./auth.js";
 import { DataikuClient, } from "./client.js";
 import { deleteCredentials, getCredentialsPath, loadCredentials, maskApiKey, saveCredentials, } from "./config.js";
 import { DataikuError, dataikuErrorCode, } from "./errors.js";
+import { buildDatasetCloneSettings, } from "./resources/datasets.js";
+import { parseJobLogProgress, } from "./resources/jobs.js";
+import { scenarioUpdatePreview, } from "./resources/scenarios.js";
 import { AGENTS, detectAgents, findWorkspaceRoot, installSkill, } from "./skill.js";
 import { appendCleanupLedgerEntry, readCleanupLedger, } from "./utils/cleanup-ledger.js";
 import { deepMerge, } from "./utils/deep-merge.js";
@@ -16,23 +20,62 @@ import { sanitizeFileName, } from "./utils/sanitize.js";
 // ---------------------------------------------------------------------------
 // Utility helpers
 // ---------------------------------------------------------------------------
-const CLI_VERSION = (() => {
-    try {
-        let dir = dirname(fileURLToPath(import.meta.url));
-        for (let i = 0; i < 5; i++) {
-            const candidate = resolve(dir, "package.json");
-            try {
-                return JSON.parse(readFileSync(candidate, "utf-8")).version;
-            }
-            catch {
-                dir = dirname(dir);
-            }
+function findPackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 5; i++) {
+        try {
+            readFileSync(resolve(dir, "package.json"), "utf-8");
+            return dir;
         }
+        catch {
+            dir = dirname(dir);
+        }
+    }
+    return undefined;
+}
+function packageVersion(packageRoot) {
+    if (!packageRoot)
         return "unknown";
+    try {
+        return JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf-8")).version;
     }
     catch {
         return "unknown";
     }
+}
+function gitDirectory(packageRoot) {
+    try {
+        const gitFile = readFileSync(resolve(packageRoot, ".git"), "utf-8").trim();
+        if (gitFile.startsWith("gitdir:")) {
+            return resolve(packageRoot, gitFile.slice("gitdir:".length).trim());
+        }
+    }
+    catch {
+        // Normal checkouts have a .git directory, not a .git file.
+    }
+    return resolve(packageRoot, ".git");
+}
+function gitRevision(packageRoot) {
+    if (!packageRoot)
+        return undefined;
+    try {
+        const gitDir = gitDirectory(packageRoot);
+        const head = readFileSync(resolve(gitDir, "HEAD"), "utf-8").trim();
+        if (!head.startsWith("ref:"))
+            return head.slice(0, 7);
+        const ref = head.slice("ref:".length).trim();
+        const full = readFileSync(resolve(gitDir, ref), "utf-8").trim();
+        return full.slice(0, 7);
+    }
+    catch {
+        return undefined;
+    }
+}
+const PACKAGE_ROOT = findPackageRoot();
+const CLI_VERSION = packageVersion(PACKAGE_ROOT);
+const CLI_VERSION_LABEL = (() => {
+    const revision = gitRevision(PACKAGE_ROOT);
+    return revision ? `${CLI_VERSION}+g${revision}` : CLI_VERSION;
 })();
 function num(v) {
     if (typeof v !== "string")
@@ -70,9 +113,73 @@ function jobLogFilterFromFlag(v) {
     }
     throw new UsageError("Invalid --log-filter value. Use stdout, stderr, user, or errors.", "invalid_enum");
 }
-function recipePayloadBackupPath(recipeName, backupDir) {
+function recipeBackupPath(recipeName, backupDir) {
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    return join(backupDir, `${sanitizeFileName(recipeName, "recipe")}-${stamp}.payload`);
+    return join(backupDir, `${sanitizeFileName(recipeName, "recipe")}-${stamp}.recipe-backup.json`);
+}
+function sha256Hex(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function normalizeLineEndings(value) {
+    return value.replace(/\r\n/g, "\n");
+}
+function stableJson(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((item) => stableJson(item)).join(",")}]`;
+    const entries = Object.entries(value).sort(([a,], [b,]) => a.localeCompare(b));
+    return `{${entries.map(([key, item,]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+}
+function stableHash(value) {
+    return sha256Hex(stableJson(value));
+}
+function recipeCodeEnv(recipe) {
+    const params = recipe.params;
+    if (!params || typeof params !== "object" || Array.isArray(params))
+        return undefined;
+    return params.envSelection;
+}
+function recipeGraph(recipe) {
+    return {
+        inputs: recipe.inputs,
+        outputs: recipe.outputs,
+    };
+}
+function recipeBackupDocument(recipeName, projectKey, current) {
+    return {
+        resource: "recipe",
+        recipeName,
+        projectKey,
+        createdAt: new Date().toISOString(),
+        versionTag: current.recipe.versionTag,
+        payloadHash: sha256Hex(current.payload ?? ""),
+        graphHash: stableHash(recipeGraph(current.recipe)),
+        normalizedPayloadHash: sha256Hex(normalizeLineEndings(current.payload ?? "")),
+        codeEnvHash: stableHash(recipeCodeEnv(current.recipe)),
+        codeEnv: recipeCodeEnv(current.recipe),
+        recipe: current.recipe,
+        payload: current.payload ?? "",
+    };
+}
+function readRecipeBackup(backupPath) {
+    const raw = readFileSync(backupPath, "utf-8");
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && parsed.resource === "recipe")
+            return parsed;
+    }
+    catch {
+        // Backward-compatible payload-only backups are handled below.
+    }
+    return {
+        resource: "recipe",
+        recipeName: "unknown",
+        payloadHash: sha256Hex(raw),
+        payload: raw,
+    };
 }
 function recipeRunShouldWait(flags) {
     if (flags["wait"] === true && flags["no-wait"] === true) {
@@ -92,6 +199,54 @@ function splitCsvFlag(v) {
         return [];
     return v.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
 }
+function recipeInputDatasetsFromFlags(flags) {
+    const inputs = splitCsvFlag(flags["input"]);
+    return inputs.length > 0 ? inputs : undefined;
+}
+function rewritePairsFromFlags(flags, flagName) {
+    const rewrites = {};
+    for (const spec of splitCsvFlag(flags[flagName])) {
+        const idx = spec.indexOf("=");
+        if (idx <= 0 || idx === spec.length - 1) {
+            throw new UsageError(`--${flagName} values must use FROM=TO.`, "invalid_enum");
+        }
+        const from = spec.slice(0, idx).trim();
+        const to = spec.slice(idx + 1).trim();
+        if (!from || !to)
+            throw new UsageError(`--${flagName} values must use FROM=TO.`, "invalid_enum");
+        rewrites[from] = to;
+    }
+    return rewrites;
+}
+function plainRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function datasetSourceSummary(details) {
+    const params = details.params ?? {};
+    return {
+        resource: "dataset",
+        name: details.name,
+        projectKey: details.projectKey,
+        type: details.type,
+        managed: details.managed,
+        connection: params.connection,
+        catalog: params.catalog,
+        schema: params.schema,
+        table: params.table,
+        path: params.path,
+        folderSmartId: params.folderSmartId,
+        formatType: details.formatType,
+    };
+}
+function requiredStringFlag(flags, name, usage) {
+    const value = flags[name];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new UsageError(`--${name} is required. Usage: ${usage}`, "missing_required_flag");
+    }
+    return value.trim();
+}
 function flowZoneId(value) {
     const trimmed = value.trim();
     if (!trimmed)
@@ -162,35 +317,264 @@ function flowZoneMoveItems(flags) {
     }
     return items;
 }
-function json(v) {
+function flowZoneItems(zone) {
+    return [...(zone.items ?? []), ...(zone.shared ?? []),];
+}
+function flowZoneContains(zone, object) {
+    return flowZoneItems(zone).some((item) => item.objectId === object.objectId
+        && item.objectType === object.objectType
+        && (object.projectKey === undefined || item.projectKey === object.projectKey));
+}
+function flowZoneSummary(zone, object) {
+    const items = flowZoneItems(zone);
+    return {
+        id: zone.id,
+        name: zone.name,
+        itemCount: items.length,
+        ...(object ? { containsMatchingObject: flowZoneContains(zone, object), } : {}),
+    };
+}
+function flowZoneDetailSummary(zone) {
+    return {
+        ...flowZoneSummary(zone),
+        items: flowZoneItems(zone),
+    };
+}
+async function resolveFlowZoneIdFromFlags(client, flags, projectKey) {
+    const zoneId = typeof flags["zone-id"] === "string" ? flags["zone-id"].trim() : "";
+    if (zoneId)
+        return zoneId;
+    const zone = typeof flags["zone"] === "string" ? flags["zone"].trim() : "";
+    if (!zone)
+        return undefined;
+    const zones = await client.flowZones.list(projectKey);
+    const match = zones.find((candidate) => candidate.id === zone || candidate.name === zone);
+    if (!match)
+        throw new UsageError(`Flow zone not found: ${zone}`, "invalid_enum");
+    return match.id;
+}
+async function moveCreatedItemsToZone(client, flags, items, projectKey) {
+    const zoneId = await resolveFlowZoneIdFromFlags(client, flags, projectKey);
+    if (!zoneId || items.length === 0)
+        return {};
+    await client.flowZones.moveItems(zoneId, items, projectKey);
+    return { zoneId, moved: items, };
+}
+function nestedValue(value, path) {
+    let current = value;
+    for (const key of path) {
+        const record = plainRecord(current);
+        if (!record)
+            return undefined;
+        current = record[key];
+    }
+    return current;
+}
+function stringPath(value, path) {
+    const item = nestedValue(value, path);
+    return typeof item === "string" && item.length > 0 ? item : undefined;
+}
+function numberPath(value, path) {
+    const item = nestedValue(value, path);
+    return typeof item === "number" && Number.isFinite(item) ? item : undefined;
+}
+function firstNumberPath(value, paths) {
+    for (const path of paths) {
+        const item = numberPath(value, path);
+        if (item !== undefined)
+            return item;
+    }
+    return undefined;
+}
+function jobSummaryId(job, fallback) {
+    return stringPath(job, ["baseStatus", "def", "id",])
+        ?? stringPath(job, ["def", "id",])
+        ?? stringPath(job, ["id",])
+        ?? fallback
+        ?? "unknown";
+}
+function jobSummaryType(job) {
+    return stringPath(job, ["baseStatus", "def", "type",])
+        ?? stringPath(job, ["def", "type",])
+        ?? stringPath(job, ["type",])
+        ?? "unknown";
+}
+function jobSummaryState(job) {
+    return stringPath(job, ["baseStatus", "state",])
+        ?? stringPath(job, ["state",])
+        ?? "unknown";
+}
+function filteredJobList(jobs, flags) {
+    const state = typeof flags["state"] === "string" ? flags["state"].trim().toUpperCase() : "";
+    const contains = typeof flags["contains"] === "string"
+        ? flags["contains"].trim().toLowerCase()
+        : "";
+    const output = typeof flags["output"] === "string" ? flags["output"].trim().toLowerCase() : "";
+    let result = jobs.filter((job) => {
+        if (state && jobSummaryState(job).toUpperCase() !== state)
+            return false;
+        const text = JSON.stringify(job).toLowerCase();
+        if (contains && !text.includes(contains))
+            return false;
+        if (output && !text.includes(output))
+            return false;
+        return true;
+    });
+    const limit = flags["latest"] === true ? 1 : num(flags["limit"]);
+    if (limit !== undefined)
+        result = result.slice(0, Math.max(0, limit));
+    return result;
+}
+function maxNumber(values) {
+    return values.length === 0 ? 0 : Math.max(...values);
+}
+function collectWarningCounts(value, inActivity, counts) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectWarningCounts(item, inActivity, counts);
+        return;
+    }
+    const record = plainRecord(value);
+    if (!record)
+        return;
+    for (const [key, item,] of Object.entries(record)) {
+        const lower = key.toLowerCase();
+        const nextInActivity = inActivity || lower.includes("activit");
+        if (lower.includes("warn")) {
+            const target = nextInActivity ? counts.activity : counts.dss;
+            if (typeof item === "number" && Number.isFinite(item))
+                target.push(item);
+            else if (Array.isArray(item))
+                target.push(item.length);
+        }
+        collectWarningCounts(item, nextInActivity, counts);
+    }
+}
+function jobWarningSummary(details, log) {
+    const counts = { dss: [], activity: [], };
+    collectWarningCounts(details, false, counts);
+    const warningLines = log
+        ? log.split(/\r?\n/).map((line) => line.trim()).filter((line) => /\bwarn(?:ing)?\b/i.test(line))
+        : [];
+    return {
+        dssSummaryWarningCount: maxNumber(counts.dss),
+        activityWarningCount: maxNumber(counts.activity),
+        logWarnLineCount: warningLines.length,
+        sampledWarningMessages: warningLines.slice(0, 5),
+    };
+}
+function jobDurationMs(details) {
+    const started = firstNumberPath(details, [
+        ["baseStatus", "startTime",],
+        ["baseStatus", "start",],
+        ["startTime",],
+        ["start",],
+    ]);
+    const ended = firstNumberPath(details, [
+        ["baseStatus", "endTime",],
+        ["baseStatus", "end",],
+        ["endTime",],
+        ["end",],
+    ]);
+    return started !== undefined && ended !== undefined && ended >= started
+        ? ended - started
+        : undefined;
+}
+async function jobInspectionSummary(client, jobId, flags) {
+    const projectKey = flags["project-key"];
+    const details = await client.jobs.get(jobId, projectKey);
+    let log;
+    let logError;
+    try {
+        log = await client.jobs.log(jobId, {
+            activity: flags["activity"],
+            logId: flags["log-id"],
+            maxLogLines: maxLogLinesFromFlags(flags),
+            projectKey,
+        });
+    }
+    catch (error) {
+        logError = error instanceof Error ? error.message : String(error);
+    }
+    const durationMs = jobDurationMs(details);
+    const progress = log ? parseJobLogProgress(log, durationMs) : undefined;
+    const logLines = log
+        ? log.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0)
+        : [];
+    const maxSummaryLines = Math.max(1, maxLogLinesFromFlags(flags) ?? 20);
+    const outputs = nestedValue(details, ["baseStatus", "def", "outputs",])
+        ?? nestedValue(details, ["def", "outputs",])
+        ?? details.outputs;
+    return {
+        resource: "job",
+        jobId: jobSummaryId(details, jobId),
+        state: jobSummaryState(details),
+        type: jobSummaryType(details),
+        ...(durationMs !== undefined ? { durationMs, } : {}),
+        ...(outputs !== undefined ? { outputs, } : {}),
+        warnings: jobWarningSummary(details, log),
+        ...(progress
+            ? {
+                progress,
+                latestUsefulProgressLine: progress.lastProgressLine,
+                doneLine: progress.doneLine,
+            }
+            : {}),
+        logSummary: {
+            lineCount: logLines.length,
+            lines: logLines.slice(-maxSummaryLines),
+            ...(logError ? { error: logError, } : {}),
+        },
+    };
+}
+function stripUtf8Bom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+function parseJsonValue(text, source) {
+    try {
+        return JSON.parse(stripUtf8Bom(text));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new UsageError(`Invalid JSON in ${source}: ${message}`, "validation_failed");
+    }
+}
+function expectJsonObject(value, source) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    throw new UsageError(`Expected JSON object in ${source}.`, "validation_failed");
+}
+function parseJsonObject(text, source) {
+    return expectJsonObject(parseJsonValue(text, source), source);
+}
+function json(v, source = "JSON flag") {
     if (typeof v !== "string")
         return undefined;
-    return JSON.parse(v);
+    return parseJsonObject(v, source);
 }
 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] [--request-timeout MS] [--project-key KEY]";
 function readStdinText() {
     return readFileSync(0, "utf-8");
 }
 function jsonInput(flags) {
-    if (flags["stdin"] === true) {
-        return JSON.parse(readStdinText());
-    }
+    if (flags["stdin"] === true)
+        return parseJsonObject(readStdinText(), "stdin");
     if (typeof flags["data-file"] === "string") {
-        return JSON.parse(readFileSync(flags["data-file"], "utf-8"));
-    }
-    if (typeof flags["data"] === "string") {
-        return JSON.parse(flags["data"]);
+        return parseJsonObject(readFileSync(flags["data-file"], "utf-8"), flags["data-file"]);
     }
+    if (typeof flags["data"] === "string")
+        return parseJsonObject(flags["data"], "--data");
     return undefined;
 }
 function unknownJsonInput(flags) {
     if (flags["stdin"] === true)
-        return JSON.parse(readStdinText());
+        return parseJsonValue(readStdinText(), "stdin");
     if (typeof flags["data-file"] === "string") {
-        return JSON.parse(readFileSync(flags["data-file"], "utf-8"));
+        return parseJsonValue(readFileSync(flags["data-file"], "utf-8"), flags["data-file"]);
     }
     if (typeof flags["data"] === "string")
-        return JSON.parse(flags["data"]);
+        return parseJsonValue(flags["data"], "--data");
     return undefined;
 }
 function schemaColumnsInput(flags, usage) {
@@ -234,7 +618,7 @@ function textInput(flags) {
 }
 function requiredJsonInput(flags, message) {
     const data = jsonInput(flags);
-    if (!data)
+    if (data === undefined)
         throw new UsageError(message);
     return data;
 }
@@ -400,7 +784,11 @@ function isFailedWaitResult(result) {
         && (typeof record.state === "string" || typeof record.outcome === "string");
 }
 function commandFailureExitCode(result) {
-    return isFailedWaitResult(result) ? 4 : undefined;
+    if (isFailedWaitResult(result))
+        return 4;
+    if (result && typeof result === "object" && result.unchanged === false)
+        return 4;
+    return undefined;
 }
 function isNotFoundError(error) {
     if (error instanceof DataikuError)
@@ -462,7 +850,7 @@ function resultRecord(result) {
         : {};
 }
 function cleanupLedgerEntry(resource, action, args, flags, result, projectKey) {
-    if (!(action.startsWith("create") || action === "upload"))
+    if (!(action.startsWith("create") || action === "clone" || action === "upload"))
         return undefined;
     const record = resultRecord(result);
     if (record.skipped !== undefined)
@@ -482,6 +870,16 @@ function cleanupLedgerEntry(resource, action, args, flags, result, projectKey) {
                 cleanup: { argv: ["dataset", "delete", name, "--if-exists", ...withProject,], },
             };
         }
+        case "dataset.clone": {
+            const name = stringField(record, ["target", "created", "name",]) ?? args[1];
+            if (!name)
+                return undefined;
+            return {
+                ...base,
+                name,
+                cleanup: { argv: ["dataset", "delete", name, "--if-exists", ...withProject,], },
+            };
+        }
         case "recipe.create": {
             const name = stringField(record, ["created", "recipeName", "name",])
                 ?? flags["name"];
@@ -493,6 +891,17 @@ function cleanupLedgerEntry(resource, action, args, flags, result, projectKey) {
                 cleanup: { argv: ["recipe", "delete", name, "--if-exists", ...withProject,], },
             };
         }
+        case "recipe.clone": {
+            const name = stringField(record, ["recipeName", "target", "created", "name",])
+                ?? flags["name"];
+            if (!name)
+                return undefined;
+            return {
+                ...base,
+                name,
+                cleanup: { argv: ["recipe", "delete", name, "--if-exists", ...withProject,], },
+            };
+        }
         case "scenario.create": {
             const id = args[0];
             return {
@@ -606,6 +1015,7 @@ const BOOLEAN_FLAGS = new Set([
     "global",
     "list-agents",
     "include-raw",
+    "raw",
     "include-payload",
     "no-payload",
     "include-logs",
@@ -624,7 +1034,12 @@ const BOOLEAN_FLAGS = new Set([
     "report-json",
     "no-wait",
     "force-rebuild",
+    "latest",
+    "copy-output-settings",
     "continue-on-error",
+    "no-backup",
+    "payload-only",
+    "allow-same-path",
 ]);
 const SHORT_FLAGS = {
     h: "help",
@@ -639,6 +1054,7 @@ const FLAG_ALIASES = {
     "skip-tls-verify": "insecure",
     "extra-ca-certs": "ca-cert",
     explain: "plan",
+    "zone-name": "zone",
 };
 const VALUE_FLAGS = new Set([
     "activity",
@@ -646,12 +1062,14 @@ const VALUE_FLAGS = new Set([
     "api-key",
     "build-mode",
     "backup-dir",
+    "backup",
     "ca-cert",
     "catalog",
     "cell-id",
     "allow-types",
     "color",
     "connection",
+    "contains",
     "content",
     "content-type",
     "data",
@@ -665,6 +1083,7 @@ const VALUE_FLAGS = new Set([
     "install-core-packages",
     "folder",
     "input",
+    "from",
     "knowledge-bank",
     "labeling-task",
     "lang",
@@ -677,14 +1096,17 @@ const VALUE_FLAGS = new Set([
     "listed",
     "max-nodes",
     "max-rows",
+    "limit",
     "max-timestamp",
     "only-monitored",
     "min-timestamp",
     "mode",
     "log-filter",
+    "log-id",
     "model-evaluation-store",
     "name",
     "object",
+    "metastore-table",
     "output",
     "output-file",
     "output-connection",
@@ -703,18 +1125,38 @@ const VALUE_FLAGS = new Set([
     "retries",
     "poll-interval",
     "python-interpreter",
+    "replace-input",
+    "replace-output",
+    "replace-payload-text",
     "retain",
     "saved-model",
     "sql",
     "schema",
     "sql-file",
     "standard",
+    "state",
     "streaming-endpoint",
     "target",
     "target-type",
     "timeout",
+    "table",
     "type",
     "url",
+    "until",
+    "to",
+    "zone",
+    "zone-id",
+]);
+const REPEATABLE_VALUE_FLAGS = new Set([
+    "dataset",
+    "folder",
+    "input",
+    "object",
+    "package",
+    "recipe",
+    "replace-input",
+    "replace-output",
+    "replace-payload-text",
 ]);
 const KNOWN_LONG_FLAGS = new Set([
     ...BOOLEAN_FLAGS,
@@ -738,6 +1180,14 @@ function requireFlagValue(flagLabel, next) {
     }
     return next;
 }
+function setParsedFlagValue(flags, flagName, value) {
+    const current = flags[flagName];
+    if (REPEATABLE_VALUE_FLAGS.has(flagName) && typeof current === "string" && current.length > 0) {
+        flags[flagName] = `${current},${value}`;
+        return;
+    }
+    flags[flagName] = value;
+}
 function parseArgs(argv) {
     const positional = [];
     const flags = {};
@@ -753,7 +1203,7 @@ function parseArgs(argv) {
             if (eqIdx !== -1) {
                 const raw = arg.slice(2, eqIdx);
                 const flagName = normalizeLongFlag(raw);
-                flags[flagName] = arg.slice(eqIdx + 1);
+                setParsedFlagValue(flags, flagName, arg.slice(eqIdx + 1));
             }
             else {
                 const rawFlagName = arg.slice(2);
@@ -763,7 +1213,7 @@ function parseArgs(argv) {
                 }
                 else {
                     const next = requireFlagValue(`--${rawFlagName}`, argv[i + 1]);
-                    flags[flagName] = next;
+                    setParsedFlagValue(flags, flagName, next);
                     i++;
                 }
             }
@@ -776,7 +1226,7 @@ function parseArgs(argv) {
                 }
                 else {
                     const next = requireFlagValue(`-${arg[1]}`, argv[i + 1]);
-                    flags[long] = next;
+                    setParsedFlagValue(flags, long, next);
                     i++;
                 }
             }
@@ -1485,10 +1935,45 @@ const commands = {
     },
     "flow-zone": {
         list: {
-            handler: (c, _a, f) => c.flowZones.list(f["project-key"]),
-            usage: "dss flow-zone list [--project-key KEY]",
-            description: "List flow zones in a project.",
-            examples: ["dss flow-zone 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) => {
@@ -1583,7 +2068,11 @@ const commands = {
         },
         move: {
             handler: async (c, a, f) => {
-                requireArgs(a, 1, "dss flow-zone move <id> [--dataset DS] [--recipe R] [--folder F] [--object TYPE:ID]");
+                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.");
@@ -1593,17 +2082,17 @@ const commands = {
                         dryRun: true,
                         action: "move",
                         resource: "flow-zone",
-                        id: flowZoneId(a[0]),
+                        id: zoneId,
                         items,
                     };
                 }
-                return c.flowZones.moveItems(flowZoneId(a[0]), items, f["project-key"]);
+                return c.flowZones.moveItems(zoneId, items, pk);
             },
-            usage: "dss flow-zone move <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.",
+            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_ID --dataset raw_orders,clean_orders --recipe prepare_orders",
+                "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",
             ],
@@ -1643,6 +2132,15 @@ const commands = {
             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]";
@@ -1727,6 +2225,7 @@ const commands = {
                     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);
@@ -1741,17 +2240,57 @@ const commands = {
                             name,
                             payload,
                             ...(existing ? { current: existing, } : {}),
+                            ...(zoneId ? { zoneId, zoneMove: [{ objectId: name, objectType: "DATASET", },], } : {}),
                         };
                     }
                 }
                 await c.datasets.create(payload);
-                return { created: name, resource: "dataset", };
+                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 [--if-not-exists] [--dry-run] [--project-key KEY]",
+            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 --dry-run",
+                "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: {
@@ -1942,15 +2481,20 @@ const commands = {
                 }
                 const name = f["name"];
                 const pk = f["project-key"];
+                const inputDatasets = recipeInputDatasetsFromFlags(f);
                 const payload = {
                     type,
                     name,
-                    inputDatasets: f["input"] ? [f["input"],] : undefined,
+                    inputDatasets,
                     outputDataset,
                     outputFolder,
                     outputConnection: f["output-connection"],
                     projectKey: pk,
                 };
+                const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
+                const zoneMove = zoneId && name
+                    ? [{ objectId: name, objectType: "RECIPE", },]
+                    : undefined;
                 if ((f["if-not-exists"] === true || f["dry-run"] === true) && name) {
                     const list = await c.recipes.list(pk);
                     const existing = list.find((r) => r.name === name);
@@ -1964,24 +2508,106 @@ const commands = {
                             resource: "recipe",
                             name,
                             payload,
+                            ...(zoneId ? { zoneId, zoneMove, } : {}),
                             ...(existing ? { current: existing, } : {}),
                         };
                     }
                 }
                 if (f["dry-run"] === true) {
-                    return { dryRun: true, action: "create", resource: "recipe", payload, };
+                    return {
+                        dryRun: true,
+                        action: "create",
+                        resource: "recipe",
+                        payload,
+                        ...(zoneId ? { zoneId, zoneMove, } : {}),
+                    };
                 }
                 const created = await c.recipes.create(payload);
-                return { created: created.recipeName, resource: "recipe", ...created, };
+                const createdName = created.recipeName;
+                const moved = await moveCreatedItemsToZone(c, f, [{
+                        objectId: createdName,
+                        objectType: "RECIPE",
+                    },], pk);
+                return { created: createdName, resource: "recipe", ...created, ...moved, };
             },
-            usage: "dss recipe create --type TYPE --input DS (--output DS | --output-folder FOLDER_ID) [--name NAME] [--output-connection CONN] [--if-not-exists] [--dry-run] [--project-key KEY]",
-            description: "Create a recipe with a dataset output, or use --output-folder with --output-connection for a managed-folder output.",
+            usage: "dss recipe create --type TYPE --input DS[,DS2] (--output DS | --output-folder FOLDER_ID) [--name NAME] [--output-connection CONN] [--zone ZONE|--zone-id ID] [--if-not-exists] [--dry-run] [--project-key KEY]",
+            description: "Create a recipe with one or more inputs and a dataset or managed-folder output.",
             examples: [
-                "dss recipe create --type python --input orders --output orders_clean",
-                "dss recipe create --type python --input orders --output orders_clean --output-connection filesystem",
+                "dss recipe create --type python --input raw_orders,lookup --output orders_clean",
+                "dss recipe create --type python --input orders --input customers --output orders_clean --zone Experiments",
                 "dss recipe create --type python --input orders --output-folder LT7TUHJ8 --output-connection filesystem --dry-run",
             ],
         },
+        clone: {
+            handler: async (c, a, f) => {
+                const usage = "dss recipe clone [source|--from SOURCE] (--name NAME|--to NAME) [--replace-input FROM=TO] [--replace-output FROM=TO] [--replace-payload-text FROM=TO] [--output DATASET] [--copy-output-settings] [--path PATH] [--metastore-table TABLE] [--zone ZONE|--zone-id ID] [--dry-run] [--project-key KEY]";
+                const fromFlag = typeof f["from"] === "string" ? f["from"].trim() : "";
+                const sourceName = a[0] ?? fromFlag;
+                if (!sourceName) {
+                    throw new UsageError(`Source recipe is required. Usage: ${usage}`, "missing_required_flag");
+                }
+                if (a[0] && fromFlag && a[0] !== fromFlag) {
+                    throw new UsageError("Positional source and --from must match when both are provided.", "invalid_enum");
+                }
+                const pk = f["project-key"];
+                const toFlag = typeof f["to"] === "string" ? f["to"].trim() : "";
+                const nameFlag = typeof f["name"] === "string" ? f["name"].trim() : "";
+                const name = toFlag || nameFlag;
+                if (!name) {
+                    throw new UsageError(`--name or --to is required. Usage: ${usage}`, "missing_required_flag");
+                }
+                const inputRewrites = rewritePairsFromFlags(f, "replace-input");
+                const outputRewrites = rewritePairsFromFlags(f, "replace-output");
+                const payloadTextRewrites = rewritePairsFromFlags(f, "replace-payload-text");
+                const opts = {
+                    projectKey: pk,
+                    name,
+                    outputDataset: f["output"],
+                    outputRewrites,
+                    inputRewrites,
+                    payloadTextRewrites,
+                    copyOutputSettings: f["copy-output-settings"] === true,
+                    outputPath: f["path"],
+                    metastoreTableName: f["metastore-table"],
+                };
+                const source = await c.recipes.get(sourceName, { includePayload: true, projectKey: pk, });
+                const outputItems = Object.values((source.recipe.outputs ?? {})).flatMap((role) => role.items ?? []).filter((item) => typeof item.ref === "string");
+                const plannedOutputRewrites = { ...outputRewrites, };
+                if (opts.outputDataset !== undefined && outputItems.length === 1) {
+                    plannedOutputRewrites[outputItems[0].ref] = opts.outputDataset;
+                }
+                if (opts.copyOutputSettings === true
+                    && Object.keys(plannedOutputRewrites).length > 1
+                    && (opts.outputPath !== undefined || opts.metastoreTableName !== undefined)) {
+                    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) {
+                    return {
+                        dryRun: true,
+                        action: "clone",
+                        resource: "recipe",
+                        source: sourceName,
+                        target: name,
+                        inputRewrites,
+                        outputRewrites: plannedOutputRewrites,
+                        copyOutputSettings: opts.copyOutputSettings,
+                        payloadTextRewrites,
+                        current: source,
+                        ...(zoneId ? { zoneId, zoneMove: [{ objectId: name, objectType: "RECIPE", },], } : {}),
+                    };
+                }
+                const cloned = await c.recipes.clone(sourceName, opts);
+                const moved = await moveCreatedItemsToZone(c, f, [{ objectId: name, objectType: "RECIPE", },], pk);
+                return { ...cloned, resource: "recipe", ...moved, };
+            },
+            usage: "dss recipe clone [source|--from SOURCE] (--name NAME|--to NAME) [--replace-input FROM=TO] [--replace-output FROM=TO] [--replace-payload-text FROM=TO] [--output DATASET] [--copy-output-settings] [--path PATH] [--metastore-table TABLE] [--zone ZONE|--zone-id ID] [--dry-run] [--project-key KEY]",
+            description: "Clone a recipe graph/settings/payload into a separate experiment recipe.",
+            examples: [
+                "dss recipe clone compute_orders --name compute_orders_opt --output orders_opt --copy-output-settings --dry-run",
+                "dss recipe clone compute_orders --name compute_orders_opt --output orders_opt --zone Experiments",
+            ],
+        },
         diff: {
             handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss recipe diff <name> --file PATH");
@@ -2046,13 +2672,24 @@ const commands = {
                 }
                 return payload;
             },
-            usage: "dss recipe get-payload <name> [--output PATH] [--project-key KEY]",
-            description: "Print the recipe code payload to stdout.",
+            usage: "dss recipe get-payload <name> [--raw] [--output PATH] [--project-key KEY]",
+            description: "Print the recipe code payload to stdout; use --raw for pipeable code bytes.",
             examples: [
-                "dss recipe get-payload compute_orders",
+                "dss recipe get-payload compute_orders --raw",
                 "dss recipe get-payload compute_orders -o code.py",
             ],
         },
+        cat: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss recipe cat <name> [--raw]");
+                return c.recipes.getPayload(a[0], {
+                    projectKey: f["project-key"],
+                });
+            },
+            usage: "dss recipe cat <name> [--raw] [--project-key KEY]",
+            description: "Print a recipe code payload; combine with --raw for shell pipes and diffs.",
+            examples: ["dss recipe cat compute_orders --raw",],
+        },
         "set-payload": {
             handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss recipe set-payload <name> --file PATH");
@@ -2060,13 +2697,17 @@ const commands = {
                 if (!filePath)
                     throw new UsageError("--file is required.");
                 const content = readFileSync(filePath, "utf-8");
-                const backupDir = f["backup-dir"];
-                const backupPath = backupDir ? recipePayloadBackupPath(a[0], backupDir) : undefined;
+                const pk = f["project-key"];
+                const shouldBackup = f["no-backup"] !== true;
+                const backupDir = shouldBackup
+                    ? f["backup-dir"] ?? join(process.cwd(), ".dss-backups", "recipes")
+                    : undefined;
+                const backupPath = backupDir ? recipeBackupPath(a[0], backupDir) : undefined;
+                const current = await c.recipes.get(a[0], {
+                    projectKey: pk,
+                    includePayload: true,
+                });
                 if (f["dry-run"] === true) {
-                    const current = await c.recipes.get(a[0], {
-                        projectKey: f["project-key"],
-                        includePayload: true,
-                    });
                     return {
                         dryRun: true,
                         action: "set-payload",
@@ -2075,41 +2716,140 @@ const commands = {
                         file: filePath,
                         current,
                         next: { ...current, payload: content, },
-                        ...(backupPath ? { backupPath, } : {}),
+                        ...(backupPath ? { backupPath, backup: recipeBackupDocument(a[0], pk, current), } : {}),
                     };
                 }
                 if (backupDir && backupPath) {
-                    const current = await c.recipes.get(a[0], {
-                        projectKey: f["project-key"],
-                        includePayload: true,
-                    });
                     await mkdir(backupDir, { recursive: true, });
-                    await writeFile(backupPath, current.payload ?? "", "utf-8");
+                    await writeFile(backupPath, `${JSON.stringify(recipeBackupDocument(a[0], pk, current), null, 2)}\n`, "utf-8");
                 }
-                await c.recipes.setPayload(a[0], content, {
-                    projectKey: f["project-key"],
-                });
+                await c.recipes.replace(a[0], { ...current, payload: content, }, pk);
                 return {
                     updated: a[0],
                     resource: "recipe",
                     file: filePath,
+                    backupCreated: backupPath !== undefined,
                     ...(backupPath ? { backupPath, } : {}),
                 };
             },
-            usage: "dss recipe set-payload <name> --file PATH [--backup-dir DIR] [--dry-run] [--project-key KEY]",
-            description: "Upload recipe code from a local file, optionally backing up the remote payload first.",
+            usage: "dss recipe set-payload <name> --file PATH [--backup-dir DIR|--no-backup] [--dry-run] [--project-key KEY]",
+            description: "Upload recipe code from a local file, backing up payload, graph, settings, and version metadata by default.",
             examples: [
                 "dss recipe set-payload compute_orders --file code.py --dry-run",
                 "dss recipe set-payload compute_orders --file code.py --backup-dir ./backups",
+                "dss recipe set-payload compute_orders --file code.py --no-backup",
+            ],
+        },
+        restore: {
+            handler: async (c, a, f) => {
+                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 payload = typeof backup.payload === "string" ? backup.payload : "";
+                const pk = f["project-key"];
+                const current = await c.recipes.get(a[0], { includePayload: true, projectKey: pk, });
+                const backupRecipe = backup.recipe && typeof backup.recipe === "object" && !Array.isArray(backup.recipe)
+                    ? backup.recipe
+                    : undefined;
+                const restoredRecipe = backupRecipe
+                    ? { ...backupRecipe, name: a[0], ...(pk ? { projectKey: pk, } : {}), }
+                    : undefined;
+                const next = f["payload-only"] === true || !restoredRecipe
+                    ? { ...current, payload, }
+                    : { ...current, recipe: restoredRecipe, payload, };
+                if (f["dry-run"] === true) {
+                    return {
+                        dryRun: true,
+                        action: "restore",
+                        resource: "recipe",
+                        name: a[0],
+                        backupPath,
+                        current,
+                        next,
+                    };
+                }
+                await c.recipes.replace(a[0], next, pk);
+                return {
+                    restored: a[0],
+                    resource: "recipe",
+                    backupPath,
+                    payloadOnly: f["payload-only"] === true,
+                };
+            },
+            usage: "dss recipe restore <name> --backup FILE [--payload-only] [--dry-run] [--project-key KEY]",
+            description: "Restore a recipe from a set-payload backup.",
+            examples: [
+                "dss recipe restore compute_orders --backup .dss-backups/recipes/backup.recipe-backup.json --dry-run",
+            ],
+        },
+        "assert-unchanged": {
+            handler: async (c, a, f) => {
+                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 current = await c.recipes.get(a[0], {
+                    includePayload: true,
+                    projectKey: f["project-key"],
+                });
+                const payloadHash = sha256Hex(current.payload ?? "");
+                const normalizedPayloadHash = sha256Hex(normalizeLineEndings(current.payload ?? ""));
+                const expectedPayloadHash = typeof backup.payloadHash === "string"
+                    ? backup.payloadHash
+                    : undefined;
+                const expectedNormalizedPayloadHash = typeof backup.normalizedPayloadHash === "string"
+                    ? backup.normalizedPayloadHash
+                    : typeof backup.payload === "string"
+                        ? sha256Hex(normalizeLineEndings(backup.payload))
+                        : undefined;
+                const checks = [
+                    {
+                        name: "payload",
+                        expected: expectedPayloadHash,
+                        actual: payloadHash,
+                        unchanged: expectedPayloadHash === payloadHash
+                            || (expectedNormalizedPayloadHash !== undefined
+                                && expectedNormalizedPayloadHash === normalizedPayloadHash),
+                        normalizedExpected: expectedNormalizedPayloadHash,
+                        normalizedActual: normalizedPayloadHash,
+                    },
+                    {
+                        name: "graph",
+                        expected: backup.graphHash,
+                        actual: stableHash(recipeGraph(current.recipe)),
+                        unchanged: backup.graphHash === stableHash(recipeGraph(current.recipe)),
+                    },
+                    {
+                        name: "codeEnv",
+                        expected: backup.codeEnvHash,
+                        actual: stableHash(recipeCodeEnv(current.recipe)),
+                        unchanged: backup.codeEnvHash === stableHash(recipeCodeEnv(current.recipe)),
+                    },
+                ].filter((check) => typeof check.expected === "string");
+                const failures = checks.filter((check) => !check.unchanged);
+                return {
+                    unchanged: failures.length === 0,
+                    resource: "recipe",
+                    name: a[0],
+                    backupPath,
+                    checks,
+                    failures,
+                };
+            },
+            usage: "dss recipe assert-unchanged <name> --since BACKUP [--project-key KEY]",
+            description: "Compare current recipe payload, graph, and code env against a backup.",
+            examples: [
+                "dss recipe assert-unchanged compute_orders --since .dss-backups/recipes/backup.recipe-backup.json",
             ],
         },
     },
     job: {
         list: {
-            handler: (c, _a, f) => c.jobs.list(f["project-key"]),
-            usage: "dss job list [--project-key KEY]",
-            description: "List recent jobs.",
-            examples: ["dss job list",],
+            handler: async (c, _a, f) => filteredJobList(await c.jobs.list(f["project-key"]), f),
+            usage: "dss job list [--state STATE] [--contains TEXT] [--output ID] [--latest] [--limit N] [--project-key KEY]",
+            description: "List recent jobs, optionally filtered for automation.",
+            examples: ["dss job list --state DONE --latest", "dss job list --contains WLM225S --limit 10",],
         },
         get: {
             handler: (c, a, f) => {
@@ -2120,18 +2860,42 @@ const commands = {
             description: "Get job details.",
             examples: ["dss job get JOB_ID",],
         },
+        summary: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss job summary <id>");
+                return jobInspectionSummary(c, a[0], f);
+            },
+            usage: "dss job summary <id> [--activity ACTIVITY_ID] [--log-id LOG_ID] [--max-lines N|--max-log-lines N] [--project-key KEY]",
+            description: "Summarize job state, outputs, warnings, progress, and useful terminal log lines.",
+            examples: ["dss job summary JOB_ID --max-log-lines 200",],
+        },
         log: {
             handler: (c, a, f) => {
                 requireArgs(a, 1, "dss job log <id>");
                 return c.jobs.log(a[0], {
                     activity: f["activity"],
+                    logId: f["log-id"],
                     maxLogLines: maxLogLinesFromFlags(f),
                     projectKey: f["project-key"],
                 });
             },
-            usage: "dss job log <id> [--activity NAME] [--max-lines N|--max-log-lines N]",
-            description: "Get log output for a job.",
-            examples: ["dss job log JOB_ID", "dss job log JOB_ID --activity main --max-log-lines 200",],
+            usage: "dss job log <id> [--activity ACTIVITY_ID] [--log-id LOG_ID] [--max-lines N|--max-log-lines N] [--project-key KEY]",
+            description: "Get public API job log output. --log-id is accepted for UI parity but DSS API-key auth cannot select browser-only cat-activity-log files.",
+            examples: [
+                "dss job log JOB_ID",
+                "dss job log JOB_ID --activity main --max-log-lines 200",
+            ],
+        },
+        "log-url": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss job log-url <url>");
+                return c.jobs.logFromUrl(a[0], { maxLogLines: maxLogLinesFromFlags(f), });
+            },
+            usage: "dss job log-url <url> [--max-lines N|--max-log-lines N]",
+            description: "Fetch a DSS cat-activity-log URL pasted from the UI.",
+            examples: [
+                'dss job log-url "https://dss/dip/api/flow/jobs/cat-activity-log?projectKey=TEST&jobId=JOB&activityId=A&logId=L"',
+            ],
         },
         build: {
             handler: async (c, a, f) => {
@@ -2225,6 +2989,44 @@ const commands = {
                 "dss job wait JOB_ID --include-logs --log-filter stdout --summary --timeout 60000",
             ],
         },
+        monitor: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss job monitor <id...>");
+                const options = {
+                    includeLogs: f["include-logs"] === true,
+                    logFilter: jobLogFilterFromFlag(f["log-filter"]),
+                    maxLogLines: maxLogLinesFromFlags(f),
+                    pollIntervalMs: num(f["poll-interval"]),
+                    timeoutMs: num(f["timeout"]),
+                    summary: f["summary"] !== false,
+                    projectKey: f["project-key"],
+                };
+                const jobs = await Promise.all(a.map((jobId) => c.jobs.wait(jobId, options)));
+                return a.length === 1 ? jobs[0] : { jobs, until: f["until"] ?? "all-done", };
+            },
+            usage: "dss job monitor <id...> [--summary] [--include-logs] [--log-filter stdout|stderr|user|errors] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--until all-done] [--project-key KEY]",
+            description: "Monitor one or more existing jobs and summarize progress counters from logs.",
+            examples: ["dss job monitor JOB_ID --summary", "dss job monitor JOB1 JOB2 --until all-done",],
+        },
+        watch: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss job watch <id...>");
+                const options = {
+                    includeLogs: f["include-logs"] === true,
+                    logFilter: jobLogFilterFromFlag(f["log-filter"]),
+                    maxLogLines: maxLogLinesFromFlags(f),
+                    pollIntervalMs: num(f["poll-interval"]),
+                    timeoutMs: num(f["timeout"]),
+                    summary: true,
+                    projectKey: f["project-key"],
+                };
+                const jobs = await Promise.all(a.map((jobId) => c.jobs.wait(jobId, options)));
+                return a.length === 1 ? jobs[0] : { jobs, until: f["until"] ?? "all-done", };
+            },
+            usage: "dss job watch <id...> [--include-logs] [--log-filter stdout|stderr|user|errors] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--until all-done] [--project-key KEY]",
+            description: "Watch one or more existing jobs with progress extraction enabled.",
+            examples: ["dss job watch JOB_ID", "dss job watch JOB1 JOB2 --until all-done",],
+        },
         abort: {
             handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss job abort <id>");
@@ -2260,7 +3062,7 @@ const commands = {
                 return c.scenarios.get(a[0], { projectKey: f["project-key"], });
             },
             usage: "dss scenario get <id> [--project-key KEY]",
-            description: "Get scenario definition.",
+            description: "Get raw scenario definition. For step-based scenario edits, patch params.steps; rawParams.params is DSS echo data.",
             examples: ["dss scenario get my_scenario",],
         },
         run: {
@@ -2391,21 +3193,46 @@ const commands = {
             handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin]");
                 const data = jsonInput(f);
-                if (!data) {
+                if (data === undefined) {
                     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) {
                     const current = await c.scenarios.get(a[0], { projectKey: pk, });
-                    const next = deepMerge(current, data);
-                    return { dryRun: true, action: "update", resource: "scenario", id: a[0], current, next, };
+                    const preview = scenarioUpdatePreview(current, data);
+                    return {
+                        dryRun: true,
+                        action: "update",
+                        resource: "scenario",
+                        id: a[0],
+                        canonicalEditableFields: preview.canonicalEditableFields,
+                        normalization: preview.normalization,
+                        normalizedData: preview.normalizedData,
+                        changes: preview.changes,
+                        unchangedPaths: preview.unchangedPaths,
+                        current: preview.current,
+                        next: preview.next,
+                    };
                 }
-                await c.scenarios.update(a[0], data, pk);
-                return { updated: a[0], resource: "scenario", };
+                const result = await c.scenarios.update(a[0], data, pk);
+                return {
+                    updated: a[0],
+                    resource: "scenario",
+                    verified: result.verified,
+                    changed: result.changes.length > 0,
+                    canonicalEditableFields: result.canonicalEditableFields,
+                    normalization: result.normalization,
+                    ...(result.normalization.length > 0 ? { normalizedData: result.normalizedData, } : {}),
+                    changes: result.changes,
+                    unchangedPaths: result.unchangedPaths,
+                };
             },
             usage: "dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin] [--dry-run] [--project-key KEY]",
-            description: "Update scenario settings via JSON merge.",
-            examples: ["dss scenario update my_scenario --data-file settings.json --dry-run",],
+            description: "Update scenario settings via JSON merge; edit step-based scenario steps at params.steps, not rawParams.params.steps.",
+            examples: [
+                'dss scenario update my_scenario --data \'{"params":{"steps":[]}}\' --dry-run',
+                "dss scenario update my_scenario --data-file settings.json --dry-run",
+            ],
         },
     },
     folder: {
@@ -3290,6 +4117,8 @@ function requireArgs(args, count, usage) {
 // .env auto-loading
 // ---------------------------------------------------------------------------
 function loadEnvFile() {
+    if (process.env.DATAIKU_DISABLE_ENV === "1")
+        return;
     const dirs = [
         resolve(dirname(fileURLToPath(import.meta.url)), ".."),
         process.cwd(),
@@ -3461,6 +4290,19 @@ async function probeDoctorPermission(probe) {
         return { status: permissionStatusForError(error), details: errorDetails(error), };
     }
 }
+async function probeReadOnlyPrerequisiteForMutation(probe, readAction) {
+    const readProbe = await probeDoctorPermission(probe);
+    if (readProbe.status !== "yes")
+        return readProbe;
+    return {
+        status: "unknown",
+        details: {
+            reason: "mutation capability was not verified because doctor capabilities are read-only",
+            readAction,
+            readStatus: "yes",
+        },
+    };
+}
 function missingProjectPermission() {
     return {
         status: "unknown",
@@ -3566,21 +4408,21 @@ async function doctorCapabilities(client, projectKey, accessibleProjects, flags)
             ? probeDoctorPermission(() => client.projects.get(probeProjectKey))
             : Promise.resolve(missingProjectPermission()),
         canMutateProject: () => probeProjectKey
-            ? probeDoctorPermission(() => client.variables.get(probeProjectKey))
+            ? probeReadOnlyPrerequisiteForMutation(() => client.variables.get(probeProjectKey), "variables.get")
             : Promise.resolve(missingProjectPermission()),
         canCreateFolder: () => probeProjectKey
-            ? probeDoctorPermission(() => client.folders.list(probeProjectKey))
+            ? probeReadOnlyPrerequisiteForMutation(() => client.folders.list(probeProjectKey), "folders.list")
             : Promise.resolve(missingProjectPermission()),
         canRunJobs: () => probeProjectKey
-            ? probeDoctorPermission(() => client.jobs.list(probeProjectKey))
+            ? probeReadOnlyPrerequisiteForMutation(() => client.jobs.list(probeProjectKey), "jobs.list")
             : Promise.resolve(missingProjectPermission()),
         canCreateScenario: () => probeProjectKey
-            ? probeDoctorPermission(() => client.scenarios.list(probeProjectKey))
+            ? probeReadOnlyPrerequisiteForMutation(() => client.scenarios.list(probeProjectKey), "scenarios.list")
             : Promise.resolve(missingProjectPermission()),
         canSaveJupyter: () => probeProjectKey
-            ? probeDoctorPermission(() => client.notebooks.listJupyter(probeProjectKey))
+            ? probeReadOnlyPrerequisiteForMutation(() => client.notebooks.listJupyter(probeProjectKey), "notebooks.listJupyter")
             : Promise.resolve(missingProjectPermission()),
-        canMutateConnection: () => probeDoctorPermission(() => client.connections.list()),
+        canMutateConnection: () => probeReadOnlyPrerequisiteForMutation(() => client.connections.list(), "connections.list"),
     };
     const permissions = {};
     const permissionDetails = {};
@@ -3738,6 +4580,7 @@ async function runFixtures(flags) {
     return discoverFixtureReport(client, projectKey, flags);
 }
 const READ_ACTIONS = new Set([
+    "cat",
     "contents",
     "diff",
     "download",
@@ -3758,10 +4601,14 @@ const READ_ACTIONS = new Set([
     "list-jupyter",
     "list-sql",
     "log",
+    "log-url",
     "map",
     "metadata",
     "peek",
+    "source",
+    "summary",
     "wait",
+    "watch",
     "preview",
     "query",
     "schema",
@@ -3891,7 +4738,7 @@ function inferSideEffect(resource, action) {
         return "write";
     if (READ_ACTIONS.has(action))
         return "read";
-    if (/^(create|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout)/
+    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout)/
         .test(action)) {
         return "write";
     }
@@ -3911,6 +4758,7 @@ function inferRequiresProject(resource, action, usage) {
 }
 const ARRAY_OUTPUT_ACTIONS = new Set([
     "history",
+    "find",
     "infer",
     "last-results",
     "list",
@@ -3926,7 +4774,9 @@ const STRING_OUTPUT_ACTIONS = new Set([
     "download",
     "download-code",
     "get-payload",
+    "cat",
     "log",
+    "log-url",
     "preview",
 ]);
 function inferOutputShape(resource, action) {
@@ -3967,7 +4817,7 @@ function inferExitCodes(asyncKind) {
     };
 }
 function cleanupCommandFromDeleteUsage(resource, action) {
-    if (!action.startsWith("create"))
+    if (!(action.startsWith("create") || action === "clone"))
         return undefined;
     const deleteAction = action === "create-rule" ? "delete-rule" : "delete";
     const deleteUsage = commands[resource]?.[deleteAction]?.usage;
@@ -3990,8 +4840,9 @@ function inferDestructiveLevel(sideEffect, action) {
     return "reversible";
 }
 function inferAsyncKind(resource, action) {
-    if (resource === "job" && ["build", "build-and-wait", "wait",].includes(action))
+    if (resource === "job" && ["build", "build-and-wait", "wait", "monitor", "watch",].includes(action)) {
         return "job";
+    }
     if (resource === "recipe" && action === "run")
         return "job";
     if (resource === "future" && ["get", "peek", "wait", "abort",].includes(action))
@@ -4013,7 +4864,7 @@ function inferIdempotency(sideEffect, action, usage) {
     return "none";
 }
 function inferCleanupHint(resource, action) {
-    if (!action.startsWith("create"))
+    if (!(action.startsWith("create") || action === "clone"))
         return undefined;
     if (resource === "code-env")
         return "Delete with `dss code-env delete <lang> <name> --if-exists`.";
@@ -4162,7 +5013,7 @@ function requiredPlanFlag(flags, name, usage) {
 }
 function optionalJsonFlag(flags, name) {
     const value = flags[name];
-    return typeof value === "string" ? JSON.parse(value) : undefined;
+    return typeof value === "string" ? parseJsonObject(value, `--${name}`) : undefined;
 }
 function requiredPlanJsonInput(flags, usage) {
     return requiredJsonInput(flags, `--data, --data-file, or --stdin is required. Usage: ${usage}`);
@@ -4475,8 +5326,11 @@ function commandPlanShape(resource, action, args, flags, entry, projectKey) {
             };
         case "recipe.set-payload": {
             const file = requiredPlanFlag(flags, "file", entry.usage);
-            const backupDir = flags["backup-dir"];
-            const backupPath = backupDir ? recipePayloadBackupPath(id, backupDir) : undefined;
+            const backupDir = flags["no-backup"] === true
+                ? undefined
+                : flags["backup-dir"]
+                    ?? join(process.cwd(), ".dss-backups", "recipes");
+            const backupPath = backupDir ? recipeBackupPath(id, backupDir) : undefined;
             return {
                 method: "PUT",
                 endpoint: projectEndpoint(`/recipes/${encodeURIComponent(id)}`),
@@ -4487,7 +5341,7 @@ function commandPlanShape(resource, action, args, flags, entry, projectKey) {
                     ...(backupPath ? { backupPath, } : {}),
                 },
                 ...(backupPath
-                    ? { localWrites: [{ path: backupPath, source: "remote recipe payload", before: "PUT", },], }
+                    ? { localWrites: [{ path: backupPath, source: "remote recipe backup", before: "PUT", },], }
                     : {}),
             };
         }
@@ -4834,17 +5688,26 @@ function promptSecret(label) {
 // Credential resolution
 // ---------------------------------------------------------------------------
 function resolveCredentials(flags) {
-    let url = flags["url"];
-    let apiKey = flags["api-key"];
-    let projectKey = flags["project-key"];
+    const hasUrlFlag = Object.hasOwn(flags, "url");
+    const hasApiKeyFlag = Object.hasOwn(flags, "api-key");
+    const hasProjectKeyFlag = Object.hasOwn(flags, "project-key");
+    let url = hasUrlFlag ? flags["url"] : undefined;
+    let apiKey = hasApiKeyFlag ? flags["api-key"] : undefined;
+    let projectKey = hasProjectKeyFlag ? flags["project-key"] : undefined;
     const saved = loadCredentials();
-    url ??= process.env.DATAIKU_URL;
-    apiKey ??= process.env.DATAIKU_API_KEY;
-    projectKey ??= process.env.DATAIKU_PROJECT_KEY;
+    if (!hasUrlFlag)
+        url ??= process.env.DATAIKU_URL;
+    if (!hasApiKeyFlag)
+        apiKey ??= process.env.DATAIKU_API_KEY;
+    if (!hasProjectKeyFlag)
+        projectKey ??= process.env.DATAIKU_PROJECT_KEY;
     if (saved) {
-        url ||= saved.url;
-        apiKey ||= saved.apiKey;
-        projectKey ??= saved.projectKey;
+        if (!hasUrlFlag)
+            url ??= saved.url;
+        if (!hasApiKeyFlag)
+            apiKey ??= saved.apiKey;
+        if (!hasProjectKeyFlag)
+            projectKey ??= saved.projectKey;
     }
     return {
         url: url ?? "",
@@ -4979,7 +5842,7 @@ async function main() {
     const { positional, flags, } = parseArgs(process.argv.slice(2));
     // --version
     if (flags["version"] === true) {
-        process.stdout.write(`${CLI_VERSION}\n`);
+        process.stdout.write(`${CLI_VERSION_LABEL}\n`);
         process.exit(0);
     }
     // Top-level help
@@ -5317,7 +6180,12 @@ async function main() {
         if (entry)
             await appendCleanupLedgerEntry(flags["record-cleanup"], entry);
     }
-    writeCommandResult(result);
+    if (flags["raw"] === true && typeof result === "string") {
+        process.stdout.write(result);
+    }
+    else {
+        writeCommandResult(result);
+    }
     const failureExitCode = commandFailureExitCode(result);
     if (failureExitCode !== undefined)
         process.exit(failureExitCode);