dataiku-sdk 3.0.0 → 3.2.0

package/dist/src/cli.js

@@ -1,22 +1,32 @@
 #!/usr/bin/env node
 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 { AGENT_CONTRACT_USAGE, AUTH_ACTIONS, BATCH_EXAMPLE_PAYLOAD, BATCH_HINT, BATCH_PLAN_EXIT_CODES, BATCH_USAGE, buildAgentContract, buildCommandRegistry, buildMutationPlan, CLEANUP_USAGE, commandActionSummary, COMMANDS_USAGE, inferRequiresProject, isAllowedCleanupAction, supportsCleanupLedger, } from "./cli/contract.js";
-import { runDoctor, runFixtures, } from "./cli/doctor.js";
 import { dataikuEnvironmentEnabled, loadEnvFile, } from "./cli/env.js";
-import { FLAG_ALIASES, isNegativeNumberToken, parseArgs, SHORT_FLAGS, VALUE_FLAGS, } from "./cli/flags.js";
+import { executionMode, FLAG_ALIASES, isNegativeNumberToken, parseArgs, SHORT_FLAGS, VALUE_FLAGS, } from "./cli/flags.js";
 import { cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
-import { commandFailureExitCode, commandFailureMessage, CommandResultFailure, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
-import { currentCommandContext, resolveCredentials, resolveTlsSettings, } from "./cli/runtime.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 { cliVersionResult, } from "./cli/version.js";
-import { DataikuClient, } from "./client.js";
 import { getCredentialsPath, } from "./config.js";
 import { canonicalStatusText, ClientValidationError, DataikuError, dataikuErrorCode, } from "./errors.js";
-import { AGENTS, detectAgents, findWorkspaceRoot, installSkill, planSkillInstalls, } from "./skill.js";
 import { appendCleanupLedgerEntry, findCleanupLedgerBindingViolation, preflightCleanupLedgerPath, readCleanupLedger, reserveCleanupLedgerDssUrl, } from "./utils/cleanup-ledger.js";
 import { canonicalDssUrl, } from "./utils/dss-url.js";
+let commands;
+let contract;
+let commandRuntimeLoad;
+// Dispatch and error reporting initialize these bindings before synchronous validation.
+function loadCommandRuntime() {
+    return commandRuntimeLoad ??= Promise.all([
+        import("./cli/commands/index.js"),
+        import("./cli/contract.js"),
+    ]).then(([commandModule, contractModule,]) => {
+        commands = commandModule.commands;
+        contract = contractModule;
+    });
+}
 // ---------------------------------------------------------------------------
 // Arg parsing
 // ---------------------------------------------------------------------------
@@ -60,7 +70,7 @@ function findUnboundLifecycleCleanup(entries) {
 async function runCleanup(flags) {
     const filePath = flags["file"];
     if (typeof filePath !== "string" || filePath.trim().length === 0) {
-        throw new UsageError(`--file is required. Usage: ${CLEANUP_USAGE}`);
+        throw new UsageError(`--file is required. Usage: ${contract.CLEANUP_USAGE}`);
     }
     let entries;
     try {
@@ -95,6 +105,7 @@ async function runCleanup(flags) {
     }
     const requestTimeoutMs = num(flags["request-timeout"], "--request-timeout");
     const retryMaxAttempts = num(flags["retries"], "--retries");
+    const { DataikuClient, } = await import("./client.js");
     const client = new DataikuClient({
         url,
         apiKey,
@@ -153,7 +164,12 @@ async function runCleanup(flags) {
         try {
             const parsed = parseArgs(entry.cleanup.argv);
             const [resource, action, ...args] = parsed.positional;
-            if (!resource || !action || !isAllowedCleanupAction(resource, action)
+            Object.assign(currentCommandContext, {
+                resource,
+                action,
+                projectKey: parsed.flags["project-key"],
+            });
+            if (!resource || !action || !contract.isAllowedCleanupAction(resource, action)
                 || !commands[resource]?.[action]) {
                 throw new UsageError(`Invalid cleanup argv: ${entry.cleanup.argv.join(" ")}`);
             }
@@ -173,13 +189,18 @@ async function runCleanup(flags) {
                 const failure = {
                     index,
                     cleanup: entry.cleanup,
-                    error: commandFailureMessage(result),
-                    result,
+                    error: buildErrorReport(new CommandResultFailure(result, 4)),
                 };
                 failures.push(failure);
                 if (flags["continue-on-error"] !== true) {
                     return {
-                        result: { applied: true, steps, results: applied, failures, },
+                        result: {
+                            applied: true,
+                            steps,
+                            results: applied,
+                            failures,
+                            ...summarizeCleanupFailures(failures),
+                        },
                         exitCode: 2,
                     };
                 }
@@ -191,29 +212,41 @@ async function runCleanup(flags) {
             const failure = {
                 index,
                 cleanup: entry.cleanup,
-                error: error instanceof Error ? error.message : String(error),
+                error: buildErrorReport(error),
             };
             failures.push(failure);
             if (flags["continue-on-error"] !== true) {
                 return {
-                    result: { applied: true, steps, results: applied, failures, },
+                    result: {
+                        applied: true,
+                        steps,
+                        results: applied,
+                        failures,
+                        ...summarizeCleanupFailures(failures),
+                    },
                     exitCode: 2,
                 };
             }
         }
     }
     return {
-        result: { applied: true, steps, results: applied, failures, },
+        result: {
+            applied: true,
+            steps,
+            results: applied,
+            failures,
+            ...summarizeCleanupFailures(failures),
+        },
         exitCode: failures.length > 0 ? 2 : 0,
     };
 }
 function parseBatchSteps(payload) {
     if (!Array.isArray(payload)) {
-        throw new UsageError("Batch payload must be a JSON array of command-argument arrays.", "validation_failed", BATCH_HINT, { example: BATCH_EXAMPLE_PAYLOAD, });
+        throw new UsageError("Batch payload must be a JSON array of command-argument arrays.", "validation_failed", contract.BATCH_HINT, { example: contract.BATCH_EXAMPLE_PAYLOAD, });
     }
     return payload.map((step, index) => {
         if (!Array.isArray(step) || !step.every((token) => typeof token === "string")) {
-            throw new UsageError(`Batch step ${index} must be an array of string arguments.`, "validation_failed", BATCH_HINT);
+            throw new UsageError(`Batch step ${index} must be an array of string arguments.`, "validation_failed", contract.BATCH_HINT);
         }
         return step;
     });
@@ -244,12 +277,12 @@ const META_COMMAND_RESOURCES = {
     fixtures: true,
     batch: true,
 };
-let commandRegistryCache;
-function cachedCommandRegistry() {
-    if (commandRegistryCache === undefined) {
-        commandRegistryCache = buildCommandRegistry();
+const commandRegistryCache = new Map();
+function cachedCommandRegistry(resource) {
+    if (!commandRegistryCache.has(resource)) {
+        commandRegistryCache.set(resource, contract.buildCommandRegistry(resource)[resource]);
     }
-    return commandRegistryCache;
+    return commandRegistryCache.get(resource);
 }
 function supportedCommandFlags(entry) {
     const supported = { ...ALWAYS_ALLOWED_COMMAND_FLAGS, };
@@ -287,7 +320,7 @@ function commandRegistrySelectors(flags) {
     return selectors;
 }
 function validateSupportedCommandFlags(resource, action, flags) {
-    const entry = cachedCommandRegistry()[resource]?.[action];
+    const entry = cachedCommandRegistry(resource)?.[action];
     if (!entry)
         return;
     const supported = supportedCommandFlags(entry);
@@ -296,7 +329,7 @@ function validateSupportedCommandFlags(resource, action, flags) {
             throw new UsageError(`Unknown flag --${flagName} for ${resource} ${action}`, "unknown_flag", scopedCommandDiscoveryHint(resource, action));
         }
     }
-    if (flags["dry-run"] === true && !entry.dryRun) {
+    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")
             ? "Remove --dry-run; use --plan to preview the mutation instead."
             : `Remove --dry-run; ${resource} ${action} has no dry-run mode.`);
@@ -359,7 +392,7 @@ function validateRequiredCommandInputs(resource, action, args, flags, entry) {
     }
 }
 function validateRegistryCommandInputs(resource, action, args, flags) {
-    const entry = cachedCommandRegistry()[resource]?.[action];
+    const entry = cachedCommandRegistry(resource)?.[action];
     if (!entry)
         return;
     validateSupportedCommandFlags(resource, action, flags);
@@ -396,7 +429,7 @@ async function validateDryRunHandlerPreconditions(handler, args, flags) {
         throw error;
     }
 }
-function validateMetaCommandInputs(resource, action, flags) {
+async function validateMetaCommandInputs(resource, action, flags) {
     if (resource === "doctor") {
         if (action !== undefined && action !== "run") {
             throw unknownActionError("doctor", action, ["run",]);
@@ -404,11 +437,11 @@ function validateMetaCommandInputs(resource, action, flags) {
         return "run";
     }
     if (resource === "auth") {
-        const validActions = Object.keys(AUTH_ACTIONS);
+        const validActions = Object.keys(contract.AUTH_ACTIONS);
         if (!action) {
             throw missingActionError("auth", validActions, "dss auth login --url URL --api-key KEY");
         }
-        if (!AUTH_ACTIONS[action]) {
+        if (!contract.AUTH_ACTIONS[action]) {
             throw unknownActionError("auth", action, validActions, "auth only supports 'login'. To check credentials/connectivity, run 'dss doctor'.");
         }
         return action;
@@ -417,6 +450,7 @@ function validateMetaCommandInputs(resource, action, flags) {
         if (action !== undefined && action !== "run") {
             throw unknownActionError("install-skill", action, ["run",]);
         }
+        const { AGENTS, } = await import("./skill.js");
         const agentFilter = typeof flags["agent"] === "string" ? flags["agent"] : undefined;
         if (agentFilter && !AGENTS[agentFilter]) {
             throw new UsageError(`Unknown agent: ${agentFilter}.`, "usage_error", COMMANDS_RUN_HINT, { agent: agentFilter, validAgents: Object.keys(AGENTS), });
@@ -425,14 +459,14 @@ function validateMetaCommandInputs(resource, action, flags) {
     }
     if (resource === "agent") {
         if (!action)
-            throw missingActionError("agent", ["contract",], AGENT_CONTRACT_USAGE);
+            throw missingActionError("agent", ["contract",], contract.AGENT_CONTRACT_USAGE);
         if (action !== "contract")
             throw unknownActionError("agent", action, ["contract",]);
         return action;
     }
     if (resource === "commands") {
         if (!action)
-            throw missingActionError("commands", ["run",], COMMANDS_USAGE);
+            throw missingActionError("commands", ["run",], contract.COMMANDS_USAGE);
         if (action !== "run")
             throw unknownActionError("commands", action, ["run",]);
         validateSupportedCommandFlags("commands", "run", flags);
@@ -449,7 +483,7 @@ function validateMetaCommandInputs(resource, action, flags) {
         if (action !== undefined && action !== "run") {
             throw unknownActionError("cleanup", action, ["run",]);
         }
-        const entry = cachedCommandRegistry().cleanup?.run;
+        const entry = cachedCommandRegistry("cleanup")?.run;
         if (entry)
             validateRequiredCommandInputs("cleanup", "run", [], flags, entry);
         return "run";
@@ -464,7 +498,7 @@ function validateMetaCommandInputs(resource, action, flags) {
         if (action !== undefined && action !== "run") {
             throw unknownActionError("batch", action, ["run",]);
         }
-        const entry = cachedCommandRegistry().batch?.run;
+        const entry = cachedCommandRegistry("batch")?.run;
         if (entry)
             validateRequiredCommandInputs("batch", "run", [], flags, entry);
         return "run";
@@ -477,7 +511,7 @@ async function validateBatchStep(argv) {
     const action = positional[1];
     if (!resource)
         throw noCommandError();
-    const metaAction = validateMetaCommandInputs(resource, action, flags);
+    const metaAction = await validateMetaCommandInputs(resource, action, flags);
     if (metaAction)
         return { positional, flags, resource, action: metaAction, };
     const resourceActions = commands[resource];
@@ -496,7 +530,7 @@ async function validateBatchStep(argv) {
 function batchStepNeedsClient(argv) {
     try {
         const { positional, flags, } = parseArgs(argv);
-        if (flags["plan"] === true)
+        if (executionMode(flags).plan)
             return false;
         const resource = positional[0];
         if (!resource)
@@ -578,7 +612,7 @@ function validateBatchStepMode(argv, index) {
     catch {
         return;
     }
-    if (flags["plan"] !== true && flags["dry-run"] !== true)
+    if (!executionMode(flags).plan && !executionMode(flags).dryRun)
         return;
     const resource = positional[0];
     const action = positional[1];
@@ -592,13 +626,13 @@ function validateBatchStepMode(argv, index) {
     const meta = resourceActions[action ?? ""];
     if (!meta)
         return;
-    const entry = cachedCommandRegistry()[resource]?.[action ?? ""];
+    const entry = cachedCommandRegistry(resource)?.[action ?? ""];
     if (!entry)
         return;
-    if (flags["plan"] === true && !entry.flags.some((flag) => flag.name === "plan")) {
+    if (executionMode(flags).plan && !entry.flags.some((flag) => flag.name === "plan")) {
         throw new UsageError(`Batch step ${index} requests --plan, which is not supported for ${resource} ${action}.`, "unknown_flag", "Remove --plan from the step; only mutating commands support --plan.");
     }
-    if (flags["dry-run"] === true && !entry.dryRun) {
+    if (executionMode(flags).dryRun && !entry.dryRun) {
         throw new UsageError(`Batch step ${index} requests --dry-run, which is not supported for ${resource} ${action}.`, "unknown_flag", "Remove --dry-run from the step.");
     }
 }
@@ -607,7 +641,8 @@ function validateBatchStepModes(steps) {
         validateBatchStepMode(steps[index], index);
     }
 }
-function runInstallSkill(flags) {
+async function runInstallSkill(flags) {
+    const { AGENTS, detectAgents, findWorkspaceRoot, installSkill, planSkillInstalls, } = await import("./skill.js");
     const agentFilter = typeof flags["agent"] === "string" ? flags["agent"] : undefined;
     const isGlobal = flags["global"] === true;
     const targetDir = typeof flags["target"] === "string" ? flags["target"] : undefined;
@@ -633,46 +668,34 @@ function runInstallSkill(flags) {
         throw new UsageError("No coding agents detected.", "usage_error", "Use --agent NAME to choose one of the supported agents.", { validAgents: Object.keys(AGENTS), });
     }
     const scope = isGlobal ? "global" : "project";
-    const cwd = targetDir ?? (isGlobal ? process.cwd() : findWorkspaceRoot(process.cwd()));
+    const cwd = isGlobal
+        ? homedir()
+        : targetDir
+            ? resolve(targetDir)
+            : findWorkspaceRoot(process.cwd());
     const installed = planSkillInstalls(targets, { global: isGlobal, cwd, });
-    if (flags["plan"] === true) {
+    if (executionMode(flags).plan) {
         return planResult("install-skill", "run", {
             identifiers: { scope, target: cwd, },
             payload: { installed, },
             idempotency: "none",
             asyncKind: "none",
             exitCodesOnFailure: { usage: 1, error: 2, transient: 3, },
-            plannedAndDryRun: flags["dry-run"] === true,
+            plannedAndDryRun: executionMode(flags).dryRun,
         });
     }
     return {
         scope,
         target: cwd,
-        installed: flags["dry-run"] === true
+        installed: executionMode(flags).dryRun
             ? installed
             : installSkill(targets, { global: isGlobal, cwd, }),
-        ...(flags["dry-run"] === true ? { dryRun: true, } : {}),
+        ...(executionMode(flags).dryRun ? { dryRun: true, } : {}),
     };
 }
 const META_PLAN_EXIT_CODES = { usage: 1, error: 2, transient: 3, };
 function authLoginPlan(flags) {
-    const tlsSettings = resolveTlsSettings(flags);
-    const useEnv = dataikuEnvironmentEnabled();
-    const url = typeof flags["url"] === "string"
-        ? flags["url"]
-        : useEnv
-            ? process.env.DATAIKU_URL ?? ""
-            : "";
-    const apiKey = typeof flags["api-key"] === "string"
-        ? flags["api-key"]
-        : useEnv
-            ? process.env.DATAIKU_API_KEY ?? ""
-            : "";
-    const projectKey = typeof flags["project-key"] === "string"
-        ? flags["project-key"]
-        : useEnv
-            ? process.env.DATAIKU_PROJECT_KEY
-            : undefined;
+    const { url, apiKey, projectKey, tlsSettings, } = resolveLoginCredentials(flags);
     if (!url || !apiKey) {
         throw new UsageError("Missing --url and/or --api-key for auth login.", "missing_required_flag", "Pass --url and --api-key, or set DATAIKU_URL and DATAIKU_API_KEY.", { requiredFlags: ["url", "api-key",], env: ["DATAIKU_URL", "DATAIKU_API_KEY",], });
     }
@@ -700,7 +723,7 @@ function authLoginPlan(flags) {
 function cleanupPlan(flags) {
     const filePath = flags["file"];
     if (typeof filePath !== "string" || filePath.trim().length === 0) {
-        throw new UsageError(`--file is required. Usage: ${CLEANUP_USAGE}`);
+        throw new UsageError(`--file is required. Usage: ${contract.CLEANUP_USAGE}`);
     }
     return planResult("cleanup", "run", {
         identifiers: { file: filePath, },
@@ -711,13 +734,13 @@ function cleanupPlan(flags) {
         idempotency: "none",
         asyncKind: "none",
         exitCodesOnFailure: META_PLAN_EXIT_CODES,
-        plannedAndDryRun: flags["dry-run"] === true,
+        plannedAndDryRun: executionMode(flags).dryRun,
     });
 }
 function batchPlan(flags) {
     const payload = unknownJsonInput(flags);
     if (payload === undefined) {
-        throw new UsageError(`Provide steps via --data, --data-file, or --stdin. Usage: ${BATCH_USAGE}`, "missing_required_flag", BATCH_HINT);
+        throw new UsageError(`Provide steps via --data, --data-file, or --stdin. Usage: ${contract.BATCH_USAGE}`, "missing_required_flag", contract.BATCH_HINT);
     }
     const steps = parseBatchSteps(payload);
     return planResult("batch", "run", {
@@ -728,34 +751,37 @@ function batchPlan(flags) {
         payload: {
             steps: steps.map((argv) => redactArgv(argv)),
             continueOnError: flags["continue-on-error"] === true,
-            dryRun: flags["dry-run"] === true,
+            dryRun: executionMode(flags).dryRun,
         },
         idempotency: "none",
         asyncKind: "none",
-        exitCodesOnFailure: BATCH_PLAN_EXIT_CODES,
-        plannedAndDryRun: flags["dry-run"] === true,
+        exitCodesOnFailure: contract.BATCH_PLAN_EXIT_CODES,
+        plannedAndDryRun: executionMode(flags).dryRun,
     });
 }
 async function runMetaCommand(resource, action, flags) {
+    if (resource !== "version")
+        await loadCommandRuntime();
     if (resource === "doctor") {
         if (action !== undefined && action !== "run") {
             throw unknownActionError("doctor", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        const { runDoctor, } = await import("./cli/doctor.js");
         const { result, exitCode, } = await runDoctor(flags);
         return { action: "run", result, exitCode, };
     }
     if (resource === "auth") {
-        const validActions = Object.keys(AUTH_ACTIONS);
+        const validActions = Object.keys(contract.AUTH_ACTIONS);
         if (!action) {
             throw missingActionError("auth", validActions, "dss auth login --url URL --api-key KEY");
         }
         currentCommandContext.action = action;
-        const authMeta = AUTH_ACTIONS[action];
+        const authMeta = contract.AUTH_ACTIONS[action];
         if (!authMeta) {
             throw unknownActionError("auth", action, validActions, "auth only supports 'login'. To check credentials/connectivity, run 'dss doctor'.");
         }
-        if (flags["plan"] === true) {
+        if (executionMode(flags).plan) {
             return { action, result: authLoginPlan(flags), exitCode: 0, };
         }
         return { action, result: await authMeta.handler(flags), exitCode: 0, };
@@ -765,29 +791,29 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("install-skill", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
-        return { action: "run", result: runInstallSkill(flags), exitCode: 0, };
+        return { action: "run", result: await runInstallSkill(flags), exitCode: 0, };
     }
     if (resource === "agent") {
         if (!action)
-            throw missingActionError("agent", ["contract",], AGENT_CONTRACT_USAGE);
+            throw missingActionError("agent", ["contract",], contract.AGENT_CONTRACT_USAGE);
         currentCommandContext.action = action;
         if (action !== "contract")
             throw unknownActionError("agent", action, ["contract",]);
-        return { action, result: buildAgentContract(), exitCode: 0, };
+        return { action, result: contract.buildAgentContract(), exitCode: 0, };
     }
     if (resource === "commands") {
         if (!action)
-            throw missingActionError("commands", ["run",], COMMANDS_USAGE);
+            throw missingActionError("commands", ["run",], contract.COMMANDS_USAGE);
         currentCommandContext.action = action;
         if (action !== "run")
             throw unknownActionError("commands", action, ["run",]);
         validateSupportedCommandFlags("commands", "run", flags);
         const selectors = commandRegistrySelectors(flags);
-        const registry = buildCommandRegistry();
+        const registry = 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", COMMANDS_USAGE, { selector, });
+                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];
@@ -808,7 +834,7 @@ async function runMetaCommand(resource, action, flags) {
         }
         return {
             action,
-            result: selectors.length === 0 ? commandActionSummary(registry) : selectedRegistry,
+            result: selectors.length === 0 ? contract.commandActionSummary(registry) : selectedRegistry,
             exitCode: 0,
         };
     }
@@ -824,7 +850,7 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("cleanup", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
-        if (flags["plan"] === true) {
+        if (executionMode(flags).plan) {
             return { action: "run", result: cleanupPlan(flags), exitCode: 0, };
         }
         const { result, exitCode, } = await runCleanup(flags);
@@ -835,6 +861,7 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("fixtures", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
+        const { runFixtures, } = await import("./cli/doctor.js");
         return { action: "run", result: await runFixtures(flags), exitCode: 0, };
     }
     if (resource === "batch") {
@@ -842,7 +869,7 @@ async function runMetaCommand(resource, action, flags) {
             throw unknownActionError("batch", action, ["run",]);
         }
         currentCommandContext.action = action ?? "run";
-        if (flags["plan"] === true) {
+        if (executionMode(flags).plan) {
             return { action: "run", result: batchPlan(flags), exitCode: 0, };
         }
         const { result, exitCode, } = await runBatch(flags);
@@ -856,11 +883,14 @@ async function runMetaCommand(resource, action, flags) {
  * share this guard.
  */
 function assertCleanupLedgerSupported(resource, action, flags) {
-    if (typeof flags["record-cleanup"] !== "string" || flags["dry-run"] === true)
+    if (typeof flags["record-cleanup"] !== "string" || executionMode(flags).dryRun)
         return;
-    if (!supportsCleanupLedger(resource, action)) {
+    if (!contract.supportsCleanupLedger(resource, action)) {
         throw new UsageError(`--record-cleanup is not supported for ${resource} ${action}.`);
     }
+    if (resource === "workspace" && action === "create" && flags["stdin"] === true) {
+        throw new UsageError("workspace create cannot combine --record-cleanup with --stdin because the cleanup identifier cannot be replayed from a consumed stream.", "conflicting_input_sources", "Use --data or --data-file so the workspaceKey remains available for the cleanup ledger.");
+    }
 }
 /**
  * Preflight a requested cleanup ledger path before any remote mutation so an
@@ -869,7 +899,7 @@ function assertCleanupLedgerSupported(resource, action, flags) {
  * steps both call it, and dry-run/preview runs never touch the ledger.
  */
 async function preflightCleanupLedgerForFlags(client, flags) {
-    if (flags["dry-run"] === true)
+    if (executionMode(flags).dryRun)
         return;
     const ledgerPath = flags["record-cleanup"];
     if (typeof ledgerPath !== "string")
@@ -920,19 +950,27 @@ async function preflightCleanupLedgerForFlags(client, flags) {
  */
 async function recordCleanupLedgerEntry(client, resource, action, args, flags, result, projectKey) {
     const ledgerPath = flags["record-cleanup"];
-    if (typeof ledgerPath !== "string" || flags["dry-run"] === true)
+    if (typeof ledgerPath !== "string" || executionMode(flags).dryRun)
         return;
     const entry = cleanupLedgerEntry(resource, action, args, flags, result, projectKey);
-    if (entry)
+    if (entry) {
         await appendCleanupLedgerEntry(ledgerPath, entry, client.getBaseUrl());
+        return;
+    }
+    const record = result !== null && typeof result === "object" && !Array.isArray(result)
+        ? result
+        : {};
+    if (record.skipped !== undefined || record.cleanupEligible === false)
+        return;
+    throw new ClientValidationError(`Mutation completed but no cleanup entry could be derived for ${resource} ${action}.`, "ambiguous_outcome", "Inspect the created object and remove it manually; do not assume the requested cleanup ledger contains it.", { resource, action, ledgerPath, });
 }
 async function runBatch(flags) {
     const payload = unknownJsonInput(flags);
     if (payload === undefined) {
-        throw new UsageError(`Provide steps via --data, --data-file, or --stdin. Usage: ${BATCH_USAGE}`, "missing_required_flag", BATCH_HINT);
+        throw new UsageError(`Provide steps via --data, --data-file, or --stdin. Usage: ${contract.BATCH_USAGE}`, "missing_required_flag", contract.BATCH_HINT);
     }
     const steps = parseBatchSteps(payload);
-    if (flags["dry-run"] === true) {
+    if (executionMode(flags).dryRun) {
         const batchProjectKey = typeof flags["project-key"] === "string"
             ? flags["project-key"]
             : dataikuEnvironmentEnabled()
@@ -999,6 +1037,7 @@ async function runBatch(flags) {
                 env: ["DATAIKU_API_KEY",],
             });
         }
+        const { DataikuClient, } = await import("./client.js");
         client = new DataikuClient({
             url,
             apiKey,
@@ -1061,8 +1100,8 @@ async function runBatch(flags) {
                 if (!meta)
                     throw unknownActionError(resource, action, Object.keys(resourceActions));
                 validateSupportedCommandFlags(resource, action, stepFlags);
-                if (stepFlags["plan"] === true) {
-                    result = buildMutationPlan(resource, action, meta, positional.slice(2), stepFlags);
+                if (executionMode(stepFlags).plan) {
+                    result = contract.buildMutationPlan(resource, action, meta, positional.slice(2), stepFlags);
                 }
                 else {
                     if (!client) {
@@ -1102,16 +1141,46 @@ async function runBatch(flags) {
         }
     }
     const ok = firstFailureExit === undefined;
+    const failureSummary = summarizeFailureEnvelopes(results.flatMap((step) => step.error ? [{ index: step.index, error: step.error, },] : []));
     return {
         result: {
             ok,
             total: steps.length,
             completed: results.filter((step) => step.ok !== null).length,
+            ...failureSummary,
             steps: results,
         },
         exitCode: ok ? 0 : firstFailureExit ?? 2,
     };
 }
+function summarizeFailureEnvelopes(failures) {
+    const failureCodes = failures.map(({ index, error, }) => ({
+        index,
+        code: error.code,
+        category: error.category,
+        exitCode: error.exitCode,
+        retryable: error.retryable === true,
+    }));
+    return {
+        failed: failures.length,
+        retryable: failures.length > 0 && failureCodes.every((failure) => failure.retryable),
+        hasRetryableFailures: failureCodes.some((failure) => failure.retryable),
+        failureCodes,
+    };
+}
+function summarizeCleanupFailures(failures) {
+    return summarizeFailureEnvelopes(failures.flatMap((failure) => {
+        const index = failure.index;
+        const error = failure.error;
+        return typeof index === "number"
+            && error !== null
+            && typeof error === "object"
+            && !Array.isArray(error)
+            && error.type === "error"
+            ? [{ index, error: error, },]
+            : [];
+    }));
+}
 function rawFlagValue(argv, flagName) {
     const longFlag = `--${flagName}`;
     for (let index = 0; index < argv.length; index++) {
@@ -1129,7 +1198,7 @@ function commandIsProjectScoped(resource, action) {
     if (!resource)
         return false;
     const usage = commands[resource]?.[action ?? ""]?.usage ?? "";
-    return inferRequiresProject(resource, action ?? "", usage);
+    return contract.inferRequiresProject(resource, action ?? "", usage);
 }
 function rawCommandContext() {
     const argv = process.argv.slice(2);
@@ -1206,13 +1275,48 @@ function requestIdFromBody(body) {
     return undefined;
 }
 const MISSING_PROJECT_KEY_ERROR_PREFIX = "projectKey is required";
+function isAmbiguousMutationFailure(err, context) {
+    if (!(err instanceof DataikuError))
+        return false;
+    const method = err.retry?.method.toUpperCase();
+    if (!method || method === "GET" || method === "HEAD")
+        return false;
+    if (err.status !== 0 && err.status < 500)
+        return false;
+    const entry = context.resource && context.action
+        ? cachedCommandRegistry(context.resource)?.[context.action]
+        : undefined;
+    return entry?.sideEffect === "write" && entry.idempotency === "none";
+}
+const MAX_FAILURE_RESULT_BYTES = 64 * 1024;
+function boundedFailureResult(result) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(result);
+    }
+    catch {
+        return { result: "[unserializable command result]", resultTruncated: true, };
+    }
+    if (serialized === undefined || Buffer.byteLength(serialized, "utf8") <= MAX_FAILURE_RESULT_BYTES) {
+        return { result, };
+    }
+    return {
+        resultPreview: Buffer.from(serialized, "utf8").subarray(0, MAX_FAILURE_RESULT_BYTES).toString("utf8"),
+        resultBytes: Buffer.byteLength(serialized, "utf8"),
+        resultTruncated: true,
+    };
+}
 function errorExitCode(err) {
     if (err instanceof CommandResultFailure)
         return err.exitCode;
+    if (err instanceof ClientValidationError && err.code === "assertion_failed")
+        return 4;
     if (err instanceof ClientValidationError && err.code === "ambiguous_outcome")
         return 2;
     if (err instanceof UsageError || err instanceof ClientValidationError)
         return 1;
+    if (isAmbiguousMutationFailure(err, rawCommandContext()))
+        return 2;
     if (err instanceof DataikuError)
         return err.category === "transient" ? 3 : 2;
     if (err instanceof Error && err.message.startsWith(MISSING_PROJECT_KEY_ERROR_PREFIX))
@@ -1222,7 +1326,8 @@ function errorExitCode(err) {
 function buildErrorReport(err) {
     const context = rawCommandContext();
     const exitCode = errorExitCode(err);
-    if (err instanceof ClientValidationError && err.code === "ambiguous_outcome") {
+    if (err instanceof ClientValidationError
+        && (err.code === "ambiguous_outcome" || err.code === "assertion_failed")) {
         return {
             type: "error",
             ok: false,
@@ -1230,6 +1335,7 @@ function buildErrorReport(err) {
             code: err.code,
             category: "dss",
             exitCode,
+            retryable: false,
             ...(err.hint ? { hint: err.hint, } : {}),
             ...(err.details ? { details: err.details, } : {}),
             ...context,
@@ -1259,7 +1365,29 @@ function buildErrorReport(err) {
             code: err.code,
             category: "dss",
             exitCode: err.exitCode,
-            details: { result: err.result, },
+            details: boundedFailureResult(err.result),
+            ...context,
+        };
+    }
+    if (isAmbiguousMutationFailure(err, context)) {
+        const method = err.retry?.method.toUpperCase() ?? "mutation";
+        return {
+            type: "error",
+            ok: false,
+            error: `The ${method} request failed after dispatch; the mutation outcome is unknown.`,
+            code: "ambiguous_outcome",
+            category: "dss",
+            exitCode: 2,
+            hint: "Read the target state and verify whether the mutation took effect before retrying.",
+            status: err.status,
+            retryable: false,
+            requestId: err.requestId ?? requestIdFromBody(err.body),
+            details: {
+                dssCategory: err.category,
+                statusText: canonicalStatusText(err.status),
+                idempotency: "none",
+                ...(err.retry ? { retry: err.retry, } : {}),
+            },
             ...context,
         };
     }
@@ -1374,8 +1502,8 @@ async function main() {
         throw unknownActionError(resource, action, Object.keys(resourceActions));
     validateSupportedCommandFlags(resource, action, flags);
     const args = positional.slice(2);
-    if (flags["plan"] === true) {
-        const plan = buildMutationPlan(resource, action, actionMeta, args, flags);
+    if (executionMode(flags).plan) {
+        const plan = contract.buildMutationPlan(resource, action, actionMeta, args, flags);
         writeCommandResult(plan);
         return;
     }
@@ -1387,6 +1515,7 @@ async function main() {
         writeCommandResult(result);
         return;
     }
+    actionMeta.validate?.(args, flags);
     const { url, apiKey, projectKey, tlsRejectUnauthorized, caCertPath, } = resolveCredentials(flags);
     currentCommandContext.projectKey = projectKey;
     if (!url) {
@@ -1397,6 +1526,7 @@ async function main() {
     }
     const requestTimeoutMs = num(flags["request-timeout"], "--request-timeout");
     const retryMaxAttempts = num(flags["retries"], "--retries");
+    const { DataikuClient, } = await import("./client.js");
     const client = new DataikuClient({
         url,
         apiKey,
@@ -1416,7 +1546,8 @@ async function main() {
         throw new CommandResultFailure(result, failureExitCode);
     writeCommandResult(result);
 }
-main().catch((err) => {
+main().catch(async (err) => {
+    await loadCommandRuntime();
     writeErrorReport(err);
     process.exitCode = errorExitCode(err);
 });