dataiku-sdk 3.9.0 → 4.1.0

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

@@ -1,9 +1,10 @@
-import { mkdir, writeFile, } from "node:fs/promises";
-import { dirname, resolve, } from "node:path";
-import { ClientValidationError, DataikuError, } from "../../errors.js";
+import { resolve, } from "node:path";
+import { ClientValidationError, DataikuError, dataikuErrorCode, RESPONSE_TOO_LARGE_STATUS_TEXT, } from "../../errors.js";
 import { asRecord, } from "../../utils/records.js";
 import { jobBuildTargetTypeFromFlags, jobLogFilterFromFlag, maxLogLinesFromFlags, num, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
+import { compactValue, } from "../list-output.js";
+import { COMPACT_LIST_FIELDS, } from "../list-shapes.js";
 import { encodedProjectEndpoint, enqueueCliWarning, } from "../output.js";
 import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
@@ -33,6 +34,27 @@ function tailJobLogForStdout(log, limit) {
     const tail = lines.slice(-shown).join("\n");
     return hasTrailingLineBreak ? `${tail}\n` : tail;
 }
+/** POSIX-shell quoting for the display form of a resume command. */
+function shellArg(value) {
+    return /^[\w.:@%+=,/-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+/**
+ * A wait that timed out only stopped polling: the job is still running in DSS.
+ * Attach the command that resumes waiting: `resumeArgv` (run it without a
+ * shell, on any OS) and `resume` (POSIX display form); other results pass through.
+ */
+function withWaitResume(result, projectKey) {
+    if (result.timedOut !== true)
+        return result;
+    const resumeArgv = [
+        "dss",
+        "job",
+        "wait",
+        result.jobId,
+        ...(projectKey ? ["--project-key", projectKey,] : []),
+    ];
+    return { ...result, resume: resumeArgv.map(shellArg).join(" "), resumeArgv, };
+}
 /**
  * With an empty output schema DSS ends a dataset build DONE after writing no
  * columns and no rows, without an error. Flag that after a successful build so
@@ -120,8 +142,9 @@ function jobSummaryType(job) {
         ?? "unknown";
 }
 function jobSummaryState(job) {
+    const listState = compactValue(job, COMPACT_LIST_FIELDS["job"]["state"]);
     return stringPath(job, ["baseStatus", "state",])
-        ?? stringPath(job, ["state",])
+        ?? (typeof listState === "string" ? listState : undefined)
         ?? "unknown";
 }
 function filteredJobList(jobs, flags) {
@@ -202,7 +225,19 @@ function jobDurationMs(details) {
 }
 async function jobInspectionSummary(client, jobId, flags) {
     const projectKey = flags["project-key"];
-    const details = await client.jobs.get(jobId, projectKey);
+    // A job-detail body over the buffered response cap must not sink the whole
+    // summary: keep the log part and report the details failure structurally.
+    let details = {};
+    let detailsError;
+    try {
+        details = await client.jobs.get(jobId, projectKey);
+    }
+    catch (error) {
+        if (!(error instanceof DataikuError && error.statusText === RESPONSE_TOO_LARGE_STATUS_TEXT)) {
+            throw error;
+        }
+        detailsError = { code: dataikuErrorCode(error.category), message: error.message, };
+    }
     let log;
     let logError;
     try {
@@ -233,6 +268,7 @@ async function jobInspectionSummary(client, jobId, flags) {
         jobId: jobSummaryId(details, jobId),
         state: jobSummaryState(details),
         type: jobSummaryType(details),
+        ...(detailsError ? { detailsError, } : {}),
         ...(durationMs !== undefined ? { durationMs, } : {}),
         ...(outputs !== undefined ? { outputs, } : {}),
         warnings: jobWarningSummary(details, log),
@@ -253,7 +289,7 @@ async function jobInspectionSummary(client, jobId, flags) {
 export const jobCommands = withUsage("job", {
     list: {
         handler: async (c, _a, f) => filteredJobList(await c.jobs.list(f["project-key"]), f),
-        description: "List recent jobs, optionally filtered for automation.",
+        description: "List recent jobs, optionally filtered for automation. In-progress jobs, which DSS lists without a state, show RUNNING; `job get` has the exact phase.",
         examples: ["dss job list --state DONE --latest", "dss job list --contains WLM225S --limit 10",],
     },
     get: {
@@ -282,18 +318,34 @@ export const jobCommands = withUsage("job", {
                 ?? f["output-file"];
             const requestedLines = maxLogLinesFromFlags(f);
             // Stdout is tailed here (not in the SDK) so the total can be reported.
-            const log = await c.jobs.log(a[0], {
+            const details = await c.jobs.logDetails(a[0], {
                 activity: f["activity"],
                 logId: f["log-id"],
                 logFilter,
                 maxLogLines: outputFile ? requestedLines : -1,
                 projectKey: f["project-key"],
             });
+            const log = details.text;
+            if (details.truncated) {
+                enqueueCliWarning({
+                    code: "log_truncated",
+                    reason: "byte_cap",
+                    earlyLinesDropped: true,
+                    maxLogBytes: details.maxLogBytes,
+                    hint: "Only the most recent part of the log was retrieved; early lines (and any earlier errors) were dropped. Use `dss job get` for job-level and per-activity errors.",
+                });
+            }
+            if (logFilter === "errors" && log.length === 0) {
+                enqueueCliWarning({
+                    code: "no_error_lines",
+                    scannedLines: details.scannedLines,
+                    hint: `No error lines matched in ${details.scannedLines} scanned log lines. Run \`dss job get ${a[0]}\` for the job-level and per-activity errors, or \`dss job log ${a[0]}\` without --errors-only for the full log.`,
+                });
+            }
             if (!outputFile)
                 return tailJobLogForStdout(log, requestedLines ?? DEFAULT_STDOUT_LOG_LINES);
             const outputPath = resolve(outputFile);
-            await mkdir(dirname(outputPath), { recursive: true, });
-            await writeFile(outputPath, log.endsWith("\n") ? log : `${log}\n`, "utf-8");
+            await Bun.write(outputPath, log.endsWith("\n") ? log : `${log}\n`);
             return outputPath;
         },
         description: "Get public API job log output (last 100 lines by default; --max-lines N, 0 = all); find why a job failed. Use --errors-only for error/traceback lines and --output PATH to write it to a file (stdout returns the path). --log-id is accepted for UI parity; API keys cannot read browser-only cat-activity-log files.",
@@ -349,7 +401,7 @@ export const jobCommands = withUsage("job", {
                 };
             }
             if (f["wait"] === true) {
-                const result = await c.jobs.buildAndWait(a[0], { ...options, projectKey: pk, });
+                const result = withWaitResume(await c.jobs.buildAndWait(a[0], { ...options, projectKey: pk, }), pk);
                 await warnIfBuiltDatasetHasNoColumns(c, a[0], options.targetType, result.success, pk);
                 return result;
             }
@@ -389,7 +441,7 @@ export const jobCommands = withUsage("job", {
                     method: "POST",
                 };
             }
-            const result = await c.jobs.buildAndWait(a[0], { ...options, projectKey: pk, });
+            const result = withWaitResume(await c.jobs.buildAndWait(a[0], { ...options, projectKey: pk, }), pk);
             await warnIfBuiltDatasetHasNoColumns(c, a[0], options.targetType, result.success, pk);
             return result;
         },
@@ -402,17 +454,19 @@ export const jobCommands = withUsage("job", {
         ],
     },
     wait: {
-        handler: (c, a, f) => {
+        handler: async (c, a, f) => {
             requireArgs(a, 1, commandUsage("job", "wait"));
-            return c.jobs.wait(a[0], {
+            const projectKey = f["project-key"];
+            const result = await c.jobs.wait(a[0], {
                 includeLogs: f["include-logs"] === true,
                 logFilter: jobLogFilterFromFlag(f["log-filter"]),
                 maxLogLines: maxLogLinesFromFlags(f),
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
                 timeoutMs: num(f["timeout"], "--timeout"),
                 summary: f["summary"] === true,
-                projectKey: f["project-key"],
+                projectKey,
             });
+            return withWaitResume(result, projectKey);
         },
         description: "Wait for an existing job to complete.",
         examples: [
@@ -432,7 +486,7 @@ export const jobCommands = withUsage("job", {
                 summary: f["summary"] !== false,
                 projectKey: f["project-key"],
             };
-            const jobs = await Promise.all(a.map((jobId) => c.jobs.wait(jobId, options)));
+            const jobs = await Promise.all(a.map(async (jobId) => withWaitResume(await c.jobs.wait(jobId, options), options.projectKey)));
             return aggregateJobWaitResults(jobs, String(f["until"] ?? "all-done"));
         },
         description: "Monitor one or more existing jobs and summarize progress counters from logs.",
@@ -450,7 +504,7 @@ export const jobCommands = withUsage("job", {
                 summary: true,
                 projectKey: f["project-key"],
             };
-            const jobs = await Promise.all(a.map((jobId) => c.jobs.wait(jobId, options)));
+            const jobs = await Promise.all(a.map(async (jobId) => withWaitResume(await c.jobs.wait(jobId, options), options.projectKey)));
             return aggregateJobWaitResults(jobs, String(f["until"] ?? "all-done"));
         },
         description: "Watch one or more existing jobs with progress extraction enabled.",

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

@@ -1,7 +1,7 @@
-import * as fs from "node:fs";
+import { readFile, } from "node:fs/promises";
 import { validatedPluginGitUrl, validatePluginDestinationPath, validatePluginId, validatePluginName, validatePluginPath, } from "../../resources/plugins.js";
 import { writeResponseToFile, } from "../../utils/response-file.js";
-import { num, readStdinText, sha256Hex, } from "../coerce.js";
+import { num, readStdinText, readTextFile, sha256Hex, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { planResult, } from "../output.js";
 import { commandUsage, withUsage, } from "../syntax.js";
@@ -281,7 +281,7 @@ export const pluginCommands = withUsage("plugin", {
             requireArgs(a, 1, SETTINGS_SET_USAGE);
             const pluginId = validatePluginId(a[0]);
             const mode = executionMode(f);
-            const settings = readSettingsInput(f);
+            const settings = await readSettingsInput(f);
             if (mode.dryRun) {
                 return pluginPlan("settings-set", {
                     method: "POST",
@@ -330,7 +330,7 @@ export const pluginCommands = withUsage("plugin", {
         },
         description: "Create the code env of a plugin. Returns the DSS future (jobId); --wait polls it to completion.",
         examples: [
-            "dss plugin code-env-create my-plugin --python-interpreter PYTHON36",
+            "dss plugin code-env-create my-plugin --python-interpreter PYTHON311",
             "dss plugin code-env-create my-plugin --conda --wait --timeout 300000",
         ],
     },
@@ -629,7 +629,7 @@ export const pluginCommands = withUsage("plugin", {
                 });
             }
             const content = typeof f["file"] === "string"
-                ? fs.readFileSync(f["file"])
+                ? await readFile(f["file"])
                 : typeof f["content"] === "string"
                     ? f["content"]
                     : await readStdinText();
@@ -738,10 +738,10 @@ function normalizeCreationMode(value) {
     }
     throw new UsageError("--creation-mode must be one of EMPTY, GIT_CLONE, GIT_EXPORT.", "invalid_enum");
 }
-function readSettingsInput(flags) {
+async function readSettingsInput(flags) {
     let text;
     if (typeof flags["file"] === "string") {
-        text = fs.readFileSync(flags["file"], "utf-8");
+        text = await readTextFile(flags["file"]);
     }
     else if (typeof flags["content"] === "string") {
         text = flags["content"];

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

@@ -159,7 +159,7 @@ export const projectLibraryCommands = withUsage("project-library", {
             const content = typeof f["content"] === "string"
                 ? f["content"]
                 : typeof f["file"] === "string"
-                    ? fs.readFileSync(f["file"])
+                    ? await fs.promises.readFile(f["file"])
                     : await readStdinText();
             const result = await c.projectLibrary.addOrUpdateFile(a[0], content, pk, expectSha256 !== undefined ? { expectSha256, } : undefined);
             return {
@@ -184,7 +184,7 @@ export const projectLibraryCommands = withUsage("project-library", {
             const local = typeof f["content"] === "string"
                 ? f["content"]
                 : typeof f["file"] === "string"
-                    ? fs.readFileSync(f["file"])
+                    ? await fs.promises.readFile(f["file"])
                     : await readStdinText();
             return c.projectLibrary.diffFile(a[0], local, pk, maxLines !== undefined ? { maxLines, } : {});
         },

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

@@ -4,11 +4,13 @@ import { inspectProjectArchive, } from "../../utils/project-archive.js";
 import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
 import { jsonInput, num, requiredJsonInput, requiredStringFlag, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
-import { CommandResultFailure, } from "../output.js";
+import { CommandResultFailure, enqueueCliWarning, } from "../output.js";
 import { compactProjectMapOutput, } from "../project-map-output.js";
 import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 const INSPECT_ARCHIVE_USAGE = commandUsage("project", "inspect-archive");
+/** Maximum credential inventory entries echoed in the export warning. */
+const EXPORT_CREDENTIAL_INVENTORY_LIMIT = 100;
 function flowRenderFormat(value) {
     if (value === undefined)
         return undefined;
@@ -162,9 +164,24 @@ export const projectCommands = withUsage("project", {
             if (!out)
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
             await c.projects.exportArchive(a[0], out, jsonInput(f));
-            return { path: out, };
+            const inspection = await inspectProjectArchive(out);
+            const findings = inspection.credentialFindings;
+            if (findings.length > 0) {
+                enqueueCliWarning({
+                    code: "export_contains_credentials",
+                    message: `The exported archive '${out}' contains ${findings.length} credential-bearing structure(s) `
+                        + "(member paths and key names only; values are never printed). "
+                        + "DSS exports credentials, API keys and secret-named variables verbatim.",
+                    hint: "Sanitize the archive before sharing or uploading it. Overwriting an object in versioned storage does not erase its retained versions: "
+                        + "once an unsanitized archive is uploaded, rotate the exposed credentials.",
+                    total: findings.length,
+                    shown: Math.min(findings.length, EXPORT_CREDENTIAL_INVENTORY_LIMIT),
+                    findings: findings.slice(0, EXPORT_CREDENTIAL_INVENTORY_LIMIT),
+                });
+            }
+            return { path: out, credentialFindings: findings.length, };
         },
-        description: "Export a project to a local archive (.zip).",
+        description: "Export a project to a local archive (.zip). The written archive is inspected locally; credential-bearing structures (apikeys.json, secret-named variables, apiKey/token/password fields) raise an export_contains_credentials warning listing member paths and key names only, and the result reports credentialFindings. The archive is not redacted.",
         examples: ["dss project export MY_PROJ --output ./my_proj.zip",],
     },
     import: {
@@ -202,7 +219,7 @@ export const projectCommands = withUsage("project", {
     "inspect-archive": {
         handler: async (_c, a) => inspectArchiveCommand(a),
         localHandler: inspectArchiveCommand,
-        description: "Read-only local inspection of a project export archive: member names, sizes, manifest validity, archive issues, and the source project key. Never contacts DSS.",
+        description: "Read-only local inspection of a project export archive: member names, sizes, manifest validity, archive issues (including credential_structure and residue_scan_skipped warnings), a credentialFindings inventory of credential-bearing member paths and key names (values are never reported), and the source project key. Never contacts DSS.",
         examples: ["dss project inspect-archive ./my_proj.zip",],
     },
     "permissions-set": {

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

@@ -1,10 +1,8 @@
-import { readFileSync, } from "node:fs";
-import { writeFile, } from "node:fs/promises";
 import { join, } from "node:path";
 import { ClientValidationError, DataikuError, } from "../../errors.js";
 import { recipeCreateWarnings, recipeOutputSchemaIsComputable, schemaUpdateComputableId, schemaUpdateIsPending, } from "../../resources/recipe-create.js";
-import { deepMerge, } from "../../utils/deep-merge.js";
-import { jobLogFilterFromFlag, jsonInput, maxLogLinesFromFlags, normalizeLineEndings, num, recipeInputDatasetsFromFlags, requiredJsonInput, requiredStringFlag, rewritePairsFromFlags, sha256Hex, splitCsvFlag, stableHash, } from "../coerce.js";
+import { buildRecipeUpdate, } from "../../resources/recipes.js";
+import { jobLogFilterFromFlag, jsonInput, maxLogLinesFromFlags, normalizeLineEndings, num, readTextFile, recipeInputDatasetsFromFlags, requiredJsonInput, requiredStringFlag, rewritePairsFromFlags, sha256Hex, splitCsvFlag, stableHash, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { moveCreatedItemsToZone, resolveFlowZoneIdFromFlags, } from "../helpers/flow-zone.js";
 import { ensureRecipeBackupDir, readRecipeBackup, recipeBackupDocument, recipeBackupPath, recipeCodeEnv, recipeGraph, recipeInputItemRef, recipeRoleInputItems, recipeRunShouldWait, writeRecipeBackup, } from "../helpers/recipe.js";
@@ -12,9 +10,9 @@ import { encodedProjectEndpoint, enqueueCliWarning, readIfExists, skipResult, }
 import { commandUsage, withUsage, } from "../syntax.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) {
+async function readRecipeFile(filePath, flagName) {
     try {
-        return readFileSync(filePath, "utf-8");
+        return await readTextFile(filePath);
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
@@ -414,9 +412,30 @@ export const recipeCommands = withUsage("recipe", {
                     hint: `Fix the recipe settings, then run dss recipe update-schema ${createdName}.`,
                 });
             }
-            return { created: createdName, resource: "recipe", ...created, ...moved, };
+            // A visual recipe whose payload came from flags is ready to run: point at the build
+            // (recursive, so outputs of recipes created just before are built too).
+            const output = f["output"];
+            const next = typeof output === "string" && (created.payloadConfigured || created.joinConfigured)
+                ? [[
+                        "dss",
+                        "job",
+                        "build-and-wait",
+                        output,
+                        "--build-mode",
+                        "RECURSIVE_BUILD",
+                        "--summary",
+                        ...(pk ? ["--project-key", pk,] : []),
+                    ],]
+                : undefined;
+            return {
+                created: createdName,
+                resource: "recipe",
+                ...created,
+                ...moved,
+                ...(next ? { next, } : {}),
+            };
         },
-        description: "Create a recipe with optional inputs and a dataset or managed-folder output. Missing outputs are created on --output-connection as DSS managed datasets. Join, grouping (--group-by/--aggregate) and prepare (--rename/--formula/--filter/...) payloads come from flags. Visual recipe outputs get the DSS-computed schema (outputSchemaUpdated).",
+        description: "Create a recipe; missing outputs become managed datasets on --output-connection. Join, grouping (--group-by/--aggregate: keys plus those aggregates, no implicit count) and prepare (--rename/--formula/--filter/...) payloads come from flags, then `next` is the build. Visual outputs get the DSS-computed schema.",
         examples: [
             "dss recipe create --type python --input raw_orders,lookup --output orders_clean",
             "dss recipe create --type grouping --input orders --output orders_by_cat --group-by category --aggregate amount:sum+avg,name:first --order-by day",
@@ -507,7 +526,7 @@ export const recipeCommands = withUsage("recipe", {
                 throw new UsageError(`--file is required. Usage: ${commandUsage("recipe", "diff")}`);
             }
             // Read and validate the local file before any DSS request.
-            const localContent = readRecipeFile(filePath, "--file");
+            const localContent = await readRecipeFile(filePath, "--file");
             const result = await c.recipes.get(a[0], {
                 includePayload: true,
                 projectKey: f["project-key"],
@@ -530,23 +549,17 @@ export const recipeCommands = withUsage("recipe", {
             const pk = f["project-key"];
             if (executionMode(f).dryRun) {
                 const current = await c.recipes.get(a[0], { projectKey: pk, includePayload: true, });
-                const currentRecipe = current.recipe;
-                const next = {
-                    ...current,
-                    ...data,
-                    recipe: deepMerge(currentRecipe, (data.recipe && typeof data.recipe === "object" && !Array.isArray(data.recipe))
-                        ? data.recipe
-                        : {}),
-                };
+                const next = buildRecipeUpdate(current, data);
                 return { dryRun: true, action: "update", resource: "recipe", name: a[0], current, next, };
             }
             await c.recipes.update(a[0], data, pk);
             return { updated: a[0], resource: "recipe", };
         },
-        description: "Update recipe settings via JSON merge. Recipe definition fields must be nested under a top-level recipe key.",
+        description: "Update recipe settings via JSON merge. Recipe definition fields must be nested under a top-level recipe key. recipe.params.envSelection, when present, replaces the existing envSelection object (include envMode; no stale envName is kept) and is only accepted under recipe.params.",
         examples: [
             "dss recipe update compute_orders --data-file settings.json --dry-run",
-            'dss recipe update compute_orders --data \'{"recipe":{"params":{"envSelection":{"envMode":"EXPLICIT_ENV","envName":"python39"}}}}\'',
+            'dss recipe update compute_orders --data \'{"recipe":{"params":{"envSelection":{"envMode":"EXPLICIT_ENV","envName":"py311_env"}}}}\'',
+            'dss recipe update compute_orders --data \'{"recipe":{"params":{"envSelection":{"envMode":"INHERIT"}}}}\'',
             "cat settings.json | dss recipe update compute_orders --stdin",
         ],
     },
@@ -636,7 +649,7 @@ export const recipeCommands = withUsage("recipe", {
                 projectKey: f["project-key"],
             });
             if (typeof f["output"] === "string") {
-                await writeFile(f["output"], payload, "utf-8");
+                await Bun.write(f["output"], payload);
                 return f["output"];
             }
             return payload;
@@ -663,7 +676,7 @@ export const recipeCommands = withUsage("recipe", {
             const filePath = f["file"];
             if (!filePath)
                 throw new UsageError("--file is required.");
-            const content = readRecipeFile(filePath, "--file");
+            const content = await readRecipeFile(filePath, "--file");
             const pk = f["project-key"];
             const shouldBackup = f["no-backup"] !== true;
             const backupDir = shouldBackup

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

@@ -1,8 +1,69 @@
+import { asRecord, } from "../../utils/records.js";
 import { jsonInput, num, parseBooleanOption, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
+import { scenarioRunDiagnosis, shapeCommandResult, } from "../result-shapes.js";
 import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
+/**
+ * The recipe a failed job was running and the datasets it read, from one
+ * `job get` (its FAILED activity). Undefined when the job cannot be read or
+ * names no failed recipe: the diagnosis then stays job-level.
+ */
+async function failedActivity(c, jobId, projectKey) {
+    if (typeof jobId !== "string")
+        return undefined;
+    try {
+        const job = asRecord(await c.jobs.get(jobId, projectKey));
+        const activities = asRecord(asRecord(job?.["baseStatus"])?.["activities"]) ?? {};
+        for (const value of Object.values(activities)) {
+            const activity = asRecord(value);
+            if (activity?.["state"] !== "FAILED" || typeof activity["recipeName"] !== "string")
+                continue;
+            const sources = Array.isArray(activity["sources"]) ? activity["sources"] : [];
+            const inputs = sources.flatMap((source) => {
+                const id = asRecord(source)?.["id"];
+                if (typeof id !== "string")
+                    return [];
+                // Same-project inputs are named bare; foreign ones keep PROJECT.name.
+                const dot = id.indexOf(".");
+                return [dot > 0 && id.slice(0, dot) === projectKey ? id.slice(dot + 1) : id,];
+            });
+            return { recipe: activity["recipeName"], inputs, };
+        }
+    }
+    catch {
+        // A diagnosis aid only: the run report itself is already in hand.
+    }
+    return undefined;
+}
+/** Diagnosis of a raw run report, located at the failed recipe when its job names one. */
+async function locatedDiagnosis(c, details, projectKey) {
+    const plain = scenarioRunDiagnosis(details);
+    const runProject = asRecord(asRecord(asRecord(details)?.["scenarioRun"])?.["trigger"])?.["projectKey"];
+    const pk = projectKey ?? (typeof runProject === "string" ? runProject : undefined);
+    const activity = await failedActivity(c, plain.failure?.["jobId"], pk);
+    return activity ? scenarioRunDiagnosis(details, activity) : plain;
+}
+/**
+ * Run a scenario and wait; a failed (not timed-out) run gains the first
+ * failure, the recipe that failed, and the next commands. Extra reads happen
+ * only on failure; a read error leaves the wait result untouched.
+ */
+async function runAndWaitWithFailure(c, scenarioId, options) {
+    const result = await c.scenarios.runAndWait(scenarioId, options);
+    if (result.success || result.timedOut === true || !result.runId)
+        return result;
+    try {
+        const details = await c.scenarios.getRunDetails(scenarioId, result.runId, {
+            projectKey: options.projectKey,
+        });
+        return { ...result, ...await locatedDiagnosis(c, details, options.projectKey), };
+    }
+    catch {
+        return result;
+    }
+}
 export const scenarioCommands = withUsage("scenario", {
     list: {
         handler: (c, _a, f) => c.scenarios.list(f["project-key"]),
@@ -37,7 +98,7 @@ export const scenarioCommands = withUsage("scenario", {
                 };
             }
             if (f["wait"] === true) {
-                return c.scenarios.runAndWait(a[0], { ...options, projectKey: pk, });
+                return runAndWaitWithFailure(c, a[0], { ...options, projectKey: pk, });
             }
             return c.scenarios.run(a[0], pk);
         },
@@ -63,7 +124,7 @@ export const scenarioCommands = withUsage("scenario", {
                     method: "POST",
                 };
             }
-            return c.scenarios.runAndWait(a[0], { ...options, projectKey: pk, });
+            return runAndWaitWithFailure(c, a[0], { ...options, projectKey: pk, });
         },
         description: "Run a scenario and wait for completion.",
         examples: [
@@ -209,17 +270,24 @@ export const scenarioCommands = withUsage("scenario", {
                 projectKey: f["project-key"],
             });
         },
-        description: "List the most recent runs of a scenario (run id, start/end, outcome).",
+        description: "List the most recent runs of a scenario (compact by default: run id, outcome, start/end, trigger, failure message; --full returns the DSS run objects).",
         examples: ["dss scenario last-runs my_scenario --limit 10",],
     },
     "get-run": {
-        handler: (c, a, f) => {
+        handler: async (c, a, f) => {
             requireArgs(a, 2, commandUsage("scenario", "get-run"));
-            return c.scenarios.getRunDetails(a[0], a[1], {
-                projectKey: f["project-key"],
-            });
+            const projectKey = f["project-key"];
+            const details = await c.scenarios.getRunDetails(a[0], a[1], { projectKey, });
+            if (f["full"] === true || typeof f["fields"] === "string")
+                return details;
+            // Compact view, located at the failed recipe (one extra job read, only on failure).
+            // The shaped object has no `scenarioRun`, so the dispatcher's shaping passes it through.
+            const shaped = asRecord(shapeCommandResult("scenario", "get-run", details, f));
+            if (!shaped?.["failure"])
+                return shaped ?? details;
+            return { ...shaped, ...await locatedDiagnosis(c, details, projectKey), };
         },
-        description: "Get the details of a specific scenario run, including per-step outcomes.",
+        description: "Get a scenario run: outcome, timing, trigger, per-step datasets and jobs, plus `failure` {stepId, jobId, dataset, recipe, inputs, message} and `next` argv (recipe code, input schemas, job errors) for the first failure (compact by default; --full returns the raw DSS run report).",
         examples: ["dss scenario get-run my_scenario 2024-09-01-01-02-03-123",],
     },
     log: {
@@ -233,11 +301,9 @@ export const scenarioCommands = withUsage("scenario", {
             const outputFile = f["output"]
                 ?? f["output-file"];
             if (outputFile) {
-                const { mkdir, writeFile, } = await import("node:fs/promises");
-                const { dirname, resolve, } = await import("node:path");
+                const { resolve, } = await import("node:path");
                 const outputPath = resolve(outputFile);
-                await mkdir(dirname(outputPath), { recursive: true, });
-                await writeFile(outputPath, result.text, "utf-8");
+                await Bun.write(outputPath, result.text);
                 return { path: outputPath, truncated: result.truncated, };
             }
             return result.text;

package/dist/src/cli/contract.js

@@ -248,6 +248,13 @@ const ALLOWED_CLEANUP_ACTIONS = new Set([
     "project-library delete",
     "streaming-endpoint delete",
     "workspace delete",
+    "saved-model delete",
+    "project-folder delete",
+    "data-collection delete",
+    "plugin delete",
+    "connection delete",
+    "user delete",
+    "group delete",
 ]);
 export function isAllowedCleanupAction(resource, action) {
     return ALLOWED_CLEANUP_ACTIONS.has(`${resource} ${action}`);
@@ -391,7 +398,7 @@ function structuredExamples(examples, examplePayload) {
  * (`dss commands run`, `dss agent contract`) never loads the TypeBox graph.
  * The content matches `typeBoxCommandOutputSchemas()` exactly; parity and
  * freshness are enforced by tests/cli/discovery-output-schemas.test.ts and
- * `bun run check`.
+ * `bun run verify`.
  */
 const actionOutputSchemas = actionOutputSchemasMetadata
     .schemas;
@@ -764,6 +771,21 @@ const STRING_OUTPUT_ACTIONS = new Set([
     "log",
     "log-url",
 ]);
+/**
+ * `resource.action` shapes that differ from the bare-action-name sets above:
+ * `contents`/`usages`/`project-timeline` are array-named elsewhere, and
+ * `download`/`diff` are string-named elsewhere, but these handlers return the
+ * opposite shape. Pinned by tests/cli/output-shapes.test.ts.
+ */
+const SCOPED_OUTPUT_SHAPES = {
+    "folder.contents": "array",
+    "scenario.last-runs": "array",
+    "plugin.usages": "object",
+    "plugin.download": "object",
+    "dataset.download": "object",
+    "project-library.get": "string",
+    "project-library.diff": "object",
+};
 function inferOutputShape(resource, action) {
     if (resource === "project-git") {
         if (action === "branches" || action === "tags" || action === "list-libraries")
@@ -777,14 +799,15 @@ function inferOutputShape(resource, action) {
         || resource === "version") {
         return "object";
     }
+    // Resource-scoped rules come first: the bare-name sets below classify by
+    // action alone and would otherwise misfile same-named actions elsewhere.
+    const scoped = SCOPED_OUTPUT_SHAPES[`${resource}.${action}`];
+    if (scoped !== undefined)
+        return scoped;
     if (/^list(-|$)/.test(action))
         return "array";
     if (ARRAY_OUTPUT_ACTIONS.has(action))
         return "array";
-    if (resource === "dataset" && action === "download")
-        return "object";
-    if (resource === "project-library" && action === "get")
-        return "string";
     if (STRING_OUTPUT_ACTIONS.has(action))
         return "string";
     return "object";
@@ -1496,7 +1519,7 @@ export function buildAgentContract() {
                     "dss commands run --fields dataset",
                     "dss commands run --fields dataset.create",
                 ],
-                scopedDiscoveryHint: "Default: resource/action summary. --contains TEXT: top 5 actions by concept. --fields RESOURCE: all resource entries; RESOURCE.ACTION: one entry keyed by that path; append .FIELD for nested metadata. Comma-separate paths. --output PATH exports the full registry.",
+                scopedDiscoveryHint: "Default: resource/action summary. --contains TEXT: top 5 actions by concept. --fields RESOURCE: each action's usage, description, and side effect; RESOURCE.ACTION: one full entry keyed by that path; append .FIELD for nested metadata. Comma-separate paths. --output PATH exports full entries (the full registry without --fields).",
                 // Accepted by every command and absent from per-entry `flags`; the
                 // connection flags matter only for commands that call DSS.
                 globalFlags: [...GLOBAL_AGENT_FLAGS, ...AUTHENTICATED_AGENT_FLAGS,].map((name) => {
@@ -1523,7 +1546,7 @@ export function buildAgentContract() {
                 failure: "structured-error-object",
                 failureResultDetailLimitBytes: 65_536,
                 fieldProjection: "Missing --fields paths: null on stdout; field_projection_missing on stderr.",
-                compactResults: "*.list, job get, dataset get/info, project get: compact; --full/--fields use DSS objects; lists take --contains/--limit (list_truncated warning).",
+                compactResults: "*.list, job get, dataset get/info, project get, scenario get-run/last-runs: compact; --full/--fields use DSS objects; lists take --contains/--limit (list_truncated warning).",
                 richFailureResults: "doctor/batch/cleanup failures: own compact {ok:false,...} result on stdout and command exit code; no wrapper.",
             },
             stderr: {

package/dist/src/cli/env.d.ts

@@ -10,4 +10,10 @@ export declare function envFileProvenance(name: string): EnvFileProvenance | und
 export declare function dataikuEnvironmentEnabled(): boolean;
 /** DATAIKU_PROJECT_KEY from the environment, unless `DATAIKU_DISABLE_ENV=1`. */
 export declare function ambientProjectKey(): string | undefined;
+/**
+ * `DSS_PRETTY=1` indents stdout JSON. Agent shells that cut long lines (omp at
+ * 768 bytes) truncate a one-line result; indented output keeps each line short.
+ * Read from the process environment only, never from a `.env` file.
+ */
+export declare function prettyOutputEnabled(): boolean;
 export declare function loadEnvFile(): void;