dataiku-sdk 3.0.0 → 3.2.0

package/dist/src/cli/commands/code-env.js

@@ -1,7 +1,34 @@
-import { readFileSync, } from "node:fs";
-import { json, jsonInput, parseBooleanOption, } from "../coerce.js";
-import { isNotFoundError, readIfExists, skipResult, } from "../output.js";
+import { readFileSync, writeFileSync, } from "node:fs";
+import { ClientValidationError, } from "../../errors.js";
+import { stableHash, } from "../../utils/stable-hash.js";
+import { json, jsonInput, num, numFlag, parseBooleanOption, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
+import { enqueueCliWarning, isNotFoundError, readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
+const CODE_ENV_LANGS = ["PYTHON", "R",];
+/** Validate a positional `<lang>` argument: required, must be PYTHON or R. */
+function requireEnvLang(value, usage) {
+    if (value !== "PYTHON" && value !== "R") {
+        throw new UsageError(`env language must be one of ${CODE_ENV_LANGS.join(", ")}. Usage: ${usage}`, "invalid_enum", undefined, { value, allowed: CODE_ENV_LANGS, });
+    }
+    return value;
+}
+function definitionHashMismatch(envLang, envName, expected, current) {
+    return new ClientValidationError(`Code env ${envLang}/${envName} changed since the expected definition hash was captured; refusing to overwrite it.`, "validation_failed", "Re-read the definition with dss code-env get-definition (definitionHash comes from code-env get), review the diff, and retry with the fresh hash.", {
+        envLang,
+        envName,
+        expectedDefinitionHash: expected,
+        ...(current !== undefined ? { currentDefinitionHash: current, } : {}),
+    });
+}
+function validateExpectHash(value) {
+    if (value === undefined || value === false)
+        return undefined;
+    if (typeof value !== "string" || !/^[0-9a-fA-F]{64}$/.test(value)) {
+        throw new ClientValidationError("Expected code env definition hash must be a 64-character SHA-256 hex digest.", "validation_failed", "Use the definitionHash value returned by dss code-env get.");
+    }
+    return value;
+}
 function codeEnvWait(flags) {
     return flags["no-wait"] !== true;
 }
@@ -33,73 +60,155 @@ function codeEnvPackageList(flags) {
 }
 export const codeEnvCommands = {
     list: {
-        handler: (c, _a, f) => c.codeEnvs.list({
-            envLang: f["lang"],
-        }),
-        usage: "dss code-env list [--lang LANG]",
-        description: "List code environments.",
+        handler: (c, _a, f) => {
+            const usage = "dss code-env list [--lang PYTHON|R]";
+            const lang = f["lang"];
+            return c.codeEnvs.list({
+                envLang: typeof lang === "string"
+                    ? requireEnvLang(lang, usage)
+                    : undefined,
+            });
+        },
+        usage: "dss code-env list [--lang PYTHON|R]",
+        description: "List code environments, optionally filtered to one language.",
         examples: ["dss code-env list", "dss code-env list --lang PYTHON",],
     },
     get: {
         handler: (c, a) => {
-            requireArgs(a, 2, "dss code-env get <lang> <name>");
-            return c.codeEnvs.get(a[0], a[1]);
+            const usage = "dss code-env get <lang> <name>";
+            requireArgs(a, 2, usage);
+            const envLang = requireEnvLang(a[0], usage);
+            return c.codeEnvs.get(envLang, a[1]);
         },
         usage: "dss code-env get <lang> <name>",
-        description: "Get code environment details.",
+        description: "Get code environment details: requested vs installed packages, Python interpreter, deployment mode, and the stable definition hash (definitionHash) used by set-definition --expect-hash.",
         examples: ["dss code-env get PYTHON my_env",],
     },
     "get-definition": {
         handler: (c, a) => {
-            requireArgs(a, 2, "dss code-env get-definition <lang> <name>");
-            return c.codeEnvs.getDefinition(a[0], a[1]);
+            const usage = "dss code-env get-definition <lang> <name>";
+            requireArgs(a, 2, usage);
+            const envLang = requireEnvLang(a[0], usage);
+            return c.codeEnvs.getDefinition(envLang, a[1]);
         },
         usage: "dss code-env get-definition <lang> <name>",
-        description: "Get raw code environment definition.",
+        description: "Get the raw code environment definition exactly as DSS stores it; capture its hash (definitionHash from code-env get) before replacing it with set-definition --expect-hash.",
         examples: ["dss code-env get-definition PYTHON my_env",],
     },
+    "list-logs": {
+        handler: (c, a) => {
+            const usage = "dss code-env list-logs <lang> <name>";
+            requireArgs(a, 2, usage);
+            const envLang = requireEnvLang(a[0], usage);
+            return c.codeEnvs.listLogs(envLang, a[1]);
+        },
+        usage: "dss code-env list-logs <lang> <name>",
+        description: "List the build log files DSS keeps for a code environment.",
+        examples: ["dss code-env list-logs PYTHON my_env",],
+    },
+    "get-log": {
+        handler: async (c, a, f) => {
+            const usage = "dss code-env get-log <lang> <name> <logName> [--max-lines N|--max-log-lines N] [--max-log-bytes N] [--output PATH]";
+            requireArgs(a, 3, usage);
+            const envLang = requireEnvLang(a[0], usage);
+            const maxLines = numFlag(f, ["max-lines", "max-log-lines",]);
+            const maxBytes = num(f["max-log-bytes"], "--max-log-bytes");
+            const result = await c.codeEnvs.getLog(envLang, a[1], a[2], {
+                ...(maxLines !== undefined ? { maxLines, } : {}),
+                ...(maxBytes !== undefined ? { maxBytes, } : {}),
+            });
+            const output = f["output"];
+            if (typeof output === "string" && output.trim().length > 0) {
+                writeFileSync(output, result.log, "utf-8");
+                if (result.truncated || result.tailed) {
+                    const limits = [
+                        result.tailed ? `tail limited to ${maxLines ?? 500} lines` : undefined,
+                        result.truncated ? "byte cap reached" : undefined,
+                    ].filter((part) => part !== undefined);
+                    enqueueCliWarning({
+                        code: "code_env_log_truncated",
+                        message: `Code env ${envLang}/${a[1]} log '${a[2]}' was truncated (${limits.join("; ")},). Pass --max-log-bytes 0 and --max-lines 0 for the full log, or refetch with higher limits.`,
+                        envLang,
+                        envName: a[1],
+                        logName: a[2],
+                        truncated: result.truncated,
+                        tailed: result.tailed,
+                    });
+                }
+                return {
+                    path: output,
+                    bytes: result.bytes,
+                    truncated: result.truncated,
+                    tailed: result.tailed,
+                    envLang,
+                    envName: a[1],
+                    logName: a[2],
+                };
+            }
+            return { ...result, envLang, envName: a[1], logName: a[2], };
+        },
+        usage: "dss code-env get-log <lang> <name> <logName> [--max-lines N|--max-log-lines N] [--max-log-bytes N] [--output PATH]",
+        description: "Fetch one code-env build log, bounded for safe output: the last --max-lines lines (default 500, 0 for all) and at most --max-log-bytes bytes (default 10 MiB, 0 for all). --output PATH writes the kept content to a file; stdout then carries the path metadata. A truncation warning names which cap hit.",
+        examples: [
+            "dss code-env get-log PYTHON my_env install.log --max-lines 200",
+            "dss code-env get-log PYTHON my_env install.log --output ./install.log --max-log-bytes 0",
+        ],
+    },
+    version: {
+        handler: (c, a) => {
+            const usage = "dss code-env version <lang> <name> <projectKey>";
+            requireArgs(a, 3, usage);
+            const envLang = requireEnvLang(a[0], usage);
+            return c.codeEnvs.getVersionForProject(envLang, a[1], a[2]);
+        },
+        usage: "dss code-env version <lang> <name> <projectKey>",
+        description: "Resolve the code environment version a project uses (versioned automation environments); empty version for unversioned environments.",
+        examples: ["dss code-env version PYTHON my_env MY_PROJ",],
+    },
     create: {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss code-env create <lang> <name> --deployment-mode MODE");
+            const usage = "dss code-env create <lang> <name> --deployment-mode MODE";
+            requireArgs(a, 2, usage);
+            const envLang = requireEnvLang(a[0], usage);
             const deploymentMode = f["deployment-mode"];
             if (!deploymentMode) {
                 throw new UsageError("--deployment-mode is required. Usage: dss code-env create <lang> <name> --deployment-mode MODE");
             }
             const params = codeEnvParams(f);
             const wait = codeEnvWait(f);
-            if (f["if-not-exists"] === true || f["dry-run"] === true) {
-                const existing = (await c.codeEnvs.list({ envLang: a[0], }))
+            if (f["if-not-exists"] === true || executionMode(f).dryRun) {
+                const existing = (await c.codeEnvs.list({ envLang, }))
                     .find((env) => env.envName === a[1]);
-                if (existing && f["if-not-exists"] === true && f["dry-run"] !== true) {
-                    return skipResult("code-env", a[1], "exists", { envLang: a[0], current: existing, });
+                if (existing && f["if-not-exists"] === true && !executionMode(f).dryRun) {
+                    return skipResult("code-env", a[1], "exists", { envLang, current: existing, });
                 }
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "create",
                         resource: "code-env",
-                        envLang: a[0],
+                        envLang,
                         envName: a[1],
                         payload: {
                             deploymentMode,
                             params,
-                            wait,
                         },
+                        wait,
                         ...(existing ? { current: existing, } : {}),
                     };
                 }
             }
             const created = await c.codeEnvs.create({
-                envLang: a[0],
+                envLang,
                 envName: a[1],
                 deploymentMode,
                 params,
                 wait,
             });
-            return { created: a[1], resource: "code-env", envLang: a[0], ...created, };
+            return { created: a[1], resource: "code-env", envLang, ...created, };
         },
         usage: "dss code-env create <lang> <name> --deployment-mode MODE [--params JSON|--data JSON|--data-file PATH|--stdin] [--python-interpreter PYTHON311] [--no-wait] [--if-not-exists] [--dry-run]",
-        description: "Create a code environment.",
+        description: "Create a code environment; --no-wait hands back a DSS future payload you can settle with dss future wait.",
         examples: [
             "dss code-env create PYTHON my_env --deployment-mode DESIGN_MANAGED --python-interpreter PYTHON311",
             'dss code-env create PYTHON my_env --deployment-mode DESIGN_MANAGED --params \'{"pythonInterpreter":"PYTHON311"}\' --dry-run',
@@ -107,47 +216,67 @@ export const codeEnvCommands = {
     },
     "set-definition": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss code-env set-definition <lang> <name> --data JSON");
+            const usage = "dss code-env set-definition <lang> <name> (--data JSON|--data-file PATH|--stdin) [--expect-hash SHA256]";
+            requireArgs(a, 2, usage);
+            const envLang = requireEnvLang(a[0], usage);
             const definition = jsonInput(f);
             if (!definition) {
                 throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss code-env set-definition <lang> <name> --data JSON");
             }
-            if (f["dry-run"] === true) {
+            const expectHash = validateExpectHash(f["expect-hash"]);
+            const definitionHash = stableHash(definition);
+            if (executionMode(f).dryRun) {
+                const current = await readIfExists(() => c.codeEnvs.getDefinition(envLang, a[1]));
+                const currentHash = current ? stableHash(current) : undefined;
+                if (expectHash !== undefined && currentHash !== expectHash) {
+                    throw definitionHashMismatch(envLang, a[1], expectHash, currentHash);
+                }
                 return {
                     dryRun: true,
                     action: "set-definition",
                     resource: "code-env",
-                    envLang: a[0],
+                    envLang,
                     envName: a[1],
                     definition,
+                    definitionHash,
+                    ...(currentHash !== undefined
+                        ? { currentDefinitionHash: currentHash, changed: currentHash !== definitionHash, }
+                        : {}),
+                    ...(expectHash !== undefined ? { expectHash, provenanceVerified: true, } : {}),
                 };
             }
-            return c.codeEnvs.setDefinition(a[0], a[1], definition);
+            return c.codeEnvs.setDefinition(envLang, a[1], definition, { expectHash, });
         },
-        usage: "dss code-env set-definition <lang> <name> (--data JSON|--data-file PATH|--stdin) [--dry-run]",
-        description: "Replace a code environment definition previously fetched from DSS.",
-        examples: ["dss code-env set-definition PYTHON my_env --data-file code-env.json --dry-run",],
+        usage: "dss code-env set-definition <lang> <name> (--data JSON|--data-file PATH|--stdin) [--expect-hash SHA256] [--dry-run]",
+        description: "Replace a code environment definition previously fetched from DSS (get-definition). --expect-hash SHA256 refuses the PUT unless the current definition still hashes to the hash captured with code-env get, so concurrent edits are never clobbered; --dry-run also fetches the current definition and reports both hashes plus a changed flag.",
+        examples: [
+            "dss code-env set-definition PYTHON my_env --data-file code-env.json --expect-hash $HASH --dry-run",
+        ],
     },
     "set-packages": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss code-env set-packages <lang> <name> --packages PKGS");
+            const usage = "dss code-env set-packages <lang> <name> (--packages PKGS|--package PKG|--file PATH)";
+            requireArgs(a, 2, usage);
+            const envLang = requireEnvLang(a[0], usage);
             const packages = codeEnvPackageList(f);
             const installCorePackages = parseBooleanOption(f["install-core-packages"], "--install-core-packages");
-            if (f["dry-run"] === true) {
+            const expectHash = validateExpectHash(f["expect-hash"]);
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "set-packages",
                     resource: "code-env",
-                    envLang: a[0],
+                    envLang,
                     envName: a[1],
                     packages,
                     installCorePackages,
+                    ...(expectHash !== undefined ? { expectHash, } : {}),
                 };
             }
-            return c.codeEnvs.setPackages(a[0], a[1], packages, { installCorePackages, });
+            return c.codeEnvs.setPackages(envLang, a[1], packages, { installCorePackages, expectHash, });
         },
-        usage: "dss code-env set-packages <lang> <name> (--packages PKGS|--package PKG|--file PATH) [--install-core-packages true|false] [--dry-run]",
-        description: "Update requested package specs without rebuilding packages.",
+        usage: "dss code-env set-packages <lang> <name> (--packages PKGS|--package PKG|--file PATH) [--install-core-packages true|false] [--expect-hash SHA256] [--dry-run]",
+        description: "Fetch the current definition, merge the requested package specs (and --install-core-packages) into it, then PUT the merged definition, so fields outside the package list are never dropped; --expect-hash refuses the merge when DSS changed since the hash was captured.",
         examples: [
             "dss code-env set-packages PYTHON my_env --packages 'tabulate\\nnameparser' --dry-run",
             "dss code-env set-packages PYTHON my_env --file requirements.txt",
@@ -155,7 +284,9 @@ export const codeEnvCommands = {
     },
     "update-packages": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss code-env update-packages <lang> <name>");
+            const usage = "dss code-env update-packages <lang> <name>";
+            requireArgs(a, 2, usage);
+            const envLang = requireEnvLang(a[0], usage);
             const wait = codeEnvWait(f);
             const versionToUpdate = typeof f["env-version"] === "string"
                 ? f["env-version"]
@@ -167,77 +298,108 @@ export const codeEnvCommands = {
                 versionToUpdate,
                 wait,
             };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "update-packages",
                     resource: "code-env",
-                    envLang: a[0],
+                    envLang,
                     envName: a[1],
                     ...opts,
                 };
             }
-            return c.codeEnvs.updatePackages(a[0], a[1], opts);
+            return c.codeEnvs.updatePackages(envLang, a[1], opts);
         },
         usage: "dss code-env update-packages <lang> <name> [--force-rebuild] [--env-version VERSION] [--no-wait] [--dry-run]",
-        description: "Rebuild or update code environment packages to match the requested specs.",
+        description: "Rebuild or update code environment packages to match the requested specs; --no-wait hands back a DSS future payload you can settle with dss future wait.",
         examples: ["dss code-env update-packages PYTHON my_env --force-rebuild --dry-run",],
     },
+    "update-images": {
+        handler: async (c, a, f) => {
+            const usage = "dss code-env update-images <lang> <name>";
+            requireArgs(a, 2, usage);
+            const envLang = requireEnvLang(a[0], usage);
+            const wait = codeEnvWait(f);
+            const envVersion = typeof f["env-version"] === "string" ? f["env-version"] : undefined;
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "update-images",
+                    resource: "code-env",
+                    envLang,
+                    envName: a[1],
+                    envVersion,
+                    wait,
+                };
+            }
+            return c.codeEnvs.updateImages(envLang, a[1], { envVersion, wait, });
+        },
+        usage: "dss code-env update-images <lang> <name> [--env-version VERSION] [--no-wait] [--dry-run]",
+        description: "Rebuild the Docker image(s) of a code environment to match its settings; --env-version targets one version of a versioned environment and --no-wait hands back a DSS future payload you can settle with dss future wait.",
+        examples: [
+            "dss code-env update-images PYTHON my_env --dry-run",
+            "dss code-env update-images PYTHON my_env --env-version v3 --no-wait",
+        ],
+    },
     "set-jupyter": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss code-env set-jupyter <lang> <name> --active true|false");
+            const usage = "dss code-env set-jupyter <lang> <name> --active true|false";
+            requireArgs(a, 2, usage);
+            const envLang = requireEnvLang(a[0], usage);
             const active = parseBooleanOption(f["active"], "--active");
             if (active === undefined) {
                 throw new UsageError("--active is required. Usage: dss code-env set-jupyter <lang> <name> --active true|false");
             }
             const wait = codeEnvWait(f);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "set-jupyter",
                     resource: "code-env",
-                    envLang: a[0],
+                    envLang,
                     envName: a[1],
                     active,
                     wait,
                 };
             }
-            return c.codeEnvs.setJupyterSupport(a[0], a[1], active, { wait, });
+            return c.codeEnvs.setJupyterSupport(envLang, a[1], active, { wait, });
         },
         usage: "dss code-env set-jupyter <lang> <name> --active true|false [--no-wait] [--dry-run]",
-        description: "Enable or disable Jupyter support for a code environment.",
+        description: "Enable or disable Jupyter support for a code environment; --no-wait hands back a DSS future payload you can settle with dss future wait.",
         examples: ["dss code-env set-jupyter PYTHON my_env --active true --dry-run",],
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss code-env delete <lang> <name>");
+            const usage = "dss code-env delete <lang> <name>";
+            requireArgs(a, 2, usage);
+            const envLang = requireEnvLang(a[0], usage);
             const wait = codeEnvWait(f);
-            if (f["dry-run"] === true) {
-                const current = await readIfExists(() => c.codeEnvs.get(a[0], a[1]));
+            if (executionMode(f).dryRun) {
+                const current = await readIfExists(() => c.codeEnvs.get(envLang, a[1]));
                 if (!current)
-                    return skipResult("code-env", a[1], "missing", { envLang: a[0], });
+                    return skipResult("code-env", a[1], "missing", { envLang, });
                 return {
                     dryRun: true,
                     action: "delete",
                     resource: "code-env",
-                    envLang: a[0],
+                    envLang,
                     envName: a[1],
                     wait,
                     current,
                 };
             }
             if (f["if-exists"] === true) {
-                return await c.codeEnvs.delete(a[0], a[1], { wait, }).catch((error) => {
+                return await c.codeEnvs.delete(envLang, a[1], { wait, }).catch((error) => {
                     if (isNotFoundError(error)) {
-                        return skipResult("code-env", a[1], "missing", { envLang: a[0], });
+                        return skipResult("code-env", a[1], "missing", { envLang, });
                     }
                     throw error;
                 });
             }
-            return c.codeEnvs.delete(a[0], a[1], { wait, });
+            return c.codeEnvs.delete(envLang, a[1], { wait, });
         },
         usage: "dss code-env delete <lang> <name> [--no-wait] [--if-exists] [--dry-run]",
-        description: "Delete a code environment.",
+        description: "Delete a code environment; --no-wait hands back a DSS future payload you can settle with dss future wait.",
         examples: ["dss code-env delete PYTHON my_env --dry-run",],
     },
     usages: {

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

@@ -1,2 +1,21 @@
 import type { CommandMeta } from "../types.js";
+export interface CodeInputSource {
+    kind: "file" | "stdin";
+    path?: string;
+}
+export interface ResolvedCodeInput {
+    script: string;
+    source: CodeInputSource;
+}
+/**
+ * Canonical validation of `code run` input: rejects positional args and
+ * conflicting sources, reads the chosen source, strips a UTF-8 BOM, and
+ * rejects empty scripts. Returns the script plus source metadata so plan or
+ * replay payloads can hash the script and reference the source without
+ * embedding its contents.
+ */
+export declare function resolveCodeInputWithSource(args: string[], flags: Record<string, string | boolean>): ResolvedCodeInput;
+export declare function resolveCodeInput(args: string[], flags: Record<string, string | boolean>): string;
+/** Parse an integer flag value, rejecting negative and fractional values before any DSS request. */
+export declare function parseCodeRunIntegerFlag(value: string | boolean | undefined, flagName: string): number | undefined;
 export declare const codeCommands: Record<string, CommandMeta>;

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

@@ -1,17 +1,44 @@
 import { readFileSync, } from "node:fs";
+import { ScenarioScriptRunWithCleanupFailureError, } from "../../resources/scenarios.js";
 import { num, readStdinText, stripUtf8Bom, } from "../coerce.js";
+import { enqueueCliWarning, } from "../output.js";
 import { UsageError, } from "../usage.js";
-const CODE_RUN_USAGE = "dss code run (--file PATH | --stdin) [--env ENV] [--timeout MS] [--keep] [--full-log] [--max-log-bytes N] [--project-key KEY]";
-function resolveCodeInput(args, flags) {
+const CODE_RUN_USAGE = "dss code run (--file PATH | --stdin) [--env ENV] [--timeout MS (default 120000)] [--keep] [--full-log] [--max-log-bytes N (default 1048576)] [--project-key KEY]";
+function previewFlagValue(value) {
+    const text = typeof value === "string" ? value : String(value);
+    return text.length <= 32 ? text : `${text.slice(0, 32)}…`;
+}
+/** Read a local Python source file, mapping read failures to usage validation. */
+function readCodeSourceFile(filePath) {
+    try {
+        return readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        throw new UsageError(`Could not read --file ${filePath}: ${error instanceof Error ? error.message : String(error)}.`, "not_found", "Verify the file path and that it is readable.");
+    }
+}
+/**
+ * Canonical validation of `code run` input: rejects positional args and
+ * conflicting sources, reads the chosen source, strips a UTF-8 BOM, and
+ * rejects empty scripts. Returns the script plus source metadata so plan or
+ * replay payloads can hash the script and reference the source without
+ * embedding its contents.
+ */
+export function resolveCodeInputWithSource(args, flags) {
     if (args.length > 0) {
         throw new UsageError(`code run takes no positional arguments; pass the script via --file PATH or --stdin. Usage: ${CODE_RUN_USAGE}`);
     }
     const sources = [];
     if (typeof flags["file"] === "string") {
-        sources.push({ label: "--file", read: () => readFileSync(flags["file"], "utf-8"), });
+        sources.push({
+            kind: "file",
+            label: "--file",
+            path: flags["file"],
+            read: () => readCodeSourceFile(flags["file"]),
+        });
     }
     if (flags["stdin"] === true) {
-        sources.push({ label: "--stdin", read: readStdinText, });
+        sources.push({ kind: "stdin", label: "--stdin", read: readStdinText, });
     }
     if (sources.length === 0) {
         throw new UsageError(`Python source is required: pass --file PATH or --stdin. Usage: ${CODE_RUN_USAGE}`);
@@ -19,23 +46,63 @@ function resolveCodeInput(args, flags) {
     if (sources.length > 1) {
         throw new UsageError(`Choose exactly one Python source: --file or --stdin. Usage: ${CODE_RUN_USAGE}`);
     }
-    const script = stripUtf8Bom(sources[0].read());
+    const source = sources[0];
+    const script = stripUtf8Bom(source.read());
     if (script.trim().length === 0) {
-        throw new UsageError(`Python source from ${sources[0].label} must not be empty. Usage: ${CODE_RUN_USAGE}`);
+        throw new UsageError(`Python source from ${source.label} must not be empty. Usage: ${CODE_RUN_USAGE}`);
+    }
+    return {
+        script,
+        source: source.kind === "file" ? { kind: "file", path: source.path, } : { kind: "stdin", },
+    };
+}
+export function resolveCodeInput(args, flags) {
+    return resolveCodeInputWithSource(args, flags).script;
+}
+/** Parse an integer flag value, rejecting negative and fractional values before any DSS request. */
+export function parseCodeRunIntegerFlag(value, flagName) {
+    const parsed = num(value, flagName);
+    if (parsed === undefined)
+        return undefined;
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        const valuePreview = previewFlagValue(value);
+        throw new UsageError(`Invalid value for ${flagName}: expected a non-negative integer, got ${valuePreview}.`, "invalid_flag_value", undefined, { flag: flagName, value: valuePreview, });
     }
-    return script;
+    return parsed;
+}
+function reportCleanupFailure(cleanupFailure) {
+    enqueueCliWarning({
+        type: "code_run_cleanup_failed",
+        scenarioId: cleanupFailure.scenarioId,
+        error: cleanupFailure.error,
+    });
+}
+function unwrapCodeRunError(error) {
+    if (error instanceof ScenarioScriptRunWithCleanupFailureError) {
+        reportCleanupFailure(error.cleanupFailure);
+        return error.cause;
+    }
+    return error;
 }
 export const codeCommands = {
     run: {
         handler: async (c, a, f) => {
+            const timeoutMs = parseCodeRunIntegerFlag(f["timeout"], "--timeout");
+            const maxLogBytes = parseCodeRunIntegerFlag(f["max-log-bytes"], "--max-log-bytes");
             const script = resolveCodeInput(a, f);
-            const run = await c.scenarios.runScript(script, {
-                envName: f["env"],
-                projectKey: f["project-key"],
-                timeoutMs: num(f["timeout"], "--timeout"),
-                keepScenario: f["keep"] === true,
-                maxLogBytes: num(f["max-log-bytes"], "--max-log-bytes"),
-            });
+            let run;
+            try {
+                run = await c.scenarios.runScript(script, {
+                    envName: f["env"],
+                    projectKey: f["project-key"],
+                    timeoutMs,
+                    keepScenario: f["keep"] === true,
+                    maxLogBytes,
+                });
+            }
+            catch (error) {
+                throw unwrapCodeRunError(error);
+            }
             const result = {
                 outcome: run.outcome,
                 success: run.success,
@@ -45,14 +112,19 @@ export const codeCommands = {
                 output: run.output ?? "",
                 logTruncated: run.logTruncated,
                 maxLogBytes: run.maxLogBytes,
+                cleanup: run.cleanup,
+                ...(run.timedOut === true ? { timedOut: true, timeoutMs: run.timeoutMs, } : {}),
             };
             if (f["full-log"] === true || run.output === undefined) {
                 result.log = run.log;
             }
+            if (run.cleanup.status === "failed") {
+                reportCleanupFailure({ scenarioId: run.scenarioId, error: run.cleanup.error ?? "unknown", });
+            }
             return result;
         },
         usage: CODE_RUN_USAGE,
-        description: "Run one-off Python in a DSS code env via a throwaway custom-python scenario; returns the script's captured output (stdout+stderr) plus outcome/success. Log retrieval is capped by --max-log-bytes (default 1048576); pass --full-log to include the capped raw DSS run log. Exits 4 on a non-SUCCESS outcome.",
+        description: "Run Python through a throwaway custom-python scenario and return captured output plus outcome. --timeout caps waiting; --max-log-bytes caps logs; --full-log returns the capped raw log. Exits 4 unless outcome is SUCCESS.",
         examples: [
             "dss code run --file inspect.py",
             "dss code run --file inspect.py --env py39_pandas",

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

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import { ClientValidationError, } from "../../errors.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { jsonInput, parseBooleanOption, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const dashboardCommands = {
@@ -106,12 +107,12 @@ export const dashboardCommands = {
             if (listed !== undefined)
                 payload.listed = listed;
             const pk = f["project-key"];
-            if (f["if-not-exists"] === true || f["dry-run"] === true) {
+            if (f["if-not-exists"] === true || executionMode(f).dryRun) {
                 const existing = (await c.dashboards.list(pk)).find((dashboard) => dashboard.name === name);
-                if (existing && f["if-not-exists"] === true && f["dry-run"] !== true) {
+                if (existing && f["if-not-exists"] === true && !executionMode(f).dryRun) {
                     return skipResult("dashboard", existing.id, "exists", { current: existing, });
                 }
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "create",
@@ -146,7 +147,7 @@ export const dashboardCommands = {
             if (name === undefined && listed === undefined && !data) {
                 throw new UsageError("--name, --listed, --data, --data-file, or --stdin is required.");
             }
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.dashboards.get(a[0], f["project-key"]);
                 const next = deepMerge(current, data ?? {});
                 if (name !== undefined)
@@ -170,11 +171,11 @@ export const dashboardCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss dashboard delete <id>");
             const pk = f["project-key"];
-            if (f["dry-run"] === true || f["if-exists"] === true) {
+            if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.dashboards.get(a[0], pk));
                 if (!current)
                     return skipResult("dashboard", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "dashboard", id: a[0], current, };
                 }
             }