dataiku-sdk 3.6.1 → 3.8.0

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

@@ -7,6 +7,8 @@ export interface CommandPayloadSchema {
     dataFileFlag?: boolean;
     contentType?: "application/json" | "text/plain";
     jsonShape?: "object" | "array";
+    /** Precise JSON Schema of the payload, published as the contract's `schemas.input`. */
+    jsonSchema?: Record<string, unknown>;
 }
 export interface CommandFlagChoice {
     oneOf: string[][];

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

@@ -12,6 +12,13 @@ export declare function unsupportedHelpFlag(): UsageError;
 export declare function noCommandError(): UsageError;
 export declare function missingActionError(resource: string, validActions: string[], usage?: string): UsageError;
 export declare function unknownResourceError(resource: string): UsageError;
+/**
+ * Agents rarely mistype; they reuse plausible flags from other commands or
+ * CLIs. When the command is known, the hint is its usage line, which lists
+ * every flag it takes, so one error carries the fix without a discovery round
+ * trip. `--json` gets its own hint: stdout is always JSON.
+ */
+export declare function unknownFlagError(flagLabel: string, resource?: string, action?: string): UsageError;
 export declare function unknownActionError(resource: string, action: string | undefined, validActions: string[], hint?: string): UsageError;
 export declare function requireArgs(args: string[], count: number, usage: string): void;
 export declare function requireNoArgs(args: string[], usage: string): void;

package/dist/src/cli/usage.js

@@ -1,4 +1,4 @@
-import { commandSyntaxTree, syntaxHasFlag, } from "./syntax.js";
+import { commandSyntaxTree, renderNodes, syntaxHasFlag, } from "./syntax.js";
 export const RESOURCE_NAMES = [
     "agent",
     "app",
@@ -35,8 +35,10 @@ export const RESOURCE_NAMES = [
     "analysis",
     "ml-task",
     "saved-model",
+    "mlflow",
     "model-evaluation-store",
     "future",
+    "flow",
     "flow-zone",
     "dataset",
     "recipe",
@@ -64,6 +66,7 @@ const PROJECT_SCOPED_RESOURCES = new Set([
     "knowledge-bank",
     "dataset",
     "llm",
+    "flow",
     "flow-zone",
     "insight",
     "folder",
@@ -72,6 +75,7 @@ const PROJECT_SCOPED_RESOURCES = new Set([
     "notebook",
     "macro",
     "ml-task",
+    "mlflow",
     "model-evaluation-store",
     "recipe",
     "scenario",
@@ -121,6 +125,21 @@ export function missingActionError(resource, validActions, usage) {
 export function unknownResourceError(resource) {
     return new UsageError(`Unknown resource: ${resource}.`, "usage_error", COMMANDS_RUN_HINT, { resource, validResources: RESOURCE_NAMES, });
 }
+/**
+ * Agents rarely mistype; they reuse plausible flags from other commands or
+ * CLIs. When the command is known, the hint is its usage line, which lists
+ * every flag it takes, so one error carries the fix without a discovery round
+ * trip. `--json` gets its own hint: stdout is always JSON.
+ */
+export function unknownFlagError(flagLabel, resource, action) {
+    const command = resource && action ? commandSyntaxTree(resource, action) : undefined;
+    // The envelope already names resource and action; the message stays the flag.
+    const message = `Unknown flag: ${flagLabel}`;
+    if (flagLabel === "--json") {
+        return new UsageError(message, "unknown_flag", "Drop --json: stdout is always one JSON value.");
+    }
+    return new UsageError(message, "unknown_flag", command ? `Usage: ${renderNodes(command)}` : undefined);
+}
 export function unknownActionError(resource, action, validActions, hint) {
     return new UsageError(`Unknown action: ${resource} ${action ?? ""}`.trim(), "usage_error", hint ?? COMMANDS_RUN_HINT, { resource, action, validActions, });
 }

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

@@ -49,7 +49,7 @@ export declare function buildVersionPayload(input: {
 export declare const PACKAGE_ROOT: string | undefined;
 export declare const CLI_VERSION: string;
 export declare const CLI_GIT_REVISION: string | undefined;
-export declare const AGENT_CONTRACT_VERSION = 2;
+export declare const AGENT_CONTRACT_VERSION = 3;
 export declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
-export declare const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v2.json";
+export declare const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v3.json";
 export declare function cliVersionResult(): CliVersionPayload;

package/dist/src/cli/version.js

@@ -204,9 +204,9 @@ export function buildVersionPayload(input) {
 export const PACKAGE_ROOT = findPackageRoot();
 export const CLI_VERSION = packageVersion(PACKAGE_ROOT);
 export const CLI_GIT_REVISION = gitRevision(PACKAGE_ROOT);
-export const AGENT_CONTRACT_VERSION = 2;
+export const AGENT_CONTRACT_VERSION = 3;
 export const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
-export const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v2.json";
+export const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v3.json";
 export function cliVersionResult() {
     // Only code actually loaded from dist/ may report dist provenance; an
     // inherited DSS_LOAD_SOURCE on a source run is ignored.

package/dist/src/cli.js

@@ -2,18 +2,19 @@
 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 { num, seenJsonInputCredentials, unknownJsonInput, } from "./cli/coerce.js";
 import { commands, } from "./cli/commands/index.js";
 import { ambientProjectKey, loadEnvFile, } from "./cli/env.js";
-import { executionMode, FLAG_ALIASES, isNegativeNumberToken, parseArgs, SHORT_FLAGS, VALUE_FLAGS, } from "./cli/flags.js";
+import { executionMode, FLAG_ALIASES, isFlagValueToken, parseArgs, rawPositionals, } 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 { shapeListResult, } from "./cli/list-output.js";
+import { commandFailureExitCode, CommandResultFailure, enqueueCliWarning, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
 import { currentCommandContext, resolveCredentials, resolveLoginCredentials, } from "./cli/runtime.js";
-import { commandUsage, } from "./cli/syntax.js";
-import { COMMANDS_RUN_HINT, inferRequiresProject, missingActionError, noCommandError, requireArgs, RESOURCE_NAMES, unknownActionError, unknownResourceError, UsageError, } from "./cli/usage.js";
+import { commandSyntaxTree, commandUsage, } from "./cli/syntax.js";
+import { COMMANDS_RUN_HINT, inferRequiresProject, missingActionError, noCommandError, requireArgs, RESOURCE_NAMES, unknownActionError, unknownFlagError, 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 { ClientValidationError, DataikuError, dataikuErrorCode, FORBIDDEN_HINT, NOT_FOUND_HINT, } from "./errors.js";
 import { appendCleanupLedgerEntry, findCleanupLedgerBindingViolation, preflightCleanupLedgerPath, readCleanupLedger, reserveCleanupLedgerDssUrl, } from "./utils/cleanup-ledger.js";
 import { canonicalDssUrl, } from "./utils/dss-url.js";
 import { sanitizeSecrets, } from "./utils/secret-sanitize.js";
@@ -26,6 +27,12 @@ function loadCommandRuntime() {
         contract = module;
     });
 }
+// Plan builders (and the command helpers they share with live handlers) load
+// only for --plan; flag validation needs just the registry.
+let planBuildersLoad;
+function loadPlanBuilders() {
+    return planBuildersLoad ??= import("./cli/plans.js");
+}
 // ---------------------------------------------------------------------------
 // Arg parsing
 // ---------------------------------------------------------------------------
@@ -290,9 +297,6 @@ function supportedCommandFlags(entry) {
     }
     return supported;
 }
-function scopedCommandDiscoveryHint(resource, action) {
-    return `Use \`dss commands run --fields ${resource}.${action}\` to list the flags this command supports.`;
-}
 /**
  * Resolve the registry field selectors for `commands run --fields`. Omitting the flag
  * selects the action summary; `--output` exports the full registry, but an explicitly supplied value carrying no selector is a
@@ -315,9 +319,8 @@ function validateSupportedCommandFlags(resource, action, flags) {
         return;
     const supported = supportedCommandFlags(entry);
     for (const flagName of Object.keys(flags)) {
-        if (supported[flagName] !== true) {
-            throw new UsageError(`Unknown flag --${flagName} for ${resource} ${action}`, "unknown_flag", scopedCommandDiscoveryHint(resource, action));
-        }
+        if (supported[flagName] !== true)
+            throw unknownFlagError(`--${flagName}`, resource, action);
     }
     if (executionMode(flags).dryRun && !entry.dryRun) {
         throw new UsageError(`--dry-run is not supported for ${resource} ${action}.`, "unknown_flag", entry.flags.some((flag) => flag.name === "plan")
@@ -339,14 +342,12 @@ function flagIsProvided(flags, name, allowEmpty = false) {
     return allowEmpty || value.length > 0;
 }
 function validateRequiredCommandInputs(resource, action, args, flags, entry) {
-    const argCount = entry.positionalArguments.filter((positional) => positional.required).length;
     const allowEmptyFlags = {};
     for (const flag of entry.flags) {
         if (flag.allowEmptyValue === true)
             allowEmptyFlags[flag.name] = true;
     }
-    if (args.length < argCount)
-        requireArgs(args, argCount, entry.usage);
+    requireEntryPositionals(entry, args);
     for (const flagName of entry.requiredFlags) {
         if (!flagIsProvided(flags, flagName, allowEmptyFlags[flagName] === true)) {
             throw new UsageError(`--${flagName} is required. Usage: ${entry.usage}`, "missing_required_flag");
@@ -367,6 +368,11 @@ function validateRegistryCommandInputs(resource, action, args, flags) {
     validateSupportedCommandFlags(resource, action, flags);
     validateRequiredCommandInputs(resource, action, args, flags, entry);
 }
+function requireEntryPositionals(entry, args) {
+    const argCount = entry.positionalArguments.filter((positional) => positional.required).length;
+    if (args.length < argCount)
+        requireArgs(args, argCount, entry.usage);
+}
 class BatchDryRunValidationComplete extends Error {
     constructor() {
         super("Batch dry-run validation reached client execution.");
@@ -527,8 +533,7 @@ function redactArgv(argv) {
                 else {
                     redacted.push(arg);
                     const next = argv[index + 1];
-                    if (next !== undefined
-                        && (next === "-" || !next.startsWith("-") || isNegativeNumberToken(next))) {
+                    if (next !== undefined && isFlagValueToken(next)) {
                         redacted.push("***");
                         index++;
                     }
@@ -738,7 +743,24 @@ async function runMetaCommand(resource, rawAction, flags) {
             return { action, result: await commandsRunResult(flags), exitCode: 0, };
     }
 }
+const COMMAND_SEARCH_LIMIT = 5;
 async function commandsRunResult(flags) {
+    const query = flags["contains"];
+    if (typeof query === "string") {
+        if (flags["fields"] !== undefined || flags["output"] !== undefined) {
+            throw new UsageError("--contains cannot be combined with --fields or --output.", "usage_error", contract.COMMANDS_USAGE);
+        }
+        const matches = contract.searchCommands(query);
+        if (matches.length > COMMAND_SEARCH_LIMIT) {
+            enqueueCliWarning({
+                code: "results_truncated",
+                shown: COMMAND_SEARCH_LIMIT,
+                total: matches.length,
+                hint: "Add words to --contains to narrow the search.",
+            });
+        }
+        return matches.slice(0, COMMAND_SEARCH_LIMIT);
+    }
     const selectors = commandRegistrySelectors(flags);
     const outputPath = flags["output"];
     if (selectors.length === 0 && typeof outputPath !== "string") {
@@ -990,7 +1012,7 @@ async function runBatch(flags) {
                     throw unknownActionError(resource, action, Object.keys(resourceActions));
                 validateSupportedCommandFlags(resource, action, stepFlags);
                 if (executionMode(stepFlags).plan) {
-                    result = contract.buildMutationPlan(resource, action, meta, positional.slice(2), stepFlags);
+                    result = (await loadPlanBuilders()).buildMutationPlan(resource, action, meta, positional.slice(2), stepFlags);
                 }
                 else {
                     if (!client) {
@@ -1000,6 +1022,8 @@ async function runBatch(flags) {
                     await preflightCleanupLedgerForFlags(client, stepFlags);
                     const stepArgs = positional.slice(2);
                     result = await meta.handler(client, stepArgs, stepFlags);
+                    if (action === "list")
+                        result = shapeListResult(resource, result, stepFlags);
                     await recordCleanupLedgerEntry(client, resource, action, stepArgs, stepFlags, result, projectKey);
                 }
                 const failureExitCode = commandFailureExitCode(result);
@@ -1070,36 +1094,6 @@ function summarizeCleanupFailures(failures) {
             : [];
     }));
 }
-/**
- * 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];
-        if (arg === "--") {
-            positionals.push(...argv.slice(index + 1));
-            break;
-        }
-        if (arg.startsWith("--")) {
-            const name = arg.slice(2).split("=")[0] ?? "";
-            const canonical = FLAG_ALIASES[name] ?? name;
-            if (!arg.includes("=") && VALUE_FLAGS.has(canonical))
-                index++;
-            continue;
-        }
-        if (arg.length === 2 && arg[0] === "-" && arg[1] !== "-") {
-            const long = SHORT_FLAGS[arg[1]];
-            if (long && VALUE_FLAGS.has(long))
-                index++;
-            continue;
-        }
-        positionals.push(arg);
-    }
-    return positionals;
-}
 function rawFlagValue(argv, flagName) {
     const longFlag = `--${flagName}`;
     for (let index = 0; index < argv.length; index++) {
@@ -1173,66 +1167,89 @@ function requestIdFromBody(body) {
 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.
+ * Credential material for redacting a server echo in an error report: the API
+ * key, resolved through the same resolver every command uses (flag → env →
+ * saved), and credential values from the command's JSON input, which DSS
+ * error text can echo back.
  */
 function cliSecretValues() {
+    const inputCredentials = [...seenJsonInputCredentials(),];
     try {
         const { apiKey, } = resolveCredentials(parseArgs(process.argv.slice(2)).flags);
-        return apiKey ? [apiKey,] : [];
+        return apiKey ? [apiKey, ...inputCredentials,] : inputCredentials;
     }
     catch {
-        return [];
+        return inputCredentials;
     }
 }
 /**
- * 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.
+ * Envelope details a DSS failure carries beyond the top-level fields: safe
+ * response metadata (target, elapsed time), a truncated-body marker, and the
+ * retry record only when a retry or timeout actually happened.
+ */
+function dssErrorDetails(err) {
+    const { requestId: _requestId, request_id: _requestIdAlt, errorId: _errorId, ...metadata } = safeResponseMetadata(err.body);
+    return {
+        ...metadata,
+        ...(err.trustedTarget ? { target: err.trustedTarget, } : {}),
+        ...(err.trustedElapsedMs !== undefined ? { elapsedMs: err.trustedElapsedMs, } : {}),
+        ...(err.bodyTruncated ? { bodyTruncated: true, } : {}),
+        ...(err.retry && (err.retry.retries > 0 || err.retry.timedOut) ? { retry: err.retry, } : {}),
+    };
+}
+/**
+ * Bounded, sanitized server diagnostic: the DSS error text (`dssMessage`) and
+ * Java error type (`dssErrorType`) the response body carried. Whitespace
+ * collapses to one line, credential material is redacted, long text
+ * truncates, and the raw body/stack never pass through.
  */
 function dssDiagnosticDetails(err) {
+    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 parsed;
     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, } : {}),
-        };
+        parsed = JSON.parse(err.body);
     }
     catch {
+        // Plain-text or HTML bodies, and the client's own transport detail for
+        // status 0, surface through the bounded summary.
+        const dssMessage = err.body.trim() === "" ? undefined : diagnostic(err.summary);
+        return dssMessage === undefined ? {} : { dssMessage, };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
         return {};
+    const record = parsed;
+    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, } : {}),
+    };
 }
 function isAmbiguousMutationFailure(err, context) {
     if (!(err instanceof DataikuError))
         return false;
+    // DSS definitively refused the operation (e.g. the database rejected the SQL):
+    // nothing took effect, so there is no outcome to verify.
+    if (err.definiteFailure)
+        return false;
     const method = err.retry?.method.toUpperCase();
     if (!method || method === "GET" || method === "HEAD")
         return false;
@@ -1344,48 +1361,46 @@ function buildErrorReport(err, contextOverride) {
             status: err.status,
             retryable: false,
             requestId: err.requestId ?? requestIdFromBody(err.body),
+            // The retry record proves how many times the mutation was dispatched.
             details: {
-                dssCategory: err.category,
-                ...(err.bodyTruncated ? { bodyTruncated: true, } : {}),
-                ...dssDiagnosticDetails(err),
-                statusText: canonicalStatusText(err.status),
                 idempotency: "none",
+                ...dssErrorDetails(err),
+                ...dssDiagnosticDetails(err),
+                ...err.details,
                 ...(err.retry ? { retry: err.retry, } : {}),
             },
             ...context,
         };
     }
     if (err instanceof DataikuError) {
-        const errorMessage = err.category === "not_found" && context.resource
-            ? `Not found: ${context.resource}${context.action ? ` ${context.action}` : ""}`
-                + `${context.projectKey ? ` in project ${context.projectKey}` : ""}`
-                + " — verify the object identifier and project key."
-                + `\nHint: ${err.retryHint}`
-            : err.safeMessage;
-        const safeMetadata = safeResponseMetadata(err.body);
-        if (err.trustedTarget)
-            safeMetadata.target = err.trustedTarget;
-        if (err.trustedElapsedMs !== undefined)
-            safeMetadata.elapsedMs = err.trustedElapsedMs;
-        const safeBody = JSON.stringify(safeMetadata);
+        const { dssMessage, dssErrorType, } = dssDiagnosticDetails(err);
+        const details = {
+            ...dssErrorDetails(err),
+            ...(dssErrorType ? { dssErrorType, } : {}),
+            ...err.details,
+        };
+        // Generic hints name what the command targeted. DSS answers 403 (not
+        // 404) for a project that does not exist: "Failed to read project
+        // permissions". A 403 about something else keeps the generic hint.
+        const inProject = context.projectKey ? ` in project ${context.projectKey}` : "";
+        const projectLevel = dssMessage === undefined || /\bproject\b/i.test(dssMessage);
+        const hint = err.retryHint === FORBIDDEN_HINT && context.projectKey && projectLevel
+            ? `Check that project ${context.projectKey} exists (\`dss project list\`) and that this API key may access it.`
+            : err.retryHint === NOT_FOUND_HINT && context.resource
+                ? `Check the ${context.resource} identifier${inProject}${commandSyntaxTree(context.resource, "list") ? ` (\`dss ${context.resource} list\`)` : ""}.`
+                : err.retryHint;
         return {
             type: "error",
             ok: false,
-            error: errorMessage,
+            error: dssMessage ? `${err.safeMessage}: ${dssMessage}` : err.safeMessage,
             code: dataikuErrorCode(err.category),
             category: "dss",
             exitCode,
-            hint: err.retryHint,
+            hint,
             status: err.status,
             retryable: err.retryable,
             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, } : {}),
-            },
+            ...(Object.keys(details).length > 0 ? { details, } : {}),
             ...context,
         };
     }
@@ -1463,11 +1478,17 @@ async function main() {
     await loadCommandRuntime();
     validateSupportedCommandFlags(resource, action, flags);
     const args = positional.slice(2);
+    // A missing required positional is a usage error with the usage line, never
+    // a handler crash. Required flags stay with the handlers' own validation,
+    // which names the specific alternatives.
+    const registryEntry = cachedCommandRegistry(resource)?.[action];
+    if (registryEntry)
+        requireEntryPositionals(registryEntry, args);
     // 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);
+        const plan = (await loadPlanBuilders()).buildMutationPlan(resource, action, actionMeta, args, flags);
         writeCommandResult(plan);
         return;
     }
@@ -1502,7 +1523,8 @@ async function main() {
     });
     assertCleanupLedgerSupported(resource, action, flags);
     await preflightCleanupLedgerForFlags(client, flags);
-    const result = await actionMeta.handler(client, args, flags);
+    const handled = await actionMeta.handler(client, args, flags);
+    const result = action === "list" ? shapeListResult(resource, handled, flags) : handled;
     await recordCleanupLedgerEntry(client, resource, action, args, flags, result, projectKey);
     const failureExitCode = commandFailureExitCode(result);
     if (failureExitCode !== undefined)

package/dist/src/client.d.ts

@@ -1,47 +1,49 @@
 import { type Static, type TSchema } from "@sinclair/typebox";
-import { AnalysesResource } from "./resources/analyses.js";
-import { ApiDeployerResource } from "./resources/api-deployer.js";
-import { ApiServicesResource } from "./resources/api-services.js";
-import { ApplicationsResource } from "./resources/applications.js";
-import { BundlesResource, ProjectDeployerResource } from "./resources/bundles.js";
-import { CodeEnvsResource } from "./resources/code-envs.js";
-import { ConnectionsResource } from "./resources/connections.js";
-import { ContinuousActivitiesResource } from "./resources/continuous-activities.js";
-import { DashboardsResource } from "./resources/dashboards.js";
-import { DataCollectionsResource } from "./resources/data-collections.js";
-import { DataQualityResource } from "./resources/data-quality.js";
-import { DatasetsResource } from "./resources/datasets.js";
-import { DiscussionsResource } from "./resources/discussions.js";
-import { FlowZonesResource } from "./resources/flow-zones.js";
-import { FoldersResource } from "./resources/folders.js";
-import { FuturesResource } from "./resources/futures.js";
-import { GroupsResource } from "./resources/groups.js";
-import { InsightsResource } from "./resources/insights.js";
-import { JobsResource } from "./resources/jobs.js";
-import { KnowledgeBanksResource } from "./resources/knowledge-banks.js";
-import { LlmsResource } from "./resources/llms.js";
-import { MacrosResource } from "./resources/macros.js";
-import { MeaningsResource } from "./resources/meanings.js";
-import { MetricsResource } from "./resources/metrics.js";
-import { MlTasksResource } from "./resources/ml-tasks.js";
-import { ModelEvaluationStoresResource } from "./resources/model-evaluation-stores.js";
-import { NotebooksResource } from "./resources/notebooks.js";
-import { PluginsResource } from "./resources/plugins.js";
-import { ProjectFoldersResource } from "./resources/project-folders.js";
-import { ProjectGitResource } from "./resources/project-git.js";
-import { ProjectLibraryResource } from "./resources/project-library.js";
-import { ProjectsResource } from "./resources/projects.js";
-import { RecipesResource } from "./resources/recipes.js";
-import { SavedModelsResource } from "./resources/saved-models.js";
-import { ScenariosResource } from "./resources/scenarios.js";
-import { SqlResource } from "./resources/sql.js";
-import { StatisticsResource } from "./resources/statistics.js";
-import { StreamingEndpointsResource } from "./resources/streaming-endpoints.js";
-import { UsersResource } from "./resources/users.js";
-import { VariablesResource } from "./resources/variables.js";
-import { WebappsResource } from "./resources/webapps.js";
-import { WikiResource } from "./resources/wiki.js";
-import { WorkspacesResource } from "./resources/workspaces.js";
+import type { AnalysesResource } from "./resources/analyses.js";
+import type { ApiDeployerResource } from "./resources/api-deployer.js";
+import type { ApiServicesResource } from "./resources/api-services.js";
+import type { ApplicationsResource } from "./resources/applications.js";
+import type { BundlesResource, ProjectDeployerResource } from "./resources/bundles.js";
+import type { CodeEnvsResource } from "./resources/code-envs.js";
+import type { ConnectionsResource } from "./resources/connections.js";
+import type { ContinuousActivitiesResource } from "./resources/continuous-activities.js";
+import type { DashboardsResource } from "./resources/dashboards.js";
+import type { DataCollectionsResource } from "./resources/data-collections.js";
+import type { DataQualityResource } from "./resources/data-quality.js";
+import type { DatasetsResource } from "./resources/datasets.js";
+import type { DiscussionsResource } from "./resources/discussions.js";
+import type { FlowZonesResource } from "./resources/flow-zones.js";
+import type { FlowResource } from "./resources/flow.js";
+import type { FoldersResource } from "./resources/folders.js";
+import type { FuturesResource } from "./resources/futures.js";
+import type { GroupsResource } from "./resources/groups.js";
+import type { InsightsResource } from "./resources/insights.js";
+import type { JobsResource } from "./resources/jobs.js";
+import type { KnowledgeBanksResource } from "./resources/knowledge-banks.js";
+import type { LlmsResource } from "./resources/llms.js";
+import type { MacrosResource } from "./resources/macros.js";
+import type { MeaningsResource } from "./resources/meanings.js";
+import type { MetricsResource } from "./resources/metrics.js";
+import type { MlTasksResource } from "./resources/ml-tasks.js";
+import type { MlflowExtensionResource } from "./resources/mlflow-extension.js";
+import type { ModelEvaluationStoresResource } from "./resources/model-evaluation-stores.js";
+import type { NotebooksResource } from "./resources/notebooks.js";
+import type { PluginsResource } from "./resources/plugins.js";
+import type { ProjectFoldersResource } from "./resources/project-folders.js";
+import type { ProjectGitResource } from "./resources/project-git.js";
+import type { ProjectLibraryResource } from "./resources/project-library.js";
+import type { ProjectsResource } from "./resources/projects.js";
+import type { RecipesResource } from "./resources/recipes.js";
+import type { SavedModelsResource } from "./resources/saved-models.js";
+import type { ScenariosResource } from "./resources/scenarios.js";
+import type { SqlResource } from "./resources/sql.js";
+import type { StatisticsResource } from "./resources/statistics.js";
+import type { StreamingEndpointsResource } from "./resources/streaming-endpoints.js";
+import type { UsersResource } from "./resources/users.js";
+import type { VariablesResource } from "./resources/variables.js";
+import type { WebappsResource } from "./resources/webapps.js";
+import type { WikiResource } from "./resources/wiki.js";
+import type { WorkspacesResource } from "./resources/workspaces.js";
 /** One part of a {@link DataikuClient.uploadForm} multipart/form-data body. */
 export interface UploadFormPart {
     /** Form field name. */
@@ -82,6 +84,8 @@ export interface DataikuGetOptions {
      * server once instead of failing before any transport attempt.
      */
     noRetry?: boolean;
+    /** Extra request headers, e.g. `x-dku-mlflow-project-key` for the MLflow API. */
+    headers?: Record<string, string>;
 }
 export interface DataikuClientTraceEvent {
     type: "trace";
@@ -162,6 +166,8 @@ export declare class DataikuClient {
     private scenariosResource?;
     private foldersResource?;
     private flowZonesResource?;
+    private flowResource?;
+    private mlflowExtensionResource?;
     private variablesResource?;
     private connectionsResource?;
     private codeEnvsResource?;
@@ -206,6 +212,8 @@ export declare class DataikuClient {
     get scenarios(): ScenariosResource;
     get folders(): FoldersResource;
     get flowZones(): FlowZonesResource;
+    get flow(): FlowResource;
+    get mlflowExtension(): MlflowExtensionResource;
     get variables(): VariablesResource;
     get connections(): ConnectionsResource;
     get codeEnvs(): CodeEnvsResource;
@@ -298,6 +306,7 @@ export declare class DataikuClient {
      */
     post<T = unknown>(path: string, body?: unknown, options?: {
         retryMaxAttempts?: number;
+        headers?: Record<string, string>;
     }): Promise<T>;
     /**
      * POST returning the text body, under the same bounded buffering rules as