dataiku-sdk 3.2.0 → 3.4.0

package/dist/src/cli/output.js

@@ -47,14 +47,15 @@ function projectionRecords(result) {
     const items = Array.isArray(result) ? result : [result,];
     return items.filter((item) => item !== null && typeof item === "object" && !Array.isArray(item));
 }
-function warnUnknownProjectionFields(result, fields) {
+function warnUnknownProjectionFields(result, fields, availableFieldNames) {
     const records = projectionRecords(result);
     if (records.length === 0)
         return;
     const unknownFields = fields.filter((field) => !records.some((record) => resolveFieldPath(record, field).found));
     if (unknownFields.length === 0)
         return;
-    const availableFields = [...new Set(records.flatMap((record) => Object.keys(record))),].sort();
+    const availableFields = availableFieldNames?.()
+        ?? [...new Set(records.flatMap((record) => Object.keys(record))),].sort();
     enqueueCliWarning({
         code: "field_projection_missing",
         fields: unknownFields,
@@ -67,8 +68,8 @@ function warnUnknownProjectionFields(result, fields) {
  * element-wise; scalars and string results pass through untouched. Requested keys
  * that are absent become null so every row keeps a stable, predictable shape.
  */
-export function projectResultFields(result, fields) {
-    warnUnknownProjectionFields(result, fields);
+export function projectResultFields(result, fields, availableFieldNames) {
+    warnUnknownProjectionFields(result, fields, availableFieldNames);
     if (Array.isArray(result))
         return result.map((item) => pickResultFields(item, fields));
     return pickResultFields(result, fields);
@@ -98,7 +99,7 @@ export function transientBodyWithTargetContext(body, target, elapsedMs) {
 }
 export function addTransientTargetContext(error, target, elapsedMs) {
     if (error instanceof DataikuError && error.category === "transient") {
-        throw new DataikuError(error.status, error.statusText, transientBodyWithTargetContext(error.body, target, elapsedMs), error.retry, error.requestId, { target, elapsedMs, });
+        throw new DataikuError(error.status, error.statusText, transientBodyWithTargetContext(error.body, target, elapsedMs), error.retry, error.requestId, { target, elapsedMs, bodyTruncated: error.bodyTruncated, });
     }
     throw error;
 }
@@ -106,10 +107,16 @@ export function isFailedWaitResult(result) {
     if (result === null || typeof result !== "object" || Array.isArray(result))
         return false;
     const record = result;
-    return record.success === false
-        && typeof record.elapsedMs === "number"
-        && typeof record.pollCount === "number"
-        && (typeof record.state === "string" || typeof record.outcome === "string");
+    if (record.success !== false)
+        return false;
+    if (typeof record.elapsedMs !== "number" || typeof record.pollCount !== "number")
+        return false;
+    // Job/future wait results name the terminal state as a string; macro wait
+    // results identify themselves by their runnable identity fields with the
+    // poll state attached as an object (or omitted entirely).
+    if (typeof record.state === "string" || typeof record.outcome === "string")
+        return true;
+    return typeof record.runnableType === "string" && typeof record.runId === "string";
 }
 export function isAssertionFailureResult(result) {
     if (result === null || typeof result !== "object" || Array.isArray(result))
@@ -172,7 +179,13 @@ export class CommandResultFailure extends Error {
 export function commandFailureMessage(result) {
     if (isFailedWaitResult(result)) {
         const record = result;
-        const state = typeof record.state === "string" ? record.state : record.outcome;
+        const state = typeof record.state === "string"
+            ? record.state
+            : typeof record.outcome === "string"
+                ? record.outcome
+                : typeof record.timedOut === "boolean"
+                    ? "timed out"
+                    : undefined;
         return `Command completed with failed long-running result${state ? `: ${state}` : ""}.`;
     }
     if (isAssertionFailureResult(result)) {

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

@@ -1,5 +1,6 @@
 import type { StableErrorCode } from "../errors.js";
 export declare const RESOURCE_NAMES: string[];
+export declare function inferRequiresProject(resource: string, action: string, usage: string): boolean;
 export declare class UsageError extends Error {
     readonly code: StableErrorCode;
     readonly hint?: string;

package/dist/src/cli/usage.js

@@ -9,6 +9,15 @@ export const RESOURCE_NAMES = [
     "bundle",
     "project-deployer",
     "project-git",
+    "project-folder",
+    "data-collection",
+    "llm",
+    "knowledge-bank",
+    "macro",
+    "plugin",
+    "user",
+    "group",
+    "project",
     "project-library",
     "streaming-endpoint",
     "continuous-activity",
@@ -44,10 +53,47 @@ export const RESOURCE_NAMES = [
     "commands",
     "fixtures",
     "install-skill",
-    "project",
     "version",
 ]
     .sort();
+const PROJECT_SCOPED_RESOURCES = new Set([
+    "analysis",
+    "data-quality",
+    "dashboard",
+    "knowledge-bank",
+    "dataset",
+    "llm",
+    "flow-zone",
+    "insight",
+    "folder",
+    "fixtures",
+    "job",
+    "notebook",
+    "macro",
+    "ml-task",
+    "model-evaluation-store",
+    "recipe",
+    "scenario",
+    "sql",
+    "variable",
+    "saved-model",
+    "wiki",
+]);
+export function inferRequiresProject(resource, action, usage) {
+    if (resource === "agent" || resource === "auth" || resource === "doctor" || resource === "commands"
+        || resource === "install-skill" || resource === "version")
+        return false;
+    if (resource === "sql" && action === "query")
+        return false;
+    if (PROJECT_SCOPED_RESOURCES.has(resource))
+        return true;
+    // Plugin project scope is optional, not a requirement.
+    if (resource === "plugin")
+        return false;
+    if (resource === "project-git")
+        return !action.startsWith("future-");
+    return usage.includes("--project-key");
+}
 export class UsageError extends Error {
     code;
     hint;

package/dist/src/cli.js

@@ -3,28 +3,26 @@ import * as fs from "node:fs/promises";
 import { homedir, } from "node:os";
 import { resolve, } from "node:path";
 import { num, unknownJsonInput, } from "./cli/coerce.js";
+import { commands, } from "./cli/commands/index.js";
 import { dataikuEnvironmentEnabled, loadEnvFile, } from "./cli/env.js";
 import { executionMode, FLAG_ALIASES, isNegativeNumberToken, parseArgs, SHORT_FLAGS, VALUE_FLAGS, } from "./cli/flags.js";
 import { cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
 import { commandFailureExitCode, CommandResultFailure, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
 import { currentCommandContext, resolveCredentials, resolveLoginCredentials, } from "./cli/runtime.js";
-import { COMMANDS_RUN_HINT, missingActionError, noCommandError, requireArgs, unknownActionError, unknownResourceError, UsageError, } from "./cli/usage.js";
+import { COMMANDS_RUN_HINT, inferRequiresProject, missingActionError, noCommandError, requireArgs, RESOURCE_NAMES, unknownActionError, unknownResourceError, UsageError, } from "./cli/usage.js";
 import { cliVersionResult, } from "./cli/version.js";
 import { getCredentialsPath, } from "./config.js";
 import { canonicalStatusText, ClientValidationError, DataikuError, dataikuErrorCode, } from "./errors.js";
 import { appendCleanupLedgerEntry, findCleanupLedgerBindingViolation, preflightCleanupLedgerPath, readCleanupLedger, reserveCleanupLedgerDssUrl, } from "./utils/cleanup-ledger.js";
 import { canonicalDssUrl, } from "./utils/dss-url.js";
-let commands;
+import { sanitizeSecrets, } from "./utils/secret-sanitize.js";
 let contract;
 let commandRuntimeLoad;
-// Dispatch and error reporting initialize these bindings before synchronous validation.
+// Command definitions are resource-lazy; full contract metadata loads only
+// after a valid action is selected or explicit discovery is requested.
 function loadCommandRuntime() {
-    return commandRuntimeLoad ??= Promise.all([
-        import("./cli/commands/index.js"),
-        import("./cli/contract.js"),
-    ]).then(([commandModule, contractModule,]) => {
-        commands = commandModule.commands;
-        contract = contractModule;
+    return commandRuntimeLoad ??= import("./cli/contract.js").then((module) => {
+        contract = module;
     });
 }
 // ---------------------------------------------------------------------------
@@ -279,6 +277,8 @@ const META_COMMAND_RESOURCES = {
 };
 const commandRegistryCache = new Map();
 function cachedCommandRegistry(resource) {
+    if (!contract)
+        return undefined;
     if (!commandRegistryCache.has(resource)) {
         commandRegistryCache.set(resource, contract.buildCommandRegistry(resource)[resource]);
     }
@@ -415,11 +415,21 @@ const batchDryRunClientHandler = {
         throw new BatchDryRunValidationComplete();
     },
 };
-const batchDryRunClient = new Proxy(batchDryRunClientTarget, batchDryRunClientHandler);
+const batchDryRunResource = new Proxy(batchDryRunClientTarget, batchDryRunClientHandler);
+let batchDryRunClient;
 async function validateDryRunHandlerPreconditions(handler, args, flags) {
     const readsFromStdin = flags["stdin"] === true || flags["sql"] === "-";
     if (readsFromStdin)
         return;
+    if (!batchDryRunClient) {
+        const { DataikuClient, } = await import("./client.js");
+        batchDryRunClient = new Proxy(new DataikuClient({
+            url: "http://dry-run.invalid",
+            apiKey: "dry-run-validation",
+        }), {
+            get: (_target, property) => property === "then" ? undefined : batchDryRunResource,
+        });
+    }
     try {
         await handler(batchDryRunClient, args, flags);
     }
@@ -760,9 +770,8 @@ function batchPlan(flags) {
     });
 }
 async function runMetaCommand(resource, action, flags) {
-    if (resource !== "version")
-        await loadCommandRuntime();
     if (resource === "doctor") {
+        await loadCommandRuntime();
         if (action !== undefined && action !== "run") {
             throw unknownActionError("doctor", action, ["run",]);
         }
@@ -772,6 +781,7 @@ async function runMetaCommand(resource, action, flags) {
         return { action: "run", result, exitCode, };
     }
     if (resource === "auth") {
+        await loadCommandRuntime();
         const validActions = Object.keys(contract.AUTH_ACTIONS);
         if (!action) {
             throw missingActionError("auth", validActions, "dss auth login --url URL --api-key KEY");
@@ -787,6 +797,7 @@ async function runMetaCommand(resource, action, flags) {
         return { action, result: await authMeta.handler(flags), exitCode: 0, };
     }
     if (resource === "install-skill") {
+        await loadCommandRuntime();
         if (action !== undefined && action !== "run") {
             throw unknownActionError("install-skill", action, ["run",]);
         }
@@ -794,6 +805,7 @@ async function runMetaCommand(resource, action, flags) {
         return { action: "run", result: await runInstallSkill(flags), exitCode: 0, };
     }
     if (resource === "agent") {
+        await loadCommandRuntime();
         if (!action)
             throw missingActionError("agent", ["contract",], contract.AGENT_CONTRACT_USAGE);
         currentCommandContext.action = action;
@@ -802,6 +814,7 @@ async function runMetaCommand(resource, action, flags) {
         return { action, result: contract.buildAgentContract(), exitCode: 0, };
     }
     if (resource === "commands") {
+        await loadCommandRuntime();
         if (!action)
             throw missingActionError("commands", ["run",], contract.COMMANDS_USAGE);
         currentCommandContext.action = action;
@@ -809,24 +822,28 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("commands", action, ["run",]);
         validateSupportedCommandFlags("commands", "run", flags);
         const selectors = commandRegistrySelectors(flags);
-        const registry = contract.buildCommandRegistry();
+        const outputPath = flags["output"];
+        if (selectors.length === 0 && typeof outputPath !== "string") {
+            return { action, result: contract.commandActionSummary(), exitCode: 0, };
+        }
+        const registry = selectors.length === 0 ? contract.buildCommandRegistry() : {};
         for (const selector of selectors) {
             const selectorParts = selector.split(".");
             if (selectorParts.some((part) => part.length === 0)) {
                 throw new UsageError(`Invalid --fields selector: ${selector}. Expected RESOURCE or RESOURCE.ACTION[.FIELD...].`, "usage_error", contract.COMMANDS_USAGE, { selector, });
             }
             const [selectedResource, selectedAction,] = selectorParts;
-            const resourceActions = registry[selectedResource];
+            const resourceActions = cachedCommandRegistry(selectedResource);
             if (!resourceActions)
                 throw unknownResourceError(selectedResource);
+            registry[selectedResource] = resourceActions;
             if (selectedAction && !resourceActions[selectedAction]) {
                 throw unknownActionError(selectedResource, selectedAction, Object.keys(resourceActions));
             }
         }
-        const outputPath = flags["output"];
         const selectedRegistry = selectors.length === 0
             ? registry
-            : projectResultFields(registry, selectors);
+            : projectResultFields(registry, selectors, () => Object.keys(contract.commandActionSummary()).sort());
         if (typeof outputPath === "string") {
             const exported = selectedRegistry;
             await fs.writeFile(outputPath, `${JSON.stringify(exported)}\n`, "utf-8");
@@ -834,7 +851,7 @@ async function runMetaCommand(resource, action, flags) {
         }
         return {
             action,
-            result: selectors.length === 0 ? contract.commandActionSummary(registry) : selectedRegistry,
+            result: selectedRegistry,
             exitCode: 0,
         };
     }
@@ -846,6 +863,7 @@ async function runMetaCommand(resource, action, flags) {
         return { action: "run", result: cliVersionResult(), exitCode: 0, };
     }
     if (resource === "cleanup") {
+        await loadCommandRuntime();
         if (action !== undefined && action !== "run") {
             throw unknownActionError("cleanup", action, ["run",]);
         }
@@ -857,6 +875,7 @@ async function runMetaCommand(resource, action, flags) {
         return { action: "run", result, exitCode, };
     }
     if (resource === "fixtures") {
+        await loadCommandRuntime();
         if (action !== undefined && action !== "run") {
             throw unknownActionError("fixtures", action, ["run",]);
         }
@@ -865,6 +884,7 @@ async function runMetaCommand(resource, action, flags) {
         return { action: "run", result: await runFixtures(flags), exitCode: 0, };
     }
     if (resource === "batch") {
+        await loadCommandRuntime();
         if (action !== undefined && action !== "run") {
             throw unknownActionError("batch", action, ["run",]);
         }
@@ -1181,27 +1201,12 @@ function summarizeCleanupFailures(failures) {
             : [];
     }));
 }
-function rawFlagValue(argv, flagName) {
-    const longFlag = `--${flagName}`;
-    for (let index = 0; index < argv.length; index++) {
-        const arg = argv[index];
-        if (arg === longFlag) {
-            const next = argv[index + 1];
-            return next && !next.startsWith("-") ? next : undefined;
-        }
-        if (arg.startsWith(`${longFlag}=`))
-            return arg.slice(longFlag.length + 1);
-    }
-    return undefined;
-}
-function commandIsProjectScoped(resource, action) {
-    if (!resource)
-        return false;
-    const usage = commands[resource]?.[action ?? ""]?.usage ?? "";
-    return contract.inferRequiresProject(resource, action ?? "", usage);
-}
-function rawCommandContext() {
-    const argv = process.argv.slice(2);
+/**
+ * Positional arguments scanned with the same flag grammar as `parseArgs`, so
+ * error reporting can recover the invoked resource/action without depending
+ * on the command registry being loaded.
+ */
+function rawPositionals(argv) {
     const positionals = [];
     for (let index = 0; index < argv.length; index++) {
         const arg = argv[index];
@@ -1224,6 +1229,30 @@ function rawCommandContext() {
         }
         positionals.push(arg);
     }
+    return positionals;
+}
+function rawFlagValue(argv, flagName) {
+    const longFlag = `--${flagName}`;
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === longFlag) {
+            const next = argv[index + 1];
+            return next && !next.startsWith("-") ? next : undefined;
+        }
+        if (arg.startsWith(`${longFlag}=`))
+            return arg.slice(longFlag.length + 1);
+    }
+    return undefined;
+}
+function commandIsProjectScoped(resource, action) {
+    if (!resource)
+        return false;
+    const usage = commands[resource]?.[action ?? ""]?.usage ?? "";
+    return inferRequiresProject(resource, action ?? "", usage);
+}
+function rawCommandContext() {
+    const argv = process.argv.slice(2);
+    const positionals = rawPositionals(argv);
     const resource = currentCommandContext.resource ?? positionals[0];
     const action = currentCommandContext.action ?? positionals[1];
     const explicitProjectKey = rawFlagValue(argv, "project-key") ?? rawFlagValue(argv, "project");
@@ -1274,6 +1303,67 @@ function requestIdFromBody(body) {
     }
     return undefined;
 }
+/** DSS diagnostic fields, in the resource layer's read order (detailedMessage → message → errorMessage). */
+const DSS_DIAGNOSTIC_MESSAGE_FIELDS = ["detailedMessage", "message", "errorMessage",];
+const MAX_DSS_DIAGNOSTIC_LENGTH = 300;
+/**
+ * Credential material for redacting a server echo in a receipt: resolved
+ * through the same resolver every command uses (flag → env → saved), so the
+ * report path never grows a second credential-precedence convention.
+ */
+function cliSecretValues() {
+    try {
+        const { apiKey, } = resolveCredentials(parseArgs(process.argv.slice(2)).flags);
+        return apiKey ? [apiKey,] : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Bounded, sanitized server diagnostic preserved on an ambiguous mutation
+ * envelope (`dssMessage`/`dssErrorType`, next to the existing `dssCategory`):
+ * the DSS error text and Java error type the response body carried, so the
+ * receipt explains why the server failed while the mutation outcome stays
+ * unknown. Whitespace collapses to one line, credential material is redacted,
+ * long text truncates, and the raw body/stack never pass through.
+ */
+function dssDiagnosticDetails(err) {
+    try {
+        const parsed = JSON.parse(err.body);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const record = parsed;
+        let secrets;
+        const diagnostic = (value) => {
+            if (typeof value !== "string" || value.trim() === "")
+                return undefined;
+            secrets ??= cliSecretValues();
+            const sanitized = sanitizeSecrets(value.replace(/\s+/g, " ").trim(), {
+                sensitiveKeys: {},
+                secrets,
+                redactUrlUserinfo: true,
+            });
+            return sanitized.length > MAX_DSS_DIAGNOSTIC_LENGTH
+                ? `${sanitized.slice(0, MAX_DSS_DIAGNOSTIC_LENGTH)}…`
+                : sanitized;
+        };
+        let message;
+        for (const field of DSS_DIAGNOSTIC_MESSAGE_FIELDS) {
+            message = diagnostic(record[field]);
+            if (message !== undefined)
+                break;
+        }
+        const errorType = diagnostic(record["errorType"]);
+        return {
+            ...(message !== undefined ? { dssMessage: message, } : {}),
+            ...(errorType !== undefined ? { dssErrorType: errorType, } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
 const MISSING_PROJECT_KEY_ERROR_PREFIX = "projectKey is required";
 function isAmbiguousMutationFailure(err, context) {
     if (!(err instanceof DataikuError))
@@ -1384,6 +1474,8 @@ function buildErrorReport(err) {
             requestId: err.requestId ?? requestIdFromBody(err.body),
             details: {
                 dssCategory: err.category,
+                ...(err.bodyTruncated ? { bodyTruncated: true, } : {}),
+                ...dssDiagnosticDetails(err),
                 statusText: canonicalStatusText(err.status),
                 idempotency: "none",
                 ...(err.retry ? { retry: err.retry, } : {}),
@@ -1417,6 +1509,7 @@ function buildErrorReport(err) {
             requestId: err.requestId ?? requestIdFromBody(err.body),
             details: {
                 dssCategory: err.category,
+                ...(err.bodyTruncated ? { bodyTruncated: true, } : {}),
                 statusText: canonicalStatusText(err.status),
                 body: safeBody,
                 ...(err.retry ? { retry: err.retry, } : {}),
@@ -1451,6 +1544,14 @@ function writeErrorReport(err) {
     flushCliWarnings();
     process.stdout.write(`${JSON.stringify(buildErrorReport(err))}\n`);
 }
+/** Only ambiguous mutation failures require full contract metadata. */
+function errorReportNeedsCommandRuntime(err) {
+    if (contract || !(err instanceof DataikuError))
+        return false;
+    const method = err.retry?.method.toUpperCase();
+    return !!method && method !== "GET" && method !== "HEAD"
+        && (err.status === 0 || err.status >= 500);
+}
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -1489,7 +1590,8 @@ async function main() {
             process.exitCode = metaCommand.exitCode;
         return;
     }
-    if (!commands[resource])
+    // Resource and action recovery require only this resource's definitions.
+    if (!RESOURCE_NAMES.includes(resource))
         throw unknownResourceError(resource);
     const resourceActions = commands[resource];
     if (positional.length === 1) {
@@ -1500,8 +1602,12 @@ async function main() {
     const actionMeta = resourceActions[action];
     if (!actionMeta)
         throw unknownActionError(resource, action, Object.keys(resourceActions));
+    await loadCommandRuntime();
     validateSupportedCommandFlags(resource, action, flags);
     const args = positional.slice(2);
+    // Command-local validation runs for live, --plan, and --dry-run alike, so a
+    // bad identifier is a usage error before any plan is built or request made.
+    actionMeta.validate?.(args, flags);
     if (executionMode(flags).plan) {
         const plan = contract.buildMutationPlan(resource, action, actionMeta, args, flags);
         writeCommandResult(plan);
@@ -1515,7 +1621,6 @@ async function main() {
         writeCommandResult(result);
         return;
     }
-    actionMeta.validate?.(args, flags);
     const { url, apiKey, projectKey, tlsRejectUnauthorized, caCertPath, } = resolveCredentials(flags);
     currentCommandContext.projectKey = projectKey;
     if (!url) {
@@ -1547,7 +1652,8 @@ async function main() {
     writeCommandResult(result);
 }
 main().catch(async (err) => {
-    await loadCommandRuntime();
+    if (errorReportNeedsCommandRuntime(err))
+        await loadCommandRuntime();
     writeErrorReport(err);
     process.exitCode = errorExitCode(err);
 });