dataiku-sdk 3.4.0 → 3.6.0

package/dist/src/cli.js

@@ -4,11 +4,12 @@ import { homedir, } from "node:os";
 import { resolve, } from "node:path";
 import { num, unknownJsonInput, } from "./cli/coerce.js";
 import { commands, } from "./cli/commands/index.js";
-import { dataikuEnvironmentEnabled, loadEnvFile, } from "./cli/env.js";
+import { ambientProjectKey, loadEnvFile, } from "./cli/env.js";
 import { executionMode, FLAG_ALIASES, isNegativeNumberToken, parseArgs, SHORT_FLAGS, VALUE_FLAGS, } from "./cli/flags.js";
 import { cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
 import { commandFailureExitCode, CommandResultFailure, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
 import { currentCommandContext, resolveCredentials, resolveLoginCredentials, } from "./cli/runtime.js";
+import { commandUsage, } from "./cli/syntax.js";
 import { COMMANDS_RUN_HINT, inferRequiresProject, missingActionError, noCommandError, requireArgs, RESOURCE_NAMES, unknownActionError, unknownResourceError, UsageError, } from "./cli/usage.js";
 import { cliVersionResult, } from "./cli/version.js";
 import { getCredentialsPath, } from "./config.js";
@@ -171,17 +172,6 @@ async function runCleanup(flags) {
                 || !commands[resource]?.[action]) {
                 throw new UsageError(`Invalid cleanup argv: ${entry.cleanup.argv.join(" ")}`);
             }
-            if (resource === "project"
-                && action === "delete"
-                && typeof parsed.flags["expect-project-incarnation"] !== "string") {
-                throw new UsageError("Project 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 projects.");
-            }
-            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 = {
@@ -334,32 +324,11 @@ function validateSupportedCommandFlags(resource, action, flags) {
             ? "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 = "";
-    let optionalDepth = 0;
-    for (const char of usage) {
-        if (char === "[") {
-            optionalDepth++;
-            if (optionalDepth === 1)
-                stripped += " ";
-            continue;
-        }
-        if (char === "]" && optionalDepth > 0) {
-            optionalDepth--;
-            if (optionalDepth === 0)
-                stripped += " ";
-            continue;
-        }
-        if (optionalDepth === 0)
-            stripped += char;
+    // Registry commands reject --plan in buildMutationPlan; meta commands never reach it.
+    if (META_COMMAND_RESOURCES[resource] === true && executionMode(flags).plan
+        && !entry.flags.some((flag) => flag.name === "plan")) {
+        throw new UsageError(`--plan is only supported for mutating commands; ${resource} ${action} has no plan mode.`, "usage_error", `Remove --plan; ${resource} ${action} has no plan mode.`);
     }
-    return stripped;
-}
-function requiredPositionalCount(usage) {
-    const requiredUsage = stripOptionalUsageGroupsForValidation(usage);
-    const positionalTokens = [...requiredUsage.matchAll(/<[^>]+>/g),];
-    return positionalTokens.length;
 }
 function flagIsProvided(flags, name, allowEmpty = false) {
     const value = flags[name];
@@ -370,7 +339,7 @@ function flagIsProvided(flags, name, allowEmpty = false) {
     return allowEmpty || value.length > 0;
 }
 function validateRequiredCommandInputs(resource, action, args, flags, entry) {
-    const argCount = requiredPositionalCount(entry.usage);
+    const argCount = entry.positionalArguments.filter((positional) => positional.required).length;
     const allowEmptyFlags = {};
     for (const flag of entry.flags) {
         if (flag.allowEmptyValue === true)
@@ -439,81 +408,60 @@ async function validateDryRunHandlerPreconditions(handler, args, flags) {
         throw error;
     }
 }
+/**
+ * The one validator for meta commands, shared by direct runs and batch
+ * --dry-run: action, supported flags (incl. --plan/--dry-run), flag conflicts,
+ * and required inputs. Returns the canonical action, or undefined for a
+ * non-meta resource.
+ */
 async function validateMetaCommandInputs(resource, action, flags) {
-    if (resource === "doctor") {
-        if (action !== undefined && action !== "run") {
-            throw unknownActionError("doctor", action, ["run",]);
-        }
-        return "run";
-    }
+    if (META_COMMAND_RESOURCES[resource] !== true)
+        return undefined;
+    await loadCommandRuntime();
+    let resolved;
     if (resource === "auth") {
         const validActions = Object.keys(contract.AUTH_ACTIONS);
-        if (!action) {
-            throw missingActionError("auth", validActions, "dss auth login --url URL --api-key KEY");
-        }
+        if (!action)
+            throw missingActionError("auth", validActions, commandUsage("auth", "login"));
         if (!contract.AUTH_ACTIONS[action]) {
             throw unknownActionError("auth", action, validActions, "auth only supports 'login'. To check credentials/connectivity, run 'dss doctor'.");
         }
-        return action;
+        resolved = action;
     }
-    if (resource === "install-skill") {
-        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), });
-        }
-        return "run";
-    }
-    if (resource === "agent") {
+    else if (resource === "agent" || resource === "commands") {
+        const only = resource === "agent" ? "contract" : "run";
+        const usage = resource === "agent" ? contract.AGENT_CONTRACT_USAGE : contract.COMMANDS_USAGE;
         if (!action)
-            throw missingActionError("agent", ["contract",], contract.AGENT_CONTRACT_USAGE);
-        if (action !== "contract")
-            throw unknownActionError("agent", action, ["contract",]);
-        return action;
+            throw missingActionError(resource, [only,], usage);
+        if (action !== only)
+            throw unknownActionError(resource, action, [only,]);
+        resolved = action;
     }
-    if (resource === "commands") {
-        if (!action)
-            throw missingActionError("commands", ["run",], contract.COMMANDS_USAGE);
-        if (action !== "run")
-            throw unknownActionError("commands", action, ["run",]);
-        validateSupportedCommandFlags("commands", "run", flags);
-        commandRegistrySelectors(flags);
-        return action;
-    }
-    if (resource === "version") {
+    else {
         if (action !== undefined && action !== "run") {
-            throw unknownActionError("version", action, ["run",]);
+            throw unknownActionError(resource, action, ["run",]);
         }
-        return "run";
+        resolved = "run";
     }
-    if (resource === "cleanup") {
-        if (action !== undefined && action !== "run") {
-            throw unknownActionError("cleanup", action, ["run",]);
-        }
-        const entry = cachedCommandRegistry("cleanup")?.run;
+    validateSupportedCommandFlags(resource, resolved, flags);
+    if (resource === "commands")
+        commandRegistrySelectors(flags);
+    if (resource === "cleanup" || resource === "batch") {
+        const entry = cachedCommandRegistry(resource)?.run;
         if (entry)
-            validateRequiredCommandInputs("cleanup", "run", [], flags, entry);
-        return "run";
+            validateRequiredCommandInputs(resource, "run", [], flags, entry);
     }
-    if (resource === "fixtures") {
-        if (action !== undefined && action !== "run") {
-            throw unknownActionError("fixtures", action, ["run",]);
-        }
-        return "run";
+    if (resource === "cleanup" && flags["apply"] === true && executionMode(flags).dryRun) {
+        throw new UsageError("--dry-run and --apply are mutually exclusive.", "usage_error");
     }
-    if (resource === "batch") {
-        if (action !== undefined && action !== "run") {
-            throw unknownActionError("batch", action, ["run",]);
+    if (resource === "install-skill") {
+        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), });
         }
-        const entry = cachedCommandRegistry("batch")?.run;
-        if (entry)
-            validateRequiredCommandInputs("batch", "run", [], flags, entry);
-        return "run";
     }
-    return undefined;
+    return resolved;
 }
 async function validateBatchStep(argv) {
     const { positional, flags, } = parseArgs(argv);
@@ -553,29 +501,8 @@ function batchStepNeedsClient(argv) {
     }
 }
 function batchStepCommandContext(argv) {
-    const positionals = [];
-    for (let index = 0; index < argv.length; index++) {
-        const arg = argv[index];
-        if (arg === "--") {
-            positionals.push(...argv.slice(index + 1));
-            break;
-        }
-        if (arg.startsWith("--")) {
-            const name = arg.slice(2).split("=")[0] ?? "";
-            const canonical = FLAG_ALIASES[name] ?? name;
-            if (!arg.includes("=") && VALUE_FLAGS.has(canonical))
-                index++;
-            continue;
-        }
-        if (arg.length === 2 && arg[0] === "-" && arg[1] !== "-") {
-            const long = SHORT_FLAGS[arg[1]];
-            if (long && VALUE_FLAGS.has(long))
-                index++;
-            continue;
-        }
-        positionals.push(arg);
-    }
-    return { resource: positionals[0], action: positionals[1], };
+    const [resource, action,] = rawPositionals(argv);
+    return { resource, action, };
 }
 const SENSITIVE_ARGV_VALUE_FLAGS = {
     "api-key": true,
@@ -769,133 +696,78 @@ function batchPlan(flags) {
         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") {
-        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 = contract.AUTH_ACTIONS[action];
-        if (!authMeta) {
-            throw unknownActionError("auth", action, validActions, "auth only supports 'login'. To check credentials/connectivity, run 'dss doctor'.");
-        }
-        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: await runInstallSkill(flags), exitCode: 0, };
-    }
-    if (resource === "agent") {
-        await loadCommandRuntime();
-        if (!action)
-            throw missingActionError("agent", ["contract",], contract.AGENT_CONTRACT_USAGE);
-        currentCommandContext.action = action;
-        if (action !== "contract")
-            throw unknownActionError("agent", action, ["contract",]);
-        return { action, result: contract.buildAgentContract(), exitCode: 0, };
-    }
-    if (resource === "commands") {
-        await loadCommandRuntime();
-        if (!action)
-            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 outputPath = flags["output"];
-        if (selectors.length === 0 && typeof outputPath !== "string") {
-            return { action, result: contract.commandActionSummary(), exitCode: 0, };
+async function runMetaCommand(resource, rawAction, flags) {
+    const action = await validateMetaCommandInputs(resource, rawAction, flags);
+    if (action === undefined)
+        return undefined;
+    currentCommandContext.action = action;
+    const plan = executionMode(flags).plan;
+    switch (resource) {
+        case "doctor": {
+            const { runDoctor, } = await import("./cli/doctor.js");
+            const { result, exitCode, } = await runDoctor(flags);
+            return { action, result, exitCode, };
         }
-        const registry = selectors.length === 0 ? contract.buildCommandRegistry() : {};
-        for (const selector of selectors) {
-            const selectorParts = selector.split(".");
-            if (selectorParts.some((part) => part.length === 0)) {
-                throw new UsageError(`Invalid --fields selector: ${selector}. Expected RESOURCE or RESOURCE.ACTION[.FIELD...].`, "usage_error", contract.COMMANDS_USAGE, { selector, });
-            }
-            const [selectedResource, selectedAction,] = selectorParts;
-            const resourceActions = cachedCommandRegistry(selectedResource);
-            if (!resourceActions)
-                throw unknownResourceError(selectedResource);
-            registry[selectedResource] = resourceActions;
-            if (selectedAction && !resourceActions[selectedAction]) {
-                throw unknownActionError(selectedResource, selectedAction, Object.keys(resourceActions));
-            }
+        case "auth":
+            if (plan)
+                return { action, result: authLoginPlan(flags), exitCode: 0, };
+            return { action, result: await contract.AUTH_ACTIONS[action].handler(flags), exitCode: 0, };
+        case "install-skill":
+            return { action, result: await runInstallSkill(flags), exitCode: 0, };
+        case "agent":
+            return { action, result: contract.buildAgentContract(), exitCode: 0, };
+        case "version":
+            return { action, result: cliVersionResult(), exitCode: 0, };
+        case "fixtures": {
+            const { runFixtures, } = await import("./cli/doctor.js");
+            return { action, result: await runFixtures(flags), exitCode: 0, };
         }
-        const selectedRegistry = selectors.length === 0
-            ? registry
-            : 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");
-            return { action, result: { path: outputPath, }, exitCode: 0, };
+        case "cleanup": {
+            if (plan)
+                return { action, result: cleanupPlan(flags), exitCode: 0, };
+            const { result, exitCode, } = await runCleanup(flags);
+            return { action, result, exitCode, };
         }
-        return {
-            action,
-            result: selectedRegistry,
-            exitCode: 0,
-        };
-    }
-    if (resource === "version") {
-        if (action !== undefined && action !== "run") {
-            throw unknownActionError("version", action, ["run",]);
+        case "batch": {
+            if (plan)
+                return { action, result: batchPlan(flags), exitCode: 0, };
+            const { result, exitCode, } = await runBatch(flags);
+            return { action, result, exitCode, };
         }
-        currentCommandContext.action = action ?? "run";
-        return { action: "run", result: cliVersionResult(), exitCode: 0, };
+        default:
+            return { action, result: await commandsRunResult(flags), exitCode: 0, };
     }
-    if (resource === "cleanup") {
-        await loadCommandRuntime();
-        if (action !== undefined && action !== "run") {
-            throw unknownActionError("cleanup", action, ["run",]);
-        }
-        currentCommandContext.action = action ?? "run";
-        if (executionMode(flags).plan) {
-            return { action: "run", result: cleanupPlan(flags), exitCode: 0, };
+}
+async function commandsRunResult(flags) {
+    const selectors = commandRegistrySelectors(flags);
+    const outputPath = flags["output"];
+    if (selectors.length === 0 && typeof outputPath !== "string") {
+        return contract.commandActionSummary();
+    }
+    const registry = selectors.length === 0 ? contract.buildCommandRegistry() : {};
+    for (const selector of selectors) {
+        const selectorParts = selector.split(".");
+        if (selectorParts.some((part) => part.length === 0)) {
+            throw new UsageError(`Invalid --fields selector: ${selector}. Expected RESOURCE or RESOURCE.ACTION[.FIELD...].`, "usage_error", contract.COMMANDS_USAGE, { selector, });
         }
-        const { 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",]);
+        const [selectedResource, selectedAction,] = selectorParts;
+        const resourceActions = cachedCommandRegistry(selectedResource);
+        if (!resourceActions)
+            throw unknownResourceError(selectedResource);
+        registry[selectedResource] = resourceActions;
+        if (selectedAction && !resourceActions[selectedAction]) {
+            throw unknownActionError(selectedResource, selectedAction, Object.keys(resourceActions));
         }
-        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 (executionMode(flags).plan) {
-            return { action: "run", result: batchPlan(flags), exitCode: 0, };
-        }
-        const { result, exitCode, } = await runBatch(flags);
-        return { action: "run", result, exitCode, };
+    const selectedRegistry = selectors.length === 0
+        ? registry
+        : 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");
+        return { path: outputPath, };
     }
-    return undefined;
+    return selectedRegistry;
 }
 /**
  * Cleanup-ledger support is checked before a handler runs so an unsupported
@@ -993,9 +865,7 @@ async function runBatch(flags) {
     if (executionMode(flags).dryRun) {
         const batchProjectKey = typeof flags["project-key"] === "string"
             ? flags["project-key"]
-            : dataikuEnvironmentEnabled()
-                ? process.env.DATAIKU_PROJECT_KEY
-                : undefined;
+            : ambientProjectKey();
         const planned = await Promise.all(steps.map(async (argv, index) => {
             const context = batchStepCommandContext(argv);
             Object.assign(currentCommandContext, { ...context, projectKey: batchProjectKey, });
@@ -1018,7 +888,8 @@ async function runBatch(flags) {
                 };
             }
             catch (error) {
-                const envelope = buildErrorReport(error);
+                // Steps validate concurrently; the shared context may belong to a sibling.
+                const envelope = buildErrorReport(error, { ...context, projectKey: batchProjectKey, });
                 return {
                     index,
                     args: redactArgv(argv),
@@ -1037,9 +908,7 @@ async function runBatch(flags) {
     validateBatchStepModes(steps);
     let projectKey = typeof flags["project-key"] === "string"
         ? flags["project-key"]
-        : dataikuEnvironmentEnabled()
-            ? process.env.DATAIKU_PROJECT_KEY
-            : undefined;
+        : ambientProjectKey();
     let client;
     const needsClient = steps.some((argv) => batchStepNeedsClient(argv));
     if (needsClient) {
@@ -1247,8 +1116,7 @@ function rawFlagValue(argv, flagName) {
 function commandIsProjectScoped(resource, action) {
     if (!resource)
         return false;
-    const usage = commands[resource]?.[action ?? ""]?.usage ?? "";
-    return inferRequiresProject(resource, action ?? "", usage);
+    return inferRequiresProject(resource, action ?? "");
 }
 function rawCommandContext() {
     const argv = process.argv.slice(2);
@@ -1256,15 +1124,13 @@ function rawCommandContext() {
     const resource = currentCommandContext.resource ?? positionals[0];
     const action = currentCommandContext.action ?? positionals[1];
     const explicitProjectKey = rawFlagValue(argv, "project-key") ?? rawFlagValue(argv, "project");
-    const ambientProjectKey = dataikuEnvironmentEnabled()
-        ? process.env.DATAIKU_PROJECT_KEY
-        : undefined;
+    const environmentProjectKey = ambientProjectKey();
     return {
         resource,
         action,
         projectKey: explicitProjectKey
             ?? (commandIsProjectScoped(resource, action)
-                ? currentCommandContext.projectKey ?? ambientProjectKey
+                ? currentCommandContext.projectKey ?? environmentProjectKey
                 : undefined),
     };
 }
@@ -1364,7 +1230,6 @@ function dssDiagnosticDetails(err) {
         return {};
     }
 }
-const MISSING_PROJECT_KEY_ERROR_PREFIX = "projectKey is required";
 function isAmbiguousMutationFailure(err, context) {
     if (!(err instanceof DataikuError))
         return false;
@@ -1399,9 +1264,15 @@ function boundedFailureResult(result) {
 function errorExitCode(err) {
     if (err instanceof CommandResultFailure)
         return err.exitCode;
-    if (err instanceof ClientValidationError && err.code === "assertion_failed")
+    if (err instanceof ClientValidationError
+        && (err.code === "assertion_failed" || err.code === "long_running_failure"))
         return 4;
-    if (err instanceof ClientValidationError && err.code === "ambiguous_outcome")
+    if (err instanceof ClientValidationError
+        && (err.code === "ambiguous_outcome" || err.code === "internal_error"))
+        return 2;
+    // A permission/environment refusal is not a usage error (exit 1 is usage only).
+    if ((err instanceof UsageError || err instanceof ClientValidationError)
+        && err.code === "target_absence_unverifiable")
         return 2;
     if (err instanceof UsageError || err instanceof ClientValidationError)
         return 1;
@@ -1409,15 +1280,14 @@ function errorExitCode(err) {
         return 2;
     if (err instanceof DataikuError)
         return err.category === "transient" ? 3 : 2;
-    if (err instanceof Error && err.message.startsWith(MISSING_PROJECT_KEY_ERROR_PREFIX))
-        return 1;
     return 2;
 }
-function buildErrorReport(err) {
-    const context = rawCommandContext();
+function buildErrorReport(err, contextOverride) {
+    const context = contextOverride ?? rawCommandContext();
     const exitCode = errorExitCode(err);
     if (err instanceof ClientValidationError
-        && (err.code === "ambiguous_outcome" || err.code === "assertion_failed")) {
+        && (err.code === "ambiguous_outcome" || err.code === "assertion_failed"
+            || err.code === "long_running_failure")) {
         return {
             type: "error",
             ok: false,
@@ -1439,7 +1309,9 @@ function buildErrorReport(err) {
             code: err.code,
             category: err.code === "target_absence_unverifiable"
                 ? "permission_or_environment"
-                : "usage",
+                : err.code === "internal_error"
+                    ? "internal"
+                    : "usage",
             exitCode,
             ...(err.code === "target_absence_unverifiable" ? { retryable: false, } : {}),
             ...(err.hint ? { hint: err.hint, } : {}),
@@ -1517,18 +1389,6 @@ function buildErrorReport(err) {
             ...context,
         };
     }
-    if (err instanceof Error && err.message.startsWith(MISSING_PROJECT_KEY_ERROR_PREFIX)) {
-        return {
-            type: "error",
-            ok: false,
-            error: err.message,
-            code: "missing_required_flag",
-            category: "usage",
-            exitCode,
-            hint: "Pass --project-key or set DATAIKU_PROJECT_KEY.",
-            ...context,
-        };
-    }
     const message = err instanceof Error ? err.message : String(err);
     return {
         type: "error",
@@ -1579,9 +1439,7 @@ async function main() {
         action: positional[1],
         projectKey: typeof flags["project-key"] === "string"
             ? flags["project-key"]
-            : dataikuEnvironmentEnabled()
-                ? process.env.DATAIKU_PROJECT_KEY
-                : undefined,
+            : ambientProjectKey(),
     });
     const metaCommand = await runMetaCommand(resource, positional[1], flags);
     if (metaCommand) {

package/dist/src/client.d.ts

@@ -118,7 +118,7 @@ export interface DataikuClientConfig {
     projectKey?: string;
     /** Request/header timeout and buffered-body budget; idle timeout per raw stream read (default 30 000 ms). */
     requestTimeoutMs?: number;
-    /** Max retry attempts for idempotent requests (default 4, capped at 10) */
+    /** Maximum total attempts, initial request included, for idempotent requests (default 4, capped at 10; 1 = no retry) */
     retryMaxAttempts?: number;
     /**
      * Maximum bytes retained from a single response body by text/JSON consumers
@@ -336,6 +336,7 @@ export declare class DataikuClient {
     stream(path: string): Promise<Response>;
     /** Bound each pending read, not total transfer time; preserve large downloads and backpressure. */
     private withBodyDeadline;
+    /** JSON request headers; Content-Type only when a body is sent. */
     private getHeaders;
     private getAnyHeaders;
     private responseMeta;