dataiku-sdk 3.1.0 → 3.3.0

package/dist/packages/types/src/index.js

@@ -113,6 +113,9 @@ export const ProjectMetadataSchema = Type.Object({
         }, { additionalProperties: true, }))),
     }, { additionalProperties: true, })),
 }, { additionalProperties: true, });
+export const ProjectTagsSchema = Type.Object({
+    tags: Type.Record(Type.String(), Type.Object({ color: Type.Optional(Type.String()), }, { additionalProperties: true, }), { additionalProperties: true, }),
+}, { additionalProperties: true, });
 // ---------------------------------------------------------------------------
 // Datasets
 // ---------------------------------------------------------------------------
@@ -347,6 +350,67 @@ export const ScenarioWaitResultSchema = Type.Object({
     steps: Type.Optional(Type.Array(ScenarioStepRunSchema)),
 });
 // ---------------------------------------------------------------------------
+// Macros (runnables)
+// ---------------------------------------------------------------------------
+/** A macro definition as returned by GET /projects/{pk}/runnables/{runnableType}. */
+export const MacroDefinitionSchema = Type.Object({
+    runnableType: Type.String(),
+    ownerPluginId: Type.Optional(Type.String()),
+    meta: Type.Optional(Type.Object({
+        label: Type.Optional(Type.String()),
+    }, { additionalProperties: true, })),
+    longDescription: Type.Optional(Type.String()),
+    resultType: Type.Optional(Type.String()),
+    extension: Type.Optional(Type.String()),
+    mimeType: Type.Optional(Type.String()),
+    resultLabel: Type.Optional(Type.String()),
+    params: Type.Optional(Type.Array(Type.Object({
+        name: Type.String(),
+        type: Type.Optional(Type.String()),
+    }, { additionalProperties: true, }))),
+    adminParams: Type.Optional(Type.Array(Type.Unknown())),
+}, { additionalProperties: true, });
+/** One entry of GET /projects/{pk}/runnables (array[Macro]). */
+export const MacroSummarySchema = Type.Object({
+    runnableType: Type.Optional(Type.String()),
+    /** Owning plugin id as the server returns it (live identifiers are server-authored). */
+    ownerPluginId: Type.Optional(Type.String()),
+    meta: Type.Optional(Type.Object({
+        label: Type.Optional(Type.String()),
+    }, { additionalProperties: true, })),
+}, { additionalProperties: true, });
+export const MacroSummaryArraySchema = Type.Array(MacroSummarySchema);
+/**
+ * Poll-state response of GET /projects/{pk}/runnables/{runnableType}/state/{run}.
+ * While running: `running: true` and optionally a stack of `progress` entries.
+ * When finished: `running: false`; on failure `resultError`/`storedError` carry
+ * details, otherwise `type` is filled.
+ */
+export const MacroStateSchema = Type.Object({
+    exists: Type.Optional(Type.Boolean()),
+    running: Type.Optional(Type.Boolean()),
+    empty: Type.Optional(Type.Boolean()),
+    type: Type.Optional(Type.String()),
+    progress: Type.Optional(Type.Unknown()),
+    resultError: Type.Optional(Type.Unknown()),
+    storedError: Type.Optional(Type.Unknown()),
+}, { additionalProperties: true, });
+/** Run trigger response of POST /projects/{pk}/runnables/{runnableType}. */
+export const MacroRunStartSchema = Type.Object({
+    runId: Type.String(),
+}, { additionalProperties: true, });
+/** Result of {@link MacrosResource.runAndWait}: bounded client-side polling. */
+export const MacroWaitResultSchema = Type.Object({
+    runnableType: Type.String(),
+    runId: Type.String(),
+    running: Type.Boolean(),
+    success: Type.Boolean(),
+    elapsedMs: Type.Number(),
+    pollCount: Type.Number(),
+    timedOut: Type.Optional(Type.Boolean()),
+    state: Type.Optional(MacroStateSchema),
+}, { additionalProperties: true, });
+// ---------------------------------------------------------------------------
 // Flow zones
 // ---------------------------------------------------------------------------
 export const FlowZoneObjectTypeSchema = Type.Union([
@@ -631,6 +695,11 @@ export const SqlNotebookCellSchema = Type.Object({
     id: Type.String(),
     type: Type.String(),
     name: Type.Optional(Type.String()),
+    /**
+     * Cell source. DSS enforces a JSON string here: an array fails to parse
+     * server-side (`Expected a string but was BEGIN_ARRAY ... $.cells[0].code`),
+     * so the official-client example's line-array form does not apply to SQL.
+     */
     code: Type.String(),
 }, { additionalProperties: true, });
 export const SqlNotebookSummarySchema = Type.Object({
@@ -639,6 +708,13 @@ export const SqlNotebookSummarySchema = Type.Object({
     language: Type.String(),
     connection: Type.String(),
 }, { additionalProperties: true, });
+/**
+ * A SQL notebook's content as returned by GET. The notebook record carries
+ * the server-allocated `id` (a request-supplied `id` is rejected on create)
+ * plus `name`/`projectKey`/`isRunning` and similar receipt fields via
+ * `additionalProperties`; requests supply `connection` + `cells` (and
+ * optionally `name` as the display handle).
+ */
 export const SqlNotebookContentSchema = Type.Object({
     connection: Type.String(),
     cells: Type.Array(SqlNotebookCellSchema),

package/dist/src/auth.js

@@ -1,7 +1,7 @@
-import { DataikuClient, } from "./client.js";
 import { DataikuError, } from "./errors.js";
 export async function validateCredentials(url, apiKey, options = {}) {
     try {
+        const { DataikuClient, } = await import("./client.js");
         const client = new DataikuClient({
             url,
             apiKey,

package/dist/src/cli/coerce.js

@@ -169,6 +169,15 @@ function selectSingleSource(flags, sourceFlags) {
     }
     return provided[0];
 }
+function readInputText(path, flag) {
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch (error) {
+        const cause = error.code;
+        throw new UsageError(`Could not read ${flag} file: ${path}`, "validation_failed", "Verify that the path names an existing, readable file.", { flag, path, ...(cause ? { cause, } : {}), });
+    }
+}
 function resolveJsonSourceText(flags, kind) {
     const source = selectSingleSource(flags, JSON_SOURCE_FLAGS);
     if (source === undefined)
@@ -182,7 +191,7 @@ function resolveJsonSourceText(flags, kind) {
     if (source === "data-file") {
         const fileValue = flags["data-file"];
         if (typeof fileValue === "string") {
-            const jsonText = readFileSync(fileValue, "utf-8");
+            const jsonText = readInputText(fileValue, "--data-file");
             return kind === "object"
                 ? parseJsonObject(jsonText, fileValue)
                 : parseJsonValue(jsonText, fileValue);
@@ -241,7 +250,7 @@ export function textInput(flags) {
     if (source === "file") {
         const fileValue = flags["file"];
         if (typeof fileValue === "string")
-            return readFileSync(fileValue, "utf-8");
+            return readInputText(fileValue, "--file");
     }
     const contentValue = flags["content"];
     if (typeof contentValue === "string")

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

@@ -1,4 +1,5 @@
 import { requiredStringFlag, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
 import { requireArgs, } from "../usage.js";
 export const analysisCommands = {
@@ -23,7 +24,7 @@ export const analysisCommands = {
             const inputDataset = requiredStringFlag(f, "input-dataset", usage);
             const projectKey = f["project-key"];
             const options = { inputDataset, projectKey, };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "create",
@@ -45,11 +46,11 @@ export const analysisCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss analysis delete <analysisId> [--if-exists] [--dry-run] [--project-key KEY]");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true || f["if-exists"] === true) {
+            if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.analyses.get(a[0], projectKey));
                 if (!current)
                     return skipResult("analysis", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "analysis", id: a[0], current, };
                 }
             }

package/dist/src/cli/commands/api-service.js

@@ -1,6 +1,8 @@
 import { ClientValidationError, } from "../../errors.js";
+import { writeResponseToFile, } from "../../utils/response-file.js";
 import { stableHash, } from "../../utils/stable-hash.js";
 import { requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { requireArgs, UsageError, } from "../usage.js";
 function validateExpectHash(value) {
     if (value === undefined || value === false)
@@ -42,7 +44,7 @@ export const apiServiceCommands = {
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (service settings).");
             const projectKey = f["project-key"];
             const expectHash = validateExpectHash(f["expect-hash"]);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.apiServices.getSettings(a[0], projectKey);
                 const currentHash = stableHash(current);
                 if (expectHash !== undefined && currentHash !== expectHash.toLowerCase()) {
@@ -81,7 +83,7 @@ export const apiServiceCommands = {
                 type: "STD_PREDICTION",
                 modelRef: a[2],
             };
-            if (f["dry-run"] === true)
+            if (executionMode(f).dryRun)
                 return endpoint;
             return c.apiServices.addPredictionEndpoint(a[0], a[1], a[2], f["project-key"]);
         },
@@ -143,7 +145,7 @@ export const apiServiceCommands = {
             if (!res.body) {
                 throw new Error("apiServices.downloadPackageArchive response did not include a body");
             }
-            const bytes = await Bun.write(out, new Response(res.body), { createPath: false, });
+            const bytes = await writeResponseToFile(out, res);
             return { path: out, bytes, };
         },
         usage: "dss api-service download-package <serviceId> <packageId> --output PATH [--project-key KEY]",

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

@@ -1,19 +1,20 @@
 import { ClientValidationError, DataikuError, } from "../../errors.js";
 import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
 import { jsonInput, num, parseBooleanOption, plainRecord, requiredJsonInput, requiredStringFlag, stringField, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { appPermissionsHash, appPermissionsVerificationError, assertAppPermissionsSnapshotBinding, buildAppPermissionsSnapshot, diffAppPermissions, readAppPermissionsSnapshot, writeAppPermissionsSnapshot, } from "../helpers/app-permissions.js";
-import { createSuccessorInstance, futureTargetIdentity, isDefinitiveRejection, preflightSuccessorInstance, requireAbsentProjectTarget, safeErrorSummary, verifyAppInstance, VISUAL_UI_GATE, } from "../helpers/app-successor.js";
+import { createSuccessorInstance, futureTargetIdentity, generatedInstanceKey, isDefinitiveRejection, preflightSuccessorInstance, requireAbsentProjectTarget, safeErrorSummary, verifyAppInstance, VISUAL_UI_GATE, } from "../helpers/app-successor.js";
 import { CommandResultFailure, } from "../output.js";
 import { requireArgs, requireNoArgs, UsageError, } from "../usage.js";
 const CREATE_INSTANCE_USAGE = "dss app create-instance <appId> (--data JSON|--data-file PATH|--stdin) [--wait] [--timeout MS] [--poll-interval MS]";
 const MANIFEST_VERSION_USAGE = "dss app manifest-version [--project-key KEY]";
 const SET_MANIFEST_VERSION_USAGE = "dss app set-manifest-version (--manifest-version V|--version-notes NOTES) [--expect-hash SHA256] [--dry-run] [--project-key KEY]";
-const CREATE_SUCCESSOR_USAGE = "dss app create-successor-instance <appId> --from KEY --to KEY [--name NAME] [--copy-permissions] [--timeout MS] [--poll-interval MS] [--dry-run] [--record-cleanup PATH]";
-const SUCCESSOR_PREFLIGHT_USAGE = "dss app successor-preflight <appId> --from KEY --to KEY [--name NAME] [--copy-permissions]";
+const CREATE_SUCCESSOR_USAGE = "dss app create-successor-instance <appId> --from KEY [--to KEY] [--name NAME] [--copy-permissions] [--timeout MS] [--poll-interval MS] [--dry-run] [--record-cleanup PATH]";
+const SUCCESSOR_PREFLIGHT_USAGE = "dss app successor-preflight <appId> --from KEY [--to KEY] [--name NAME] [--copy-permissions]";
 const VERIFY_INSTANCE_USAGE = "dss app verify-instance <appId> --project-key KEY [--expect-version V]";
 const DELETE_INSTANCE_USAGE = "dss app delete-instance --project-key KEY [--future-id ID] [--expect-project-incarnation SHA256] [--unconfirmed-creation] [--timeout MS] [--poll-interval MS]";
 const CREATE_INSTANCE_INDETERMINATE_REMEDIATION = "DSS may have accepted the creation, but no future ID or project incarnation authorizes cleanup. Inspect `dss app instances <appId>` and DSS task history; delete only after creation is known terminal and the target identity is verified.";
-const CREATE_INSTANCE_REJECTED_REMEDIATION = "DSS refused the creation request, so no instance project was created: fix the reported problem and retry.";
+const CREATE_INSTANCE_REJECTED_REMEDIATION = "DSS refused the creation request, so no instance project was created: fix the reported problem and retry. If the target key itself is the problem, rerun create-instance with targetProjectKey omitted to generate a fresh random key (the generated key is a new key, never the rejected one).";
 const DELETE_INSTANCE_FUTURE_REMEDIATION = "The supplied creation future could not authorize deletion. Inspect that future and the target project, then retry only with a future whose terminal result reports this project.";
 const DELETE_INSTANCE_UNCONFIRMED_REMEDIATION = "Creation may still be running and DSS returned no future ID. Inspect the app's instances and wait until creation is known terminal before running delete-instance without --unconfirmed-creation.";
 const DELETE_INSTANCE_DELETE_REMEDIATION = "Future safety checks passed, but the project DELETE outcome is unresolved. Inspect the target project; if it still exists, retry delete-instance.";
@@ -51,6 +52,21 @@ async function assertProjectIncarnationHash(client, projectKey, expected) {
         return;
     throw new ClientValidationError(`Project ${projectKey} is not the same project incarnation recorded for this operation.`, "validation_failed", "Refusing to continue after project-key reuse. Re-read the current project and retry only with an artifact captured from that incarnation.", { projectKey, expectedProjectIncarnationHash: expected, currentProjectIncarnationHash: current, });
 }
+/**
+ * Optional caller-chosen successor key. Absent selects generated-key mode: the
+ * key is generated exactly once during apply (never during plan, preflight or
+ * dry-run) and no absence probe runs. A present-but-empty value is an input
+ * error, never a silent fallback to a generated key.
+ */
+function optionalSuccessorTarget(flags, usage) {
+    const value = flags["to"];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new UsageError("--to must not be empty when supplied; omit --to entirely to create the successor with a generated key.", "validation_failed", `Usage: ${usage}`);
+    }
+    return value.trim();
+}
 export const appCommands = {
     list: {
         handler: (c) => c.applications.listApps(),
@@ -112,14 +128,36 @@ export const appCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, CREATE_INSTANCE_USAGE);
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (instance creation payload).");
-            const requestedProjectKey = stringField(body, ["targetProjectKey",])?.trim();
-            if (!requestedProjectKey) {
-                throw new UsageError("Instance creation payload must include a non-empty targetProjectKey.", "validation_failed", `Usage: ${CREATE_INSTANCE_USAGE}`);
+            let requestedProjectKey;
+            if (body["targetProjectKey"] === undefined) {
+                // Designer-friendly generated mode, mirroring the official Python
+                // client and the successor command's generated mode: one shared
+                // generator produces a random APP_ key (122 random bits of
+                // UUIDv4 hex, collisions negligible) that is POSTed as the
+                // authoritative targetProjectKey. No absent-project probe runs
+                // for a generated key, and errors never retry or fall back to
+                // an alternate key.
+                requestedProjectKey = generatedInstanceKey();
+                // Official key-as-name convenience: the display name defaults to
+                // the generated key when no targetProjectName is supplied.
+                if (body["targetProjectName"] === undefined) {
+                    body.targetProjectName = requestedProjectKey;
+                }
+            }
+            else {
+                // Explicit keys keep the strict caller-chosen-key contract: the
+                // payload value must be a non-empty string, and the target must
+                // be proven absent before the POST.
+                const explicitKey = stringField(body, ["targetProjectKey",])?.trim();
+                if (!explicitKey) {
+                    throw new UsageError("Instance creation payload must include a non-empty targetProjectKey.", "validation_failed", `Usage: ${CREATE_INSTANCE_USAGE}`);
+                }
+                requestedProjectKey = explicitKey;
+                await requireAbsentProjectTarget(c, requestedProjectKey, "targetProjectKey", {
+                    appId: a[0],
+                });
             }
             body.targetProjectKey = requestedProjectKey;
-            await requireAbsentProjectTarget(c, requestedProjectKey, "targetProjectKey", {
-                appId: a[0],
-            });
             let created;
             try {
                 created = await c.applications.createInstance(a[0], body);
@@ -351,50 +389,55 @@ export const appCommands = {
             };
         },
         usage: CREATE_INSTANCE_USAGE,
-        description: "Create an app instance from a Dataiku App template, optionally waiting for the instance-creation future returned by DSS.",
+        description: "Create an app instance from a Dataiku App template, optionally waiting for the creation future. Omit targetProjectKey to generate a random APP_ key (the default display name); explicit keys are trimmed and must be absent.",
         examples: [
             'dss app create-instance my-app --data \'{"targetProjectKey":"NEWPROJ"}\'',
             'dss app create-instance my-app --data \'{"targetProjectKey":"NEWPROJ"}\' --wait --timeout 120000 --poll-interval 2000',
+            "dss app create-instance my-app --data '{}' --wait",
         ],
     },
     "successor-preflight": {
         handler: async (c, a, f) => {
             requireArgs(a, 1, SUCCESSOR_PREFLIGHT_USAGE);
+            const to = optionalSuccessorTarget(f, SUCCESSOR_PREFLIGHT_USAGE);
             return preflightSuccessorInstance(c, {
                 appId: a[0],
                 from: requiredStringFlag(f, "from", SUCCESSOR_PREFLIGHT_USAGE),
-                to: requiredStringFlag(f, "to", SUCCESSOR_PREFLIGHT_USAGE),
+                ...(to !== undefined ? { to, } : {}),
                 ...(f["name"] !== undefined ? { name: f["name"], } : {}),
                 copyPermissions: parseBooleanOption(f["copy-permissions"], "--copy-permissions") ?? false,
                 dryRun: true,
             }, SUCCESSOR_PREFLIGHT_USAGE);
         },
         usage: SUCCESSOR_PREFLIGHT_USAGE,
-        description: "Run every read-only successor gate before changing the template version: validate the template, verify the predecessor, prove target absence, and optionally snapshot the predecessor ACL.",
+        description: "Run every read-only successor gate before changing the template version: validate the template, verify the predecessor, prove an explicit --to target absent, and optionally snapshot the predecessor ACL. Omit --to to preflight generated-key mode, where no target exists yet and nothing is probed or allocated.",
         examples: [
             "dss app successor-preflight my-app --from OLD_INSTANCE --to NEW_INSTANCE",
             "dss app successor-preflight my-app --from OLD_INSTANCE --to NEW_INSTANCE --copy-permissions",
+            "dss app successor-preflight my-app --from OLD_INSTANCE",
         ],
     },
     "create-successor-instance": {
         handler: async (c, a, f) => {
             requireArgs(a, 1, CREATE_SUCCESSOR_USAGE);
+            const to = optionalSuccessorTarget(f, CREATE_SUCCESSOR_USAGE);
             return createSuccessorInstance(c, {
                 appId: a[0],
                 from: requiredStringFlag(f, "from", CREATE_SUCCESSOR_USAGE),
-                to: requiredStringFlag(f, "to", CREATE_SUCCESSOR_USAGE),
+                ...(to !== undefined ? { to, } : {}),
                 ...(f["name"] !== undefined ? { name: f["name"], } : {}),
                 copyPermissions: parseBooleanOption(f["copy-permissions"], "--copy-permissions") ?? false,
-                dryRun: parseBooleanOption(f["dry-run"], "--dry-run") ?? false,
+                dryRun: executionMode(f).dryRun,
                 timeoutMs: num(f["timeout"], "--timeout"),
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
             }, CREATE_SUCCESSOR_USAGE);
         },
         usage: CREATE_SUCCESSOR_USAGE,
-        description: "Create a new app instance from the current template version alongside an existing instance. The predecessor is never modified and is retired separately and deliberately; the creation future is always awaited.",
+        description: "Create a new app instance from the current template version alongside an existing instance. An explicit --to keeps the strict caller-chosen-key contract (proven absent before the single POST); omit --to to generate the successor key once during apply and let the terminal future name it. The predecessor is never modified and is retired separately and deliberately; the creation future is always awaited.",
         examples: [
             "dss app create-successor-instance my-app --from OLD_INSTANCE --to NEW_INSTANCE",
             'dss app create-successor-instance my-app --from OLD_INSTANCE --to NEW_INSTANCE --name "Release 2" --copy-permissions',
+            "dss app create-successor-instance my-app --from OLD_INSTANCE",
         ],
     },
     "instance-manifest": {
@@ -445,7 +488,7 @@ export const appCommands = {
                 ...(version !== undefined ? { version, } : {}),
                 ...(versionNotes !== undefined ? { versionNotes, } : {}),
                 ...(f["expect-hash"] !== undefined ? { expectHash: f["expect-hash"], } : {}),
-                dryRun: parseBooleanOption(f["dry-run"], "--dry-run") ?? false,
+                dryRun: executionMode(f).dryRun,
             }, f["project-key"]);
             if (result.outcome === "indeterminate") {
                 // The PUT may or may not have landed. Fail nonzero without
@@ -756,7 +799,7 @@ export const appCommands = {
             assertAppPermissionsSnapshotBinding(snapshot, projectKey, c.getBaseUrl());
             const currentProjectIncarnationHash = await requireProjectIncarnationHash(c, projectKey);
             assertAppPermissionsSnapshotBinding(snapshot, projectKey, c.getBaseUrl(), currentProjectIncarnationHash);
-            const dryRun = parseBooleanOption(f["dry-run"], "--dry-run") ?? false;
+            const dryRun = executionMode(f).dryRun;
             const before = await c.projects.getPermissions(projectKey);
             await assertProjectIncarnationHash(c, projectKey, snapshot.projectIncarnationHash);
             const beforeHash = appPermissionsHash(before);

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

@@ -1,3 +1,4 @@
+import { writeResponseToFile, } from "../../utils/response-file.js";
 import { json, parseBooleanOption, } from "../coerce.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const bundleCommands = {
@@ -22,7 +23,7 @@ export const bundleCommands = {
             return { exported: a[0], };
         },
         usage: "dss bundle export <bundleId> [--release-notes TEXT] [--evaluate-standards-checks true|false] [--project-key KEY]",
-        description: "Create (or overwrite) an exported Design-node bundle. --release-notes forwards the documented releaseNotes parameter; --evaluate-standards-checks toggles the documented Project Standards Checks evaluation (default true).",
+        description: "Create an exported Design-node bundle. --release-notes forwards the documented releaseNotes parameter; --evaluate-standards-checks toggles the documented Project Standards Checks evaluation (default true; this instance forbids disabling it). DSS refuses re-exporting an existing bundle id — delete-exported first to replace one.",
         examples: [
             "dss bundle export v1",
             "dss bundle export v1 --release-notes='Adds churn model' --evaluate-standards-checks=false",
@@ -48,7 +49,7 @@ export const bundleCommands = {
             if (!res.body) {
                 throw new Error("bundles.downloadExportedArchive response did not include a body");
             }
-            const bytes = await Bun.write(out, new Response(res.body), { createPath: false, });
+            const bytes = await writeResponseToFile(out, res);
             return { path: out, bytes, };
         },
         usage: "dss bundle download-exported <bundleId> --output PATH [--project-key KEY]",

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

@@ -2,6 +2,7 @@ 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",];
@@ -41,19 +42,25 @@ function codeEnvParams(flags) {
 function splitPackageSpec(raw) {
     return raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
 }
+/**
+ * Resolve requested package specs from --file/--packages/--package. An
+ * explicit source that resolves to zero specs is a legitimate clear
+ * (set-packages replaces specPackageList wholesale); only a call with no
+ * package source flag at all is a usage error.
+ */
 function codeEnvPackageList(flags) {
-    const packages = [];
-    if (typeof flags["file"] === "string") {
-        packages.push(...splitPackageSpec(readFileSync(flags["file"], "utf-8")));
-    }
+    const file = flags["file"];
+    const packages = typeof file === "string" ? splitPackageSpec(readFileSync(file, "utf-8")) : [];
     if (typeof flags["packages"] === "string") {
         packages.push(...splitPackageSpec(flags["packages"]));
     }
     if (typeof flags["package"] === "string") {
         packages.push(...splitPackageSpec(flags["package"]));
     }
-    if (packages.length === 0) {
-        throw new UsageError("--packages, --package, or --file is required. Use newline-separated package specs for version constraints.");
+    if (typeof file !== "string"
+        && typeof flags["packages"] !== "string"
+        && typeof flags["package"] !== "string") {
+        throw new UsageError("--packages, --package, or --file is required. Use newline-separated package specs for version constraints; an explicitly empty value (or empty file) clears the requested package list.");
     }
     return packages;
 }
@@ -175,13 +182,13 @@ export const codeEnvCommands = {
             }
             const params = codeEnvParams(f);
             const wait = codeEnvWait(f);
-            if (f["if-not-exists"] === true || f["dry-run"] === true) {
+            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) {
+                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",
@@ -224,7 +231,7 @@ export const codeEnvCommands = {
             }
             const expectHash = validateExpectHash(f["expect-hash"]);
             const definitionHash = stableHash(definition);
-            if (f["dry-run"] === true) {
+            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) {
@@ -260,7 +267,7 @@ export const codeEnvCommands = {
             const packages = codeEnvPackageList(f);
             const installCorePackages = parseBooleanOption(f["install-core-packages"], "--install-core-packages");
             const expectHash = validateExpectHash(f["expect-hash"]);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "set-packages",
@@ -275,7 +282,7 @@ export const codeEnvCommands = {
             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] [--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.",
+        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. The package list is replaced wholesale, so an explicitly empty --packages value or an empty --file clears the requested packages.",
         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",
@@ -297,7 +304,7 @@ export const codeEnvCommands = {
                 versionToUpdate,
                 wait,
             };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "update-packages",
@@ -320,7 +327,7 @@ export const codeEnvCommands = {
             const envLang = requireEnvLang(a[0], usage);
             const wait = codeEnvWait(f);
             const envVersion = typeof f["env-version"] === "string" ? f["env-version"] : undefined;
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "update-images",
@@ -350,7 +357,7 @@ export const codeEnvCommands = {
                 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",
@@ -373,7 +380,7 @@ export const codeEnvCommands = {
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             const wait = codeEnvWait(f);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await readIfExists(() => c.codeEnvs.get(envLang, a[1]));
                 if (!current)
                     return skipResult("code-env", a[1], "missing", { envLang, });

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

@@ -1,2 +1,11 @@
 import type { CommandMeta } from "../types.js";
+export declare function sanitizeConnectionSecrets<T>(value: T, secrets?: string[]): T;
+/** Extract exact secret values (e.g. `params.password`) for error scrubbing. */
+export declare function connectionSecretsFromBody(body: unknown): string[];
+/**
+ * DSS validation errors can echo the submitted connection body (including
+ * credentials). Scrub error text and body before it reaches stderr or a
+ * structured failure.
+ */
+export declare function sanitizeConnectionError(error: unknown, secrets: string[]): unknown;
 export declare const connectionCommands: Record<string, CommandMeta>;