dataiku-sdk 3.1.0 → 3.3.0

package/dist/src/cli.js

@@ -1,22 +1,30 @@
 #!/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, 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 { 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";
+import { sanitizeSecrets, } from "./utils/secret-sanitize.js";
+let contract;
+let commandRuntimeLoad;
+// 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 ??= import("./cli/contract.js").then((module) => {
+        contract = module;
+    });
+}
 // ---------------------------------------------------------------------------
 // Arg parsing
 // ---------------------------------------------------------------------------
@@ -60,7 +68,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 +103,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,
@@ -158,7 +167,7 @@ async function runCleanup(flags) {
                 action,
                 projectKey: parsed.flags["project-key"],
             });
-            if (!resource || !action || !isAllowedCleanupAction(resource, action)
+            if (!resource || !action || !contract.isAllowedCleanupAction(resource, action)
                 || !commands[resource]?.[action]) {
                 throw new UsageError(`Invalid cleanup argv: ${entry.cleanup.argv.join(" ")}`);
             }
@@ -231,11 +240,11 @@ async function runCleanup(flags) {
 }
 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;
     });
@@ -266,12 +275,14 @@ const META_COMMAND_RESOURCES = {
     fixtures: true,
     batch: true,
 };
-let commandRegistryCache;
-function cachedCommandRegistry() {
-    if (commandRegistryCache === undefined) {
-        commandRegistryCache = buildCommandRegistry();
-    }
-    return commandRegistryCache;
+const commandRegistryCache = new Map();
+function cachedCommandRegistry(resource) {
+    if (!contract)
+        return undefined;
+    if (!commandRegistryCache.has(resource)) {
+        commandRegistryCache.set(resource, contract.buildCommandRegistry(resource)[resource]);
+    }
+    return commandRegistryCache.get(resource);
 }
 function supportedCommandFlags(entry) {
     const supported = { ...ALWAYS_ALLOWED_COMMAND_FLAGS, };
@@ -309,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);
@@ -318,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.`);
@@ -381,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);
@@ -404,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);
     }
@@ -418,7 +439,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",]);
@@ -426,11 +447,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;
@@ -439,6 +460,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), });
@@ -447,14 +469,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);
@@ -471,7 +493,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";
@@ -486,7 +508,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";
@@ -499,7 +521,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];
@@ -518,7 +540,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)
@@ -600,7 +622,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];
@@ -614,13 +636,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.");
     }
 }
@@ -629,7 +651,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;
@@ -655,25 +678,29 @@ 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, };
@@ -706,7 +733,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, },
@@ -717,13 +744,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", {
@@ -734,79 +761,89 @@ 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 === "doctor") {
+        await loadCommandRuntime();
         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);
+        await loadCommandRuntime();
+        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, };
     }
     if (resource === "install-skill") {
+        await loadCommandRuntime();
         if (action !== undefined && action !== "run") {
             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") {
+        await loadCommandRuntime();
         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") {
+        await loadCommandRuntime();
         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 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", 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];
+            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");
@@ -814,7 +851,7 @@ async function runMetaCommand(resource, action, flags) {
         }
         return {
             action,
-            result: selectors.length === 0 ? commandActionSummary(registry) : selectedRegistry,
+            result: selectedRegistry,
             exitCode: 0,
         };
     }
@@ -826,29 +863,33 @@ 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",]);
         }
         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);
         return { action: "run", result, exitCode, };
     }
     if (resource === "fixtures") {
+        await loadCommandRuntime();
         if (action !== undefined && action !== "run") {
             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") {
+        await loadCommandRuntime();
         if (action !== undefined && action !== "run") {
             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);
@@ -862,9 +903,9 @@ 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) {
@@ -878,7 +919,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")
@@ -929,7 +970,7 @@ 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) {
@@ -946,10 +987,10 @@ async function recordCleanupLedgerEntry(client, resource, action, args, flags, r
 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()
@@ -1016,6 +1057,7 @@ async function runBatch(flags) {
                 env: ["DATAIKU_API_KEY",],
             });
         }
+        const { DataikuClient, } = await import("./client.js");
         client = new DataikuClient({
             url,
             apiKey,
@@ -1078,8 +1120,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) {
@@ -1159,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 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];
@@ -1202,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");
@@ -1252,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))
@@ -1262,7 +1374,7 @@ function isAmbiguousMutationFailure(err, context) {
     if (err.status !== 0 && err.status < 500)
         return false;
     const entry = context.resource && context.action
-        ? cachedCommandRegistry()[context.resource]?.[context.action]
+        ? cachedCommandRegistry(context.resource)?.[context.action]
         : undefined;
     return entry?.sideEffect === "write" && entry.idempotency === "none";
 }
@@ -1362,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, } : {}),
@@ -1395,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, } : {}),
@@ -1429,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
 // ---------------------------------------------------------------------------
@@ -1467,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) {
@@ -1478,10 +1602,14 @@ 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);
-    if (flags["plan"] === true) {
-        const plan = buildMutationPlan(resource, action, actionMeta, args, flags);
+    // 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);
         return;
     }
@@ -1493,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) {
@@ -1504,6 +1631,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,
@@ -1523,7 +1651,9 @@ async function main() {
         throw new CommandResultFailure(result, failureExitCode);
     writeCommandResult(result);
 }
-main().catch((err) => {
+main().catch(async (err) => {
+    if (errorReportNeedsCommandRuntime(err))
+        await loadCommandRuntime();
     writeErrorReport(err);
     process.exitCode = errorExitCode(err);
 });