dataiku-sdk 0.12.4 → 0.12.6

package/dist/src/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 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_USAGE, buildAgentContract, buildCommandRegistry, buildMutationPlan, CLEANUP_USAGE, COMMANDS_USAGE, inferRequiresProject, isAllowedCleanupAction, supportsCleanupLedger, } from "./cli/contract.js";
+import { AGENT_CONTRACT_USAGE, AUTH_ACTIONS, BATCH_EXAMPLE_PAYLOAD, BATCH_HINT, BATCH_PLAN_EXIT_CODES, BATCH_USAGE, buildAgentContract, buildCommandRegistry, buildMutationPlan, CLEANUP_USAGE, 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, parseArgs, SHORT_FLAGS, VALUE_FLAGS, } from "./cli/flags.js";
+import { FLAG_ALIASES, isNegativeNumberToken, parseArgs, SHORT_FLAGS, VALUE_FLAGS, } from "./cli/flags.js";
 import { cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
-import { commandFailureExitCode, CommandResultFailure, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
+import { commandFailureExitCode, commandFailureMessage, CommandResultFailure, isFailedWaitResult, planResult, projectResultFields, setCompactJsonOutput, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
 import { currentCommandContext, resolveCredentials, resolveTlsSettings, } from "./cli/runtime.js";
 import { COMMANDS_RUN_HINT, missingActionError, noCommandError, requireArgs, unknownActionError, unknownResourceError, UsageError, } from "./cli/usage.js";
 import { cliVersionResult, } from "./cli/version.js";
@@ -14,7 +14,8 @@ 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, readCleanupLedger, } from "./utils/cleanup-ledger.js";
+import { appendCleanupLedgerEntry, findCleanupLedgerBindingViolation, preflightCleanupLedgerPath, readCleanupLedger, reserveCleanupLedgerDssUrl, } from "./utils/cleanup-ledger.js";
+import { canonicalDssUrl, } from "./utils/dss-url.js";
 // ---------------------------------------------------------------------------
 // Arg parsing
 // ---------------------------------------------------------------------------
@@ -30,6 +31,22 @@ import { appendCleanupLedgerEntry, readCleanupLedger, } from "./utils/cleanup-le
 // ---------------------------------------------------------------------------
 // Auth commands (run before client creation)
 // ---------------------------------------------------------------------------
+function findUnboundAppCleanup(entries) {
+    for (const [index, entry,] of entries.entries()) {
+        const parsed = parseArgs(entry.cleanup.argv);
+        const [resource, action,] = parsed.positional;
+        if (resource !== "app" || action !== "delete-instance")
+            continue;
+        if (parsed.flags["unconfirmed-creation"] === true)
+            continue;
+        const expected = parsed.flags["expect-project-incarnation"];
+        if (typeof expected !== "string")
+            return { index, reason: "missing", };
+        if (!/^[0-9a-f]{64}$/.test(expected))
+            return { index, reason: "invalid", };
+    }
+    return undefined;
+}
 async function runCleanup(flags) {
     const filePath = flags["file"];
     if (typeof filePath !== "string" || filePath.trim().length === 0) {
@@ -53,6 +70,7 @@ async function runCleanup(flags) {
         name: entry.name,
         path: entry.path,
         projectKey: entry.projectKey,
+        dssUrl: typeof entry.dssUrl === "string" ? canonicalDssUrl(entry.dssUrl) : null,
         cleanup: entry.cleanup,
     }));
     if (flags["apply"] !== true) {
@@ -77,6 +95,47 @@ async function runCleanup(flags) {
         tlsRejectUnauthorized,
         caCertPath,
     });
+    // Refuse before any DSS call when the ledger is not entirely bound to this
+    // server: a mixed ledger must never partially apply.
+    const bindingViolation = findCleanupLedgerBindingViolation(ordered, client.getBaseUrl());
+    if (bindingViolation) {
+        return {
+            result: {
+                applied: false,
+                steps,
+                bindingError: {
+                    entryIndex: bindingViolation.index,
+                    resource: bindingViolation.resource,
+                    action: bindingViolation.action,
+                    reason: bindingViolation.reason,
+                    expectedDssUrl: client.getBaseUrl(),
+                    ...(bindingViolation.found === undefined
+                        ? {}
+                        : { foundDssUrl: bindingViolation.found, }),
+                },
+            },
+            exitCode: 2,
+        };
+    }
+    // Lifecycle binding is as load-bearing as server binding. Validate the whole
+    // reversed plan before step one so a later legacy app entry cannot leave an
+    // earlier cleanup applied and then fail on project-key reuse protection.
+    const lifecycleViolation = findUnboundAppCleanup(ordered);
+    if (lifecycleViolation) {
+        return {
+            result: {
+                applied: false,
+                steps,
+                lifecycleError: {
+                    entryIndex: lifecycleViolation.index,
+                    resource: "app",
+                    action: "delete-instance",
+                    reason: lifecycleViolation.reason,
+                },
+            },
+            exitCode: 2,
+        };
+    }
     const applied = [];
     const failures = [];
     for (const [index, entry,] of ordered.entries()) {
@@ -87,7 +146,29 @@ async function runCleanup(flags) {
                 || !commands[resource]?.[action]) {
                 throw new UsageError(`Invalid cleanup argv: ${entry.cleanup.argv.join(" ")}`);
             }
+            if (resource === "app"
+                && action === "delete-instance"
+                && parsed.flags["unconfirmed-creation"] !== true
+                && typeof parsed.flags["expect-project-incarnation"] !== "string") {
+                throw new UsageError("App cleanup entry is not bound to a project incarnation. Refusing deletion after possible project-key reuse.", "validation_failed", "Capture a new cleanup entry from the current CLI. Legacy entries cannot safely delete app projects.");
+            }
             const result = await commands[resource][action].handler(client, args, parsed.flags);
+            if (isFailedWaitResult(result)) {
+                const failure = {
+                    index,
+                    cleanup: entry.cleanup,
+                    error: commandFailureMessage(result),
+                    result,
+                };
+                failures.push(failure);
+                if (flags["continue-on-error"] !== true) {
+                    return {
+                        result: { applied: true, steps, results: applied, failures, },
+                        exitCode: 2,
+                    };
+                }
+                continue;
+            }
             applied.push({ index, cleanup: entry.cleanup, result, });
         }
         catch (error) {
@@ -170,6 +251,25 @@ function supportedCommandFlags(entry) {
     }
     return supported;
 }
+function scopedCommandDiscoveryHint(resource, action) {
+    return `Use \`dss commands run --fields ${resource}.${action} --json\` to list the flags this command supports.`;
+}
+/**
+ * Resolve the registry field selectors for `commands run --fields`. Omitting the flag
+ * selects the whole registry, but an explicitly supplied value carrying no selector is a
+ * usage error: an agent that asked for a scoped subset must never be handed the full
+ * registry instead.
+ */
+function commandRegistrySelectors(flags) {
+    const fieldsFlag = flags["fields"];
+    if (typeof fieldsFlag !== "string")
+        return [];
+    const selectors = fieldsFlag.split(",").map((field) => field.trim()).filter((field) => field.length > 0);
+    if (selectors.length === 0) {
+        throw new UsageError("--fields requires at least one selector. Expected RESOURCE or RESOURCE.ACTION[.FIELD...].", "usage_error", COMMANDS_RUN_HINT, { fields: fieldsFlag, });
+    }
+    return selectors;
+}
 function validateSupportedCommandFlags(resource, action, flags) {
     const entry = cachedCommandRegistry()[resource]?.[action];
     if (!entry)
@@ -177,9 +277,14 @@ function validateSupportedCommandFlags(resource, action, flags) {
     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");
+            throw new UsageError(`Unknown flag --${flagName} for ${resource} ${action}`, "unknown_flag", scopedCommandDiscoveryHint(resource, action));
         }
     }
+    if (flags["dry-run"] === true && !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.`);
+    }
 }
 function stripOptionalUsageGroupsForValidation(usage) {
     let stripped = "";
@@ -207,23 +312,30 @@ function requiredPositionalCount(usage) {
     const positionalTokens = [...requiredUsage.matchAll(/<[^>]+>/g),];
     return positionalTokens.length;
 }
-function flagIsProvided(flags, name) {
+function flagIsProvided(flags, name, allowEmpty = false) {
     const value = flags[name];
     if (value === undefined || value === false)
         return false;
-    return typeof value !== "string" || value.length > 0;
+    if (typeof value !== "string")
+        return true;
+    return allowEmpty || value.length > 0;
 }
 function validateRequiredCommandInputs(resource, action, args, flags, entry) {
     const argCount = requiredPositionalCount(entry.usage);
+    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);
     for (const flagName of entry.requiredFlags) {
-        if (!flagIsProvided(flags, flagName)) {
+        if (!flagIsProvided(flags, flagName, allowEmptyFlags[flagName] === true)) {
             throw new UsageError(`--${flagName} is required. Usage: ${entry.usage}`, "missing_required_flag");
         }
     }
     for (const choice of entry.requiredOneOf ?? []) {
-        const satisfied = choice.oneOf.some((alternative) => alternative.every((flagName) => flagIsProvided(flags, flagName)));
+        const satisfied = choice.oneOf.some((alternative) => alternative.every((flagName) => flagIsProvided(flags, flagName, allowEmptyFlags[flagName] === true)));
         if (!satisfied) {
             const alternatives = choice.oneOf.map((alternative) => alternative.map((flagName) => `--${flagName}`).join(" and ")).join(" or ");
             throw new UsageError(`One of ${alternatives} is required for ${resource} ${action}. Usage: ${entry.usage}`, "missing_required_flag");
@@ -307,6 +419,7 @@ function validateMetaCommandInputs(resource, action, flags) {
             throw missingActionError("commands", ["run",], COMMANDS_USAGE);
         if (action !== "run")
             throw unknownActionError("commands", action, ["run",]);
+        commandRegistrySelectors(flags);
         return action;
     }
     if (resource === "version") {
@@ -365,7 +478,9 @@ async function validateBatchStep(argv) {
 }
 function batchStepNeedsClient(argv) {
     try {
-        const { positional, } = parseArgs(argv);
+        const { positional, flags, } = parseArgs(argv);
+        if (flags["plan"] === true)
+            return false;
         const resource = positional[0];
         if (!resource)
             return false;
@@ -401,6 +516,79 @@ function batchStepCommandContext(argv) {
     }
     return { resource: positionals[0], action: positionals[1], };
 }
+const SENSITIVE_ARGV_VALUE_FLAGS = new Set([
+    "api-key",
+]);
+function redactArgv(argv) {
+    const redacted = [];
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === "--") {
+            redacted.push(...argv.slice(index));
+            break;
+        }
+        if (arg.startsWith("--")) {
+            const eqIdx = arg.indexOf("=");
+            const rawFlagName = eqIdx === -1 ? arg.slice(2) : arg.slice(2, eqIdx);
+            const flagName = FLAG_ALIASES[rawFlagName] ?? rawFlagName;
+            if (SENSITIVE_ARGV_VALUE_FLAGS.has(flagName)) {
+                if (eqIdx !== -1) {
+                    redacted.push(`${arg.slice(0, eqIdx + 1)}***`);
+                }
+                else {
+                    redacted.push(arg);
+                    const next = argv[index + 1];
+                    if (next !== undefined
+                        && (next === "-" || !next.startsWith("-") || isNegativeNumberToken(next))) {
+                        redacted.push("***");
+                        index++;
+                    }
+                }
+                continue;
+            }
+        }
+        redacted.push(arg);
+    }
+    return redacted;
+}
+function validateBatchStepMode(argv, index) {
+    let positional;
+    let flags;
+    try {
+        ({ positional, flags, } = parseArgs(argv));
+    }
+    catch {
+        return;
+    }
+    if (flags["plan"] !== true && flags["dry-run"] !== true)
+        return;
+    const resource = positional[0];
+    const action = positional[1];
+    if (!resource)
+        return;
+    if (META_COMMAND_RESOURCES[resource] === true)
+        return;
+    const resourceActions = commands[resource];
+    if (!resourceActions)
+        return;
+    const meta = resourceActions[action ?? ""];
+    if (!meta)
+        return;
+    const entry = cachedCommandRegistry()[resource]?.[action ?? ""];
+    if (!entry)
+        return;
+    if (flags["plan"] === true && !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) {
+        throw new UsageError(`Batch step ${index} requests --dry-run, which is not supported for ${resource} ${action}.`, "unknown_flag", "Remove --dry-run from the step.");
+    }
+}
+function validateBatchStepModes(steps) {
+    for (let index = 0; index < steps.length; index++) {
+        validateBatchStepMode(steps[index], index);
+    }
+}
 function runInstallSkill(flags) {
     const agentFilter = typeof flags["agent"] === "string" ? flags["agent"] : undefined;
     const isGlobal = flags["global"] === true;
@@ -520,13 +708,13 @@ function batchPlan(flags) {
             needsClient: steps.some((argv) => batchStepNeedsClient(argv)),
         },
         payload: {
-            steps,
+            steps: steps.map((argv) => redactArgv(argv)),
             continueOnError: flags["continue-on-error"] === true,
             dryRun: flags["dry-run"] === true,
         },
         idempotency: "none",
         asyncKind: "none",
-        exitCodesOnFailure: META_PLAN_EXIT_CODES,
+        exitCodesOnFailure: BATCH_PLAN_EXIT_CODES,
         plannedAndDryRun: flags["dry-run"] === true,
     });
 }
@@ -575,7 +763,22 @@ async function runMetaCommand(resource, action, flags) {
         currentCommandContext.action = action;
         if (action !== "run")
             throw unknownActionError("commands", action, ["run",]);
-        return { action, result: buildCommandRegistry(), exitCode: 0, };
+        const selectors = commandRegistrySelectors(flags);
+        const registry = 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, });
+            }
+            const [selectedResource, selectedAction,] = selectorParts;
+            const resourceActions = registry[selectedResource];
+            if (!resourceActions)
+                throw unknownResourceError(selectedResource);
+            if (selectedAction && !resourceActions[selectedAction]) {
+                throw unknownActionError(selectedResource, selectedAction, Object.keys(resourceActions));
+            }
+        }
+        return { action, result: registry, exitCode: 0, };
     }
     if (resource === "version") {
         if (action !== undefined && action !== "run") {
@@ -615,6 +818,82 @@ async function runMetaCommand(resource, action, flags) {
     }
     return undefined;
 }
+/**
+ * Cleanup-ledger support is checked before a handler runs so an unsupported
+ * `--record-cleanup` fails without mutating DSS. Direct dispatch and batch steps
+ * share this guard.
+ */
+function assertCleanupLedgerSupported(resource, action, flags) {
+    if (typeof flags["record-cleanup"] !== "string" || flags["dry-run"] === true)
+        return;
+    if (!supportsCleanupLedger(resource, action)) {
+        throw new UsageError(`--record-cleanup is not supported for ${resource} ${action}.`);
+    }
+}
+/**
+ * Preflight a requested cleanup ledger path before any remote mutation so an
+ * unwritable (or unwritable-to-be) ledger fails fast with no DSS-side change.
+ * Shares assertCleanupLedgerSupported's placement: direct dispatch and batch
+ * steps both call it, and dry-run/preview runs never touch the ledger.
+ */
+async function preflightCleanupLedgerForFlags(client, flags) {
+    if (flags["dry-run"] === true)
+        return;
+    const ledgerPath = flags["record-cleanup"];
+    if (typeof ledgerPath !== "string")
+        return;
+    if (ledgerPath.trim().length === 0) {
+        throw new UsageError("--record-cleanup requires a non-empty file path.", "validation_failed");
+    }
+    const assertExistingEntriesBound = async () => {
+        let entries;
+        try {
+            entries = await readCleanupLedger(ledgerPath);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        const violation = findCleanupLedgerBindingViolation(entries, client.getBaseUrl());
+        if (violation) {
+            throw new UsageError(`Existing cleanup ledger entry ${violation.index + 1} is not bound to the configured DSS server.`, "validation_failed", "Use a new cleanup ledger path, or run the mutation against the DSS server already bound to this ledger.", {
+                entryIndex: violation.index,
+                resource: violation.resource,
+                action: violation.action,
+                reason: violation.reason,
+            });
+        }
+    };
+    try {
+        await preflightCleanupLedgerPath(ledgerPath);
+        await assertExistingEntriesBound();
+        await reserveCleanupLedgerDssUrl(ledgerPath, client.getBaseUrl());
+        // Re-read after winning the atomic reservation. This catches an entry
+        // appended between the initial compatibility check and reservation.
+        await assertExistingEntriesBound();
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            throw error;
+        throw new UsageError(`Could not preflight cleanup ledger: ${error instanceof Error ? error.message : String(error)}`, "validation_failed");
+    }
+}
+/**
+ * Append the cleanup entry for a completed handler result. Callers must pass the
+ * raw, unprojected result and must call this before any failure exit code is
+ * raised: an indeterminate post-POST outcome stays addressable only when the
+ * ledger records it first. Eligibility (dry runs, skipped work, an explicit
+ * `cleanupEligible:false`) is decided by `cleanupLedgerEntry`, never here.
+ */
+async function recordCleanupLedgerEntry(client, resource, action, args, flags, result, projectKey) {
+    const ledgerPath = flags["record-cleanup"];
+    if (typeof ledgerPath !== "string" || flags["dry-run"] === true)
+        return;
+    const entry = cleanupLedgerEntry(resource, action, args, flags, result, projectKey);
+    if (entry)
+        await appendCleanupLedgerEntry(ledgerPath, entry, client.getBaseUrl());
+}
 async function runBatch(flags) {
     const payload = unknownJsonInput(flags);
     if (payload === undefined) {
@@ -631,6 +910,7 @@ async function runBatch(flags) {
             const context = batchStepCommandContext(argv);
             Object.assign(currentCommandContext, { ...context, projectKey: batchProjectKey, });
             try {
+                validateBatchStepMode(argv, index);
                 const step = await validateBatchStep(argv);
                 Object.assign(currentCommandContext, {
                     resource: step.resource,
@@ -639,13 +919,19 @@ async function runBatch(flags) {
                         ? step.flags["project-key"]
                         : batchProjectKey,
                 });
-                return { index, args: argv, resource: step.resource, action: step.action, runnable: true, };
+                return {
+                    index,
+                    args: redactArgv(argv),
+                    resource: step.resource,
+                    action: step.action,
+                    runnable: true,
+                };
             }
             catch (error) {
                 const envelope = buildErrorReport(error);
                 return {
                     index,
-                    args: argv,
+                    args: redactArgv(argv),
                     resource: context.resource,
                     action: context.action,
                     runnable: false,
@@ -658,6 +944,7 @@ async function runBatch(flags) {
             exitCode: planned.every((step) => step.runnable) ? 0 : 1,
         };
     }
+    validateBatchStepModes(steps);
     let projectKey = typeof flags["project-key"] === "string"
         ? flags["project-key"]
         : dataikuEnvironmentEnabled()
@@ -700,7 +987,7 @@ async function runBatch(flags) {
         let resource = context.resource;
         let action = context.action;
         if (firstFailureExit !== undefined && !continueOnError) {
-            results.push({ index, args: argv, resource, action, ok: null, skipped: true, });
+            results.push({ index, args: redactArgv(argv), resource, action, ok: null, skipped: true, });
             continue;
         }
         Object.assign(currentCommandContext, {
@@ -742,10 +1029,19 @@ async function runBatch(flags) {
                 if (!meta)
                     throw unknownActionError(resource, action, Object.keys(resourceActions));
                 validateSupportedCommandFlags(resource, action, stepFlags);
-                if (!client) {
-                    throw new UsageError("Missing Dataiku URL.", "missing_required_flag", "Set DATAIKU_URL or pass --url.", { requiredFlags: ["url",], env: ["DATAIKU_URL",], });
+                if (stepFlags["plan"] === true) {
+                    result = buildMutationPlan(resource, action, meta, positional.slice(2), stepFlags);
+                }
+                else {
+                    if (!client) {
+                        throw new UsageError("Missing Dataiku URL.", "missing_required_flag", "Set DATAIKU_URL or pass --url.", { requiredFlags: ["url",], env: ["DATAIKU_URL",], });
+                    }
+                    assertCleanupLedgerSupported(resource, action, stepFlags);
+                    await preflightCleanupLedgerForFlags(client, stepFlags);
+                    const stepArgs = positional.slice(2);
+                    result = await meta.handler(client, stepArgs, stepFlags);
+                    await recordCleanupLedgerEntry(client, resource, action, stepArgs, stepFlags, result, projectKey);
                 }
-                result = await meta.handler(client, positional.slice(2), stepFlags);
                 const failureExitCode = commandFailureExitCode(result);
                 if (failureExitCode !== undefined)
                     throw new CommandResultFailure(result, failureExitCode);
@@ -755,11 +1051,18 @@ async function runBatch(flags) {
                 ? stepFieldsFlag.split(",").map((field) => field.trim()).filter((field) => field.length > 0)
                 : [];
             const stepResult = stepFields.length > 0 ? projectResultFields(result, stepFields) : result;
-            results.push({ index, args: argv, resource, action, ok: true, result: stepResult, });
+            results.push({
+                index,
+                args: redactArgv(argv),
+                resource,
+                action,
+                ok: true,
+                result: stepResult,
+            });
         }
         catch (error) {
             const envelope = buildErrorReport(error);
-            results.push({ index, args: argv, resource, action, ok: false, error: envelope, });
+            results.push({ index, args: redactArgv(argv), resource, action, ok: false, error: envelope, });
             if (firstFailureExit === undefined)
                 firstFailureExit = envelope.exitCode;
         }
@@ -901,7 +1204,7 @@ function buildErrorReport(err) {
             type: "error",
             ok: false,
             error: err.message,
-            code: "long_running_failure",
+            code: err.code,
             category: "dss",
             exitCode: err.exitCode,
             details: { result: err.result, },
@@ -973,6 +1276,7 @@ function writeErrorReport(err) {
 async function main() {
     loadEnvFile();
     const { positional, flags, } = parseArgs(process.argv.slice(2));
+    setCompactJsonOutput(flags["json"] === true);
     const fieldsFlag = flags["fields"];
     if (typeof fieldsFlag === "string") {
         const selected = fieldsFlag.split(",").map((field) => field.trim()).filter((field) => field.length > 0);
@@ -1040,17 +1344,10 @@ async function main() {
         tlsRejectUnauthorized,
         caCertPath,
     });
-    if (typeof flags["record-cleanup"] === "string" && flags["dry-run"] !== true) {
-        if (!supportsCleanupLedger(resource, action)) {
-            throw new UsageError(`--record-cleanup is not supported for ${resource} ${action}.`);
-        }
-    }
+    assertCleanupLedgerSupported(resource, action, flags);
+    await preflightCleanupLedgerForFlags(client, flags);
     const result = await actionMeta.handler(client, args, flags);
-    if (typeof flags["record-cleanup"] === "string" && flags["dry-run"] !== true) {
-        const entry = cleanupLedgerEntry(resource, action, args, flags, result, projectKey);
-        if (entry)
-            await appendCleanupLedgerEntry(flags["record-cleanup"], entry);
-    }
+    await recordCleanupLedgerEntry(client, resource, action, args, flags, result, projectKey);
     const failureExitCode = commandFailureExitCode(result);
     if (failureExitCode !== undefined)
         throw new CommandResultFailure(result, failureExitCode);

package/dist/src/client.d.ts

@@ -151,6 +151,12 @@ export declare class DataikuClient {
     get savedModels(): SavedModelsResource;
     get modelEvaluationStores(): ModelEvaluationStoresResource;
     constructor(config?: DataikuClientConfig);
+    /**
+     * Canonical request base URL: the exact prefix every HTTP verb concatenates
+     * paths onto (trimmed, trailing slashes stripped). Callers that must bind a
+     * recorded artifact to its originating DSS server compare against this.
+     */
+    getBaseUrl(): string;
     getRequestTimeoutMs(): number;
     resolveProjectKey(paramValue?: string): string;
     get<T = unknown>(path: string): Promise<T>;
@@ -159,7 +165,13 @@ export declare class DataikuClient {
         text: string;
         truncated: boolean;
     }>;
-    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /**
+     * POST with optional transient retry. Only opt in when repeating the request
+     * is safe: the server may have accepted an attempt whose response was lost.
+     */
+    post<T = unknown>(path: string, body?: unknown, options?: {
+        retryMaxAttempts?: number;
+    }): Promise<T>;
     postText(path: string, body?: unknown): Promise<string>;
     put<T = unknown>(path: string, body: unknown): Promise<T>;
     del(path: string): Promise<void>;