dataiku-sdk 3.1.0 → 3.2.0

package/dist/src/cli/commands/scenario.js

@@ -1,5 +1,6 @@
 import { scenarioUpdatePreview, } from "../../resources/scenarios.js";
 import { jsonInput, num, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const scenarioCommands = {
@@ -26,7 +27,7 @@ export const scenarioCommands = {
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
                 timeoutMs: num(f["timeout"], "--timeout"),
             };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "run",
@@ -54,7 +55,7 @@ export const scenarioCommands = {
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
                 timeoutMs: num(f["timeout"], "--timeout"),
             };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "run-and-wait",
@@ -87,11 +88,11 @@ export const scenarioCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss scenario delete <id>");
             const pk = f["project-key"];
-            if (f["dry-run"] === true || f["if-exists"] === true) {
+            if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.scenarios.get(a[0], { projectKey: pk, }));
                 if (!current)
                     return skipResult("scenario", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "scenario", id: a[0], current, };
                 }
             }
@@ -112,13 +113,13 @@ export const scenarioCommands = {
                 scenarioType: f["type"],
                 projectKey: pk,
             };
-            if (f["if-not-exists"] === true || f["dry-run"] === true) {
+            if (f["if-not-exists"] === true || executionMode(f).dryRun) {
                 const list = await c.scenarios.list(pk);
                 const existing = list.find((s) => s.id === a[0]);
-                if (existing && f["if-not-exists"] === true && f["dry-run"] !== true) {
+                if (existing && f["if-not-exists"] === true && !executionMode(f).dryRun) {
                     return skipResult("scenario", a[0], "exists", { current: existing, });
                 }
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "create",
@@ -150,7 +151,7 @@ export const scenarioCommands = {
                 throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin]");
             }
             const pk = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.scenarios.get(a[0], { projectKey: pk, });
                 const preview = scenarioUpdatePreview(current, data);
                 return {

package/dist/src/cli/commands/sql.js

@@ -1,6 +1,7 @@
 import { readFileSync, } from "node:fs";
-import { mkdir, writeFile, } from "node:fs/promises";
+import { mkdir, } from "node:fs/promises";
 import { dirname, resolve, } from "node:path";
+import { writeResponseToFile, } from "../../utils/response-file.js";
 import { readStdinText, stripUtf8Bom, } from "../coerce.js";
 import { enqueueCliWarning, } from "../output.js";
 import { UsageError, } from "../usage.js";
@@ -121,7 +122,7 @@ export const sqlCommands = {
             }
             const outputPath = resolve(outputFile);
             await mkdir(dirname(outputPath), { recursive: true, });
-            await writeFile(outputPath, `${JSON.stringify(result, null, 2)}\n`, "utf-8");
+            await writeResponseToFile(outputPath, new Response(`${JSON.stringify(result, null, 2)}\n`), "preserve");
             return {
                 queryId: result.queryId,
                 schema: result.schema,

package/dist/src/cli/commands/statistics.js

@@ -1,4 +1,5 @@
 import { requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, planResult, } from "../output.js";
 import { requireArgs, } from "../usage.js";
 const STATISTICS_PLAN_EXIT_CODES = { usage: 1, error: 2, transient: 3, };
@@ -51,7 +52,7 @@ export const statisticsCommands = {
             requireArgs(a, 1, "dss statistics create-worksheet <dataset> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (worksheet definition).");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("create-worksheet", {
                     method: "POST",
                     endpoint: statisticsWorksheetsEndpoint(c, a[0], projectKey),
@@ -72,7 +73,7 @@ export const statisticsCommands = {
             requireArgs(a, 2, "dss statistics update-worksheet <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (worksheet definition).");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("update-worksheet", {
                     method: "PUT",
                     endpoint: statisticsWorksheetEndpoint(c, a[0], a[1], projectKey),
@@ -90,7 +91,7 @@ export const statisticsCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 2, "dss statistics delete-worksheet <dataset> <worksheetId> [--dry-run] [--project-key KEY]");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("delete-worksheet", {
                     method: "DELETE",
                     endpoint: statisticsWorksheetEndpoint(c, a[0], a[1], projectKey),
@@ -108,7 +109,7 @@ export const statisticsCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 2, "dss statistics run-worksheet <dataset> <worksheetId> [--dry-run] [--project-key KEY]");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("run-worksheet", {
                     method: "POST",
                     endpoint: `${statisticsWorksheetEndpoint(c, a[0], a[1], projectKey)}/actions/run-card`,
@@ -127,7 +128,7 @@ export const statisticsCommands = {
             requireArgs(a, 2, "dss statistics run-card <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
             const card = requiredJsonInput(f, "--data, --data-file, or --stdin is required (card settings).");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("run-card", {
                     method: "POST",
                     endpoint: `${statisticsWorksheetEndpoint(c, a[0], a[1], projectKey)}/actions/run-card`,
@@ -147,7 +148,7 @@ export const statisticsCommands = {
             requireArgs(a, 2, "dss statistics run-computation <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
             const computation = requiredJsonInput(f, "--data, --data-file, or --stdin is required (computation settings).");
             const projectKey = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return statisticsPlan("run-computation", {
                     method: "POST",
                     endpoint: `${statisticsWorksheetEndpoint(c, a[0], a[1], projectKey)}/actions/run-computation`,

package/dist/src/cli/commands/variable.js

@@ -1,4 +1,5 @@
 import { json, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { UsageError, } from "../usage.js";
 export const variableCommands = {
     get: {
@@ -15,7 +16,7 @@ export const variableCommands = {
             if (standard === undefined && local === undefined) {
                 throw new UsageError("--standard and/or --local is required.");
             }
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.variables.get(pk);
                 const next = f["replace"] === true
                     ? { standard: standard ?? {}, local: local ?? {}, }

package/dist/src/cli/commands/webapp.js

@@ -2,6 +2,7 @@ import { ClientValidationError, } from "../../errors.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { stableHash, } from "../../utils/stable-hash.js";
 import { num, requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { requireArgs, } from "../usage.js";
 const UPDATE_SETTINGS_USAGE = "dss webapp update-settings <webappId> (--data JSON|--data-file PATH|--stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]";
 const RESTART_USAGE = "dss webapp restart-backend <webappId> [--wait] [--timeout MS] [--poll-interval MS] [--project-key KEY]";
@@ -44,7 +45,7 @@ export const webappCommands = {
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (webapp settings).");
             const projectKey = f["project-key"];
             const expectHash = validateExpectHash(f["expect-hash"]);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.webapps.getSettings(a[0], projectKey);
                 const currentHash = stableHash(current);
                 if (expectHash !== undefined && currentHash !== expectHash.toLowerCase()) {

package/dist/src/cli/commands/wiki.js

@@ -1,5 +1,6 @@
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { jsonInput, textInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const wikiCommands = {
@@ -31,12 +32,12 @@ export const wikiCommands = {
                 throw new UsageError("--name is required. Usage: dss wiki create --name NAME");
             const content = textInput(f);
             const pk = f["project-key"];
-            if (f["if-not-exists"] === true || f["dry-run"] === true) {
+            if (f["if-not-exists"] === true || executionMode(f).dryRun) {
                 const existing = (await c.wiki.list(pk)).find((article) => article.article.name === name);
-                if (existing && f["if-not-exists"] === true && f["dry-run"] !== true) {
+                if (existing && f["if-not-exists"] === true && !executionMode(f).dryRun) {
                     return skipResult("wiki", existing.article.id, "exists", { current: existing, });
                 }
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "create",
@@ -75,7 +76,7 @@ export const wikiCommands = {
             if (!data && content === undefined && name === undefined) {
                 throw new UsageError("--name, --content, --file, --data, --data-file, or --stdin is required.");
             }
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.wiki.get(a[0], f["project-key"]);
                 const next = deepMerge(current, data ?? {});
                 if (name !== undefined) {
@@ -105,11 +106,11 @@ export const wikiCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss wiki delete <id-or-name>");
             const pk = f["project-key"];
-            if (f["dry-run"] === true || f["if-exists"] === true) {
+            if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.wiki.get(a[0], pk));
                 if (!current)
                     return skipResult("wiki", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "wiki", article: a[0], current, };
                 }
             }

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

@@ -103,7 +103,7 @@ export declare function inferRequiresProject(resource: string, action: string, u
 export declare function inferInputContract(usage: string): CommandInputContract;
 export declare function supportsCleanupLedger(resource: string, action: string): boolean;
 export declare function inferCleanupHint(resource: string, action: string): string | undefined;
-export declare function buildCommandRegistry(): Record<string, Record<string, CommandRegistryEntry>>;
+export declare function buildCommandRegistry(resourceFilter?: string): Record<string, Record<string, CommandRegistryEntry>>;
 export declare function agentContractJsonSchema(): Record<string, unknown>;
 export declare function commandActionSummary(registry: Record<string, Record<string, CommandRegistryEntry>>): Record<string, string[]>;
 export declare function buildAgentContract(): Record<string, unknown>;

package/dist/src/cli/contract.js

@@ -13,7 +13,7 @@ import { commands, } from "./commands/index.js";
 import { projectLibraryPutPayload, } from "./commands/project-library.js";
 import { resolveSqlQueryInvocation, } from "./commands/sql.js";
 import { dataikuEnvironmentEnabled, } from "./env.js";
-import { BOOLEAN_FLAGS, FLAG_ALIASES, KNOWN_LONG_FLAGS, SHORT_FLAGS, } from "./flags.js";
+import { BOOLEAN_FLAGS, executionMode, FLAG_ALIASES, KNOWN_LONG_FLAGS, SHORT_FLAGS, } from "./flags.js";
 import { flowZoneColor, flowZoneMoveItems, flowZoneName, } from "./helpers/flow-zone.js";
 import { recipeBackupPath, recipeRunShouldWait, } from "./helpers/recipe.js";
 import { encodedProjectEndpointForPlan, planResult, } from "./output.js";
@@ -749,11 +749,11 @@ function unsafeOutputs(resource, action, producesLocalFile) {
             condition: "--output or --output-file",
             kind: "local-file",
             detail: sensitivePermissions
-                ? "Command writes access-control identities and permissions to an owner-only local file."
-                : "Command writes bytes to a local path and returns JSON metadata on stdout.",
+                ? "Writes access-control identities and permissions to an owner-only local file."
+                : "Writes a local file; stdout contains JSON metadata.",
             ...(sensitivePermissions
                 ? {
-                    safeAlternative: "Keep the file owner-only and outside version control unless repository policy explicitly permits committing access-control data.",
+                    safeAlternative: "Keep owner-only and outside version control unless repository policy explicitly permits committing access-control data.",
                 }
                 : {}),
         });
@@ -1293,10 +1293,10 @@ export function inferCleanupHint(resource, action) {
         return undefined;
     const key = `${resource}.${action}`;
     if (key === "notebook.save-jupyter") {
-        return "When the save reports created:true, delete with `dss notebook delete-jupyter <name> --if-exists`.";
+        return "If created:true, delete with `dss notebook delete-jupyter <name> --if-exists`.";
     }
     if (key === "notebook.save-sql") {
-        return "When the save reports created:true, delete with `dss notebook delete-sql <id> --if-exists`.";
+        return "If created:true, delete with `dss notebook delete-sql <id> --if-exists`.";
     }
     if (!(action.startsWith("create") || action === "clone"))
         return undefined;
@@ -1317,7 +1317,7 @@ export function inferCleanupHint(resource, action) {
     if (resource === "data-quality") {
         return `Delete with \`dss data-quality delete-rule <dataset> <rule-id>${ifExists}\`.`;
     }
-    return `Delete with \`dss ${resource} delete <id>${ifExists}\` when the created object is disposable.`;
+    return `For disposable creates: \`dss ${resource} delete <id>${ifExists}\`.`;
 }
 function buildRegistryEntry(resource, action, meta) {
     const requiresAuth = meta.localHandler === undefined && inferRequiresAuth(resource);
@@ -1427,81 +1427,99 @@ function buildRegistryEntry(resource, action, meta) {
         agentContractVersion: AGENT_CONTRACT_VERSION,
     };
 }
-export function buildCommandRegistry() {
+export function buildCommandRegistry(resourceFilter) {
     const registry = {};
     for (const [resource, actions,] of Object.entries(commands)) {
+        if (resourceFilter !== undefined && resource !== resourceFilter)
+            continue;
         registry[resource] = {};
         for (const [action, meta,] of Object.entries(actions)) {
             registry[resource][action] = buildRegistryEntry(resource, action, meta);
         }
     }
-    registry.commands = {
-        run: buildRegistryEntry("commands", "run", {
-            handler: async () => undefined,
-            usage: COMMANDS_USAGE,
-            description: COMMANDS_DESCRIPTION,
-            examples: COMMANDS_EXAMPLES,
-        }),
-    };
-    registry.agent = {
-        contract: buildRegistryEntry("agent", "contract", {
-            handler: async () => undefined,
-            usage: AGENT_CONTRACT_USAGE,
-            description: AGENT_CONTRACT_DESCRIPTION,
-            examples: AGENT_CONTRACT_EXAMPLES,
-        }),
-    };
-    registry.version = {
-        run: buildRegistryEntry("version", "run", {
-            handler: async () => undefined,
-            usage: VERSION_USAGE,
-            description: VERSION_DESCRIPTION,
-            examples: VERSION_EXAMPLES,
-        }),
-    };
-    registry["install-skill"] = {
-        run: buildRegistryEntry("install-skill", "run", {
-            handler: async () => undefined,
-            usage: INSTALL_SKILL_USAGE,
-            description: INSTALL_SKILL_DESCRIPTION,
-            examples: INSTALL_SKILL_EXAMPLES,
-        }),
-    };
-    registry.cleanup = {
-        run: buildRegistryEntry("cleanup", "run", {
-            handler: async () => undefined,
-            usage: CLEANUP_USAGE,
-            description: CLEANUP_DESCRIPTION,
-            examples: CLEANUP_EXAMPLES,
-        }),
-    };
-    registry.fixtures = {
-        run: buildRegistryEntry("fixtures", "run", {
-            handler: async () => undefined,
-            usage: FIXTURES_USAGE,
-            description: FIXTURES_DESCRIPTION,
-            examples: FIXTURES_EXAMPLES,
-        }),
-    };
-    registry.batch = {
-        run: buildRegistryEntry("batch", "run", {
-            handler: async () => undefined,
-            usage: BATCH_USAGE,
-            description: BATCH_DESCRIPTION,
-            examples: BATCH_EXAMPLES,
-            examplePayload: BATCH_EXAMPLE_PAYLOAD,
-            payloadSchema: { stdin: true, dataFlag: true, dataFileFlag: true, jsonShape: "array", },
-        }),
-    };
-    registry.auth = {};
-    for (const [action, meta,] of Object.entries(AUTH_ACTIONS)) {
-        registry.auth[action] = buildRegistryEntry("auth", action, {
-            handler: async () => undefined,
-            usage: meta.usage,
-            description: meta.description,
-            examples: meta.examples,
-            requiredFlags: meta.requiredFlags,
-        });
+    if (resourceFilter === undefined || resourceFilter === "commands") {
+        registry.commands = {
+            run: buildRegistryEntry("commands", "run", {
+                handler: async () => undefined,
+                usage: COMMANDS_USAGE,
+                description: COMMANDS_DESCRIPTION,
+                examples: COMMANDS_EXAMPLES,
+            }),
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "agent") {
+        registry.agent = {
+            contract: buildRegistryEntry("agent", "contract", {
+                handler: async () => undefined,
+                usage: AGENT_CONTRACT_USAGE,
+                description: AGENT_CONTRACT_DESCRIPTION,
+                examples: AGENT_CONTRACT_EXAMPLES,
+            }),
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "version") {
+        registry.version = {
+            run: buildRegistryEntry("version", "run", {
+                handler: async () => undefined,
+                usage: VERSION_USAGE,
+                description: VERSION_DESCRIPTION,
+                examples: VERSION_EXAMPLES,
+            }),
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "install-skill") {
+        registry["install-skill"] = {
+            run: buildRegistryEntry("install-skill", "run", {
+                handler: async () => undefined,
+                usage: INSTALL_SKILL_USAGE,
+                description: INSTALL_SKILL_DESCRIPTION,
+                examples: INSTALL_SKILL_EXAMPLES,
+            }),
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "cleanup") {
+        registry.cleanup = {
+            run: buildRegistryEntry("cleanup", "run", {
+                handler: async () => undefined,
+                usage: CLEANUP_USAGE,
+                description: CLEANUP_DESCRIPTION,
+                examples: CLEANUP_EXAMPLES,
+            }),
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "fixtures") {
+        registry.fixtures = {
+            run: buildRegistryEntry("fixtures", "run", {
+                handler: async () => undefined,
+                usage: FIXTURES_USAGE,
+                description: FIXTURES_DESCRIPTION,
+                examples: FIXTURES_EXAMPLES,
+            }),
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "batch") {
+        registry.batch = {
+            run: buildRegistryEntry("batch", "run", {
+                handler: async () => undefined,
+                usage: BATCH_USAGE,
+                description: BATCH_DESCRIPTION,
+                examples: BATCH_EXAMPLES,
+                examplePayload: BATCH_EXAMPLE_PAYLOAD,
+                payloadSchema: { stdin: true, dataFlag: true, dataFileFlag: true, jsonShape: "array", },
+            }),
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "auth") {
+        registry.auth = {};
+        for (const [action, meta,] of Object.entries(AUTH_ACTIONS)) {
+            registry.auth[action] = buildRegistryEntry("auth", action, {
+                handler: async () => undefined,
+                usage: meta.usage,
+                description: meta.description,
+                examples: meta.examples,
+                requiredFlags: meta.requiredFlags,
+            });
+        }
     }
     return registry;
 }
@@ -1680,7 +1698,7 @@ export function buildAgentContract() {
                 "dss commands run --fields dataset",
                 "dss commands run --fields dataset.create",
             ],
-            scopedDiscoveryHint: "`dss commands run` returns the resource/action summary. --fields RESOURCE returns every action of one resource; --fields RESOURCE.ACTION returns a single registry entry keyed by the dotted path; append .FIELD paths to project nested metadata. Comma-separate paths to select several. Use --output PATH to export the full registry.",
+            scopedDiscoveryHint: "Default: resource/action summary. --fields RESOURCE: all resource entries; RESOURCE.ACTION: one entry keyed by that path; append .FIELD for nested metadata. Comma-separate paths. --output PATH exports the full registry.",
             actions: commandActionSummary(registry),
         },
         schemas: {
@@ -1697,8 +1715,8 @@ export function buildAgentContract() {
                 success: "single-json-value",
                 failure: "structured-error-object",
                 failureResultDetailLimitBytes: 65_536,
-                fieldProjection: "Missing --fields paths stay null on stdout and emit field_projection_missing on stderr.",
-                richFailureResults: "doctor/batch/cleanup nonzero outcomes are their own compact result on stdout ({ok:false,...}) with the command's exit code; not re-wrapped.",
+                fieldProjection: "Missing --fields paths: null on stdout; field_projection_missing on stderr.",
+                richFailureResults: "doctor/batch/cleanup failures: own compact {ok:false,...} result on stdout and command exit code; no wrapper.",
             },
             stderr: {
                 format: "jsonl",
@@ -1715,7 +1733,7 @@ export function buildAgentContract() {
         },
         compatibility: {
             fieldsAreAdditiveWithinMajor: true,
-            failFastWhenUnsupported: "Check agentContractVersion before planning commands.",
+            failFastWhenUnsupported: "Check agentContractVersion before planning.",
         },
     };
 }
@@ -3654,7 +3672,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 wait: true,
             })}`;
             const guarded = flags["if-exists"] === true
-                || flags["dry-run"] === true
+                || executionMode(flags).dryRun
                 || expectedProjectIncarnation !== undefined;
             if (!guarded) {
                 return {
@@ -3671,7 +3689,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                     provided: true,
                     expectedHash: expectedProjectIncarnation,
                 };
-            if (flags["dry-run"] === true) {
+            if (executionMode(flags).dryRun) {
                 return {
                     method: "GET",
                     endpoint: projectProbe,
@@ -4080,7 +4098,7 @@ export function buildMutationPlan(resource, action, meta, args, flags) {
         asyncKind: entry.async,
         exitCodesOnFailure: exitCodesOnFailure(entry),
         idempotency: entry.idempotency,
-        plannedAndDryRun: flags["dry-run"] === true,
+        plannedAndDryRun: executionMode(flags).dryRun,
     });
 }
 /**

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

@@ -1,3 +1,7 @@
+export declare function executionMode(flags: Record<string, string | boolean>): {
+    readonly plan: boolean;
+    readonly dryRun: boolean;
+};
 export declare const BOOLEAN_FLAGS: Set<string>;
 export declare const SHORT_FLAGS: Record<string, string>;
 /** Long-flag aliases: these are normalized to the canonical name in parseArgs. */

package/dist/src/cli/flags.js

@@ -1,4 +1,17 @@
+import { parseBooleanOption, } from "./coerce.js";
 import { unsupportedHelpFlag, UsageError, } from "./usage.js";
+/** Planning wins dispatch; dryRun remains set for combined plan metadata. */
+const EXECUTION_MODES = [
+    Object.freeze({ plan: false, dryRun: false, }),
+    Object.freeze({ plan: false, dryRun: true, }),
+    Object.freeze({ plan: true, dryRun: false, }),
+    Object.freeze({ plan: true, dryRun: true, }),
+];
+export function executionMode(flags) {
+    const plan = parseBooleanOption(flags["plan"], "--plan") ?? false;
+    const dryRun = parseBooleanOption(flags["dry-run"], "--dry-run") ?? false;
+    return EXECUTION_MODES[(plan ? 2 : 0) + (dryRun ? 1 : 0)];
+}
 export const BOOLEAN_FLAGS = new Set([
     "verbose",
     "version",
@@ -273,7 +286,13 @@ export function parseArgs(argv) {
             if (eqIdx !== -1) {
                 const raw = arg.slice(2, eqIdx);
                 const flagName = normalizeLongFlag(raw);
-                setParsedFlagValue(flags, flagName, arg.slice(eqIdx + 1));
+                const value = arg.slice(eqIdx + 1);
+                if (BOOLEAN_FLAGS.has(flagName)) {
+                    flags[flagName] = parseBooleanOption(value, `--${flagName}`);
+                }
+                else {
+                    setParsedFlagValue(flags, flagName, value);
+                }
             }
             else {
                 const rawFlagName = arg.slice(2);