dataiku-sdk 3.2.0 → 3.3.0

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

@@ -3,18 +3,18 @@ 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.";
@@ -52,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(),
@@ -113,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);
@@ -352,38 +389,42 @@ 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: executionMode(f).dryRun,
@@ -392,10 +433,11 @@ export const appCommands = {
             }, 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": {

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

@@ -23,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",

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

@@ -42,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;
 }
@@ -276,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",

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>;

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

@@ -1,4 +1,81 @@
-import { UsageError, } from "../usage.js";
+import { sanitizeErrorSecrets, sanitizeSecrets, } from "../../utils/secret-sanitize.js";
+import { requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
+import { readIfExists, skipResult, } from "../output.js";
+import { requireArgs, UsageError, } from "../usage.js";
+/**
+ * Keys of a connection payload that carry credentials. CLI plan/error/output
+ * layers replace these with `[redacted]`; the SDK resource layer forwards
+ * values verbatim to DSS (over TLS) and returns server responses unmodified.
+ * Keys are matched after stripping `-`/`_` and lowercasing. The connection
+ * policy is deliberately broader than the user/project-git tables.
+ */
+const SENSITIVE_CONNECTION_KEYS = {
+    accesstoken: true,
+    accesskey: true,
+    apikey: true,
+    apitoken: true,
+    apisecret: true,
+    authorization: true,
+    clientsecret: true,
+    credential: true,
+    credentials: true,
+    password: true,
+    privatekey: true,
+    refreshtoken: true,
+    secret: true,
+    secretkey: true,
+    sharesecret: true,
+    token: true,
+};
+export function sanitizeConnectionSecrets(value, secrets = []) {
+    return sanitizeSecrets(value, { sensitiveKeys: SENSITIVE_CONNECTION_KEYS, secrets, });
+}
+/** Extract exact secret values (e.g. `params.password`) for error scrubbing. */
+export function connectionSecretsFromBody(body) {
+    if (body === undefined || body === null || typeof body !== "object" || Array.isArray(body)) {
+        return [];
+    }
+    const found = [];
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            value.forEach(visit);
+            return;
+        }
+        if (value !== null && typeof value === "object") {
+            for (const [key, item,] of Object.entries(value)) {
+                const normalizedKey = key.replace(/[-_]/g, "").toLowerCase();
+                if (SENSITIVE_CONNECTION_KEYS[normalizedKey] === true && typeof item === "string") {
+                    found.push(item);
+                }
+                else {
+                    visit(item);
+                }
+            }
+        }
+    };
+    visit(body);
+    return found;
+}
+/**
+ * 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 function sanitizeConnectionError(error, secrets) {
+    return sanitizeErrorSecrets(error, { sensitiveKeys: SENSITIVE_CONNECTION_KEYS, secrets, });
+}
+function requiredConnectionJson(flags, usage) {
+    return requiredJsonInput(flags, `--data, --data-file, or --stdin is required (connection definition). Usage: ${usage}`);
+}
+/** Connection identifiers must be non-empty before any request or dry-run preview. */
+function requireConnectionName(value, usage) {
+    const trimmed = value?.trim() ?? "";
+    if (trimmed.length === 0) {
+        throw new UsageError(`connection name must be a non-empty string.\nUsage: ${usage}`, "validation_failed");
+    }
+    return trimmed;
+}
 export const connectionCommands = {
     list: {
         handler: (c, _a, f) => c.connections.list({
@@ -17,6 +94,118 @@ export const connectionCommands = {
         description: "List connections with inferred types and metadata.",
         examples: ["dss connection infer", "dss connection infer --mode rich",],
     },
+    get: {
+        handler: async (c, a) => {
+            const usage = "dss connection get <name>";
+            requireArgs(a, 1, usage);
+            const details = await c.connections.adminGet(requireConnectionName(a[0], usage));
+            return sanitizeConnectionSecrets(details);
+        },
+        usage: "dss connection get <name>",
+        description: "Get a connection by name (admin). Credential-bearing params (e.g. params.password) are redacted in output.",
+        examples: ["dss connection get postgres",],
+    },
+    create: {
+        handler: async (c, _a, f) => {
+            const usage = "dss connection create (--data JSON|--data-file PATH|--stdin)";
+            const body = requiredConnectionJson(f, usage);
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "create",
+                    resource: "connection",
+                    connectionName: typeof body.name === "string" ? body.name : undefined,
+                    method: "POST",
+                    endpoint: "/public/api/admin/connections",
+                    payload: sanitizeConnectionSecrets(body),
+                };
+            }
+            try {
+                return await c.connections.adminCreate(body);
+            }
+            catch (error) {
+                throw sanitizeConnectionError(error, connectionSecretsFromBody(body));
+            }
+        },
+        usage: "dss connection create (--data JSON|--data-file PATH|--stdin) [--dry-run]",
+        description: 'Create a connection (admin). Body is the Connection definition, e.g. {"name":"new-connection","type":"PostgreSQL","params":{"host":"...","user":"...","password":"..."}}. Secrets are never echoed in errors or output.',
+        examples: [
+            `dss connection create --data '{"name":"new-connection","type":"PostgreSQL","params":{"db":"dbname","user":"myuser","password":"s3cret"}}'`,
+        ],
+    },
+    update: {
+        handler: async (c, a, f) => {
+            const usage = "dss connection update <name> (--data JSON|--data-file PATH|--stdin) [--dry-run]";
+            requireArgs(a, 1, usage);
+            const name = requireConnectionName(a[0], usage);
+            const body = requiredConnectionJson(f, usage);
+            const secrets = connectionSecretsFromBody(body);
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "update",
+                    resource: "connection",
+                    name,
+                    method: "PUT",
+                    endpoint: `/public/api/admin/connections/${encodeURIComponent(name)}`,
+                    payload: sanitizeConnectionSecrets(body),
+                    note: "PUT replaces the whole Connection object; the body must come from `dss connection get`. No GET was issued in dry-run.",
+                };
+            }
+            try {
+                const result = await c.connections.adminUpdate(name, body);
+                return sanitizeConnectionSecrets(result, secrets);
+            }
+            catch (error) {
+                throw sanitizeConnectionError(error, secrets);
+            }
+        },
+        usage: "dss connection update <name> (--data JSON|--data-file PATH|--stdin) [--dry-run]",
+        description: "Update a connection (admin). The body MUST be the Connection object obtained from `dss connection get` (PUT semantics); type and name cannot be modified. Use --dry-run to preview the merged result without writing.",
+        examples: [
+            `dss connection update postgres --data '{"type":"PostgreSQL","name":"postgres","allowWrite":true,"params":{"db":"dbname","user":"myuser","password":"s3cret"}}'`,
+        ],
+    },
+    delete: {
+        handler: async (c, a, f) => {
+            const usage = "dss connection delete <name> [--if-exists] [--dry-run]";
+            requireArgs(a, 1, usage);
+            const name = requireConnectionName(a[0], usage);
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "delete",
+                    resource: "connection",
+                    name,
+                    method: "DELETE",
+                    endpoint: `/public/api/admin/connections/${encodeURIComponent(name)}`,
+                    ...(f["if-exists"] === true
+                        ? { note: "Existence not checked in dry-run; live --if-exists issues a GET probe first.", }
+                        : {}),
+                };
+            }
+            if (f["if-exists"] === true) {
+                const current = await readIfExists(() => c.connections.adminGet(name));
+                if (!current)
+                    return skipResult("connection", name, "missing");
+            }
+            return c.connections.adminDelete(name);
+        },
+        usage: "dss connection delete <name> [--if-exists] [--dry-run]",
+        description: "Delete a connection (admin). Destructive: per the DSS docs no check is performed that the connection is not in use by a dataset.",
+        examples: ["dss connection delete old-conn", "dss connection delete old-conn --if-exists",],
+    },
+    test: {
+        handler: async (c, a) => {
+            const usage = "dss connection test <name>";
+            requireArgs(a, 1, usage);
+            const result = await c.connections.adminTest(requireConnectionName(a[0], usage));
+            return sanitizeConnectionSecrets(result);
+        },
+        usage: "dss connection test <name>",
+        description: "Test whether a connection is available (uses the same GET /connections/{name}/test route as the official Python client; returns connectionOK, errors when testing is unsupported for the type). Credential-bearing fields are redacted in output.",
+        examples: ["dss connection test postgres",],
+    },
     schemas: {
         handler: (c, _a, f) => {
             const connection = f["connection"];
@@ -51,4 +240,81 @@ export const connectionCommands = {
             "dss connection tables --connection ATHENA_CONN --schema analytics --project-key MYPROJ",
         ],
     },
+    "prepare-import": {
+        handler: async (c, _a, f) => {
+            const usage = "dss connection prepare-import (--data JSON|--data-file PATH|--stdin) [--project-key KEY]";
+            const body = requiredJsonInput(f, `--data, --data-file, or --stdin is required (tables-import request). Usage: ${usage}`);
+            const keys = body["keys"];
+            if (!Array.isArray(keys) || keys.length === 0) {
+                throw new UsageError('Body must include a non-empty keys array (e.g. [{"connectionName":"postgres","name":"my_table"}]).', "validation_failed", `Usage: ${usage}`);
+            }
+            for (const key of keys) {
+                const k = key;
+                const connectionName = k["connectionName"];
+                const name = k["name"];
+                if (typeof connectionName !== "string" || connectionName.trim().length === 0
+                    || typeof name !== "string" || name.trim().length === 0) {
+                    throw new UsageError('Each key must carry non-empty string connectionName and name (e.g. {"connectionName":"postgres","name":"my_table"}).', "validation_failed", `Usage: ${usage}`);
+                }
+            }
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "prepare-import",
+                    resource: "connection",
+                    keyCount: keys.length,
+                    method: "POST",
+                    endpoint: `/public/api/projects/${encodeURIComponent(c.resolveProjectKey(f["project-key"]))}/datasets/tables-import/actions/prepare-from-keys`,
+                    payload: { keys, },
+                };
+            }
+            return c.connections.prepareTablesImport({
+                keys: keys,
+                projectKey: f["project-key"],
+            });
+        },
+        usage: "dss connection prepare-import (--data JSON|--data-file PATH|--stdin) [--project-key KEY] [--dry-run]",
+        description: 'Prepare the import of selected SQL or Hive tables (WRITE_CONF). Body is {"keys":[...]} per the DSS tables-import docs. Returns a DSS future; poll with `dss future wait <jobId>`.',
+        examples: [
+            `dss connection prepare-import --data '{"keys":[{"connectionName":"postgres","name":"my_table"}]}' --project-key MYPROJ`,
+        ],
+    },
+    "execute-import": {
+        handler: async (c, _a, f) => {
+            const usage = "dss connection execute-import (--data JSON|--data-file PATH|--stdin) [--project-key KEY]";
+            const body = requiredJsonInput(f, `--data, --data-file, or --stdin is required (tables-import request). Usage: ${usage}`);
+            const sql = body["sqlImportCandidates"];
+            const hive = body["hiveImportCandidates"];
+            const hasSql = Array.isArray(sql) && sql.length > 0;
+            const hasHive = Array.isArray(hive) && hive.length > 0;
+            if (!hasSql && !hasHive) {
+                throw new UsageError('Body must include sqlImportCandidates and/or hiveImportCandidates arrays (e.g. {"sqlImportCandidates":[{"connectionName":"pgsql","table":"t","checked":false,"datasetName":"imported","existingDatasetsNames":[]}]}).', "validation_failed", `Usage: ${usage}`);
+            }
+            if (executionMode(f).dryRun) {
+                return {
+                    dryRun: true,
+                    action: "execute-import",
+                    resource: "connection",
+                    sqlCandidates: hasSql ? sql.length : undefined,
+                    hiveCandidates: hasHive ? hive.length : undefined,
+                    method: "POST",
+                    endpoint: `/public/api/projects/${encodeURIComponent(c.resolveProjectKey(f["project-key"]))}/datasets/tables-import/actions/execute-from-candidates`,
+                    payload: {
+                        ...(hasSql ? { sqlImportCandidates: sql, } : {}),
+                        ...(hasHive ? { hiveImportCandidates: hive, } : {}),
+                    },
+                };
+            }
+            return c.connections.executeTablesImport({
+                sqlImportCandidates: hasSql ? sql : undefined,
+                hiveImportCandidates: hasHive ? hive : undefined,
+                projectKey: f["project-key"],
+            });
+        },
+        usage: "dss connection execute-import (--data JSON|--data-file PATH|--stdin) [--project-key KEY] [--dry-run]",
+        description: "Perform an import from SQL/Hive table candidates (WRITE_CONF). Body carries sqlImportCandidates and/or hiveImportCandidates per the DSS tables-import docs. Returns a DSS future.",
+        examples: [
+            `dss connection execute-import --data '{"sqlImportCandidates":[{"connectionName":"pgsql","table":"my_table","checked":false,"datasetName":"imported_from_db","existingDatasetsNames":[]}]}' --project-key MYPROJ`,
+        ],
+    },
 };

package/dist/src/cli/commands/data-collection.d.ts

@@ -0,0 +1,2 @@
+import type { CommandMeta } from "../types.js";
+export declare const dataCollectionCommands: Record<string, CommandMeta>;