dataiku-sdk 3.1.0 → 3.2.0

package/README.md

@@ -23,12 +23,99 @@ Bun is the only supported runtime and the package manager. Examples below assume
 `--no-env-file` disables Bun's automatic preloading only; the CLI still applies its documented `.env` handling unless `DATAIKU_DISABLE_ENV=1` is set.
 `dss version` reports whether the running code came from `source` or `dist`, the runtime (always `bun`), the packaged build revision when available, and `staleBuild` when that revision differs from the checkout. Release builds generate `dist/build-metadata.json`; source snapshots without Git metadata still build but report no build revision.
 
+## Self-provisioning live tests
+
+From a checkout, `test:live` is a separate Bun script, not a `dss` command. It reads
+the existing `.env` without changing it and needs project-creation access plus a
+writable managed storage connection. No imported tutorials are required.
+
+```sh
+bun run test:live setup
+bun run test:live run --case core.dataset.baseline
+bun run test:live run --case "core.recipe.*"
+bun run test:live run                 # all core cases + migrated integration suites
+bun run test:live run --profile ml --case "ml.*"
+bun run test:live status
+bun run test:live clean               # delete only this lab, including its root project
+# CI: setup + run + cleanup, even when cases fail
+bun run test:live all
+```
+
+`setup` is idempotent for a ready lab; `run` reuses its datasets, graph and collaboration
+fixtures. Cases use temporary resources or restore baseline values. Cases accept exact
+IDs, comma-separated lists, repeated `--case`, and trailing-prefix `*` matching; quote
+wildcards. Selected runs omit the legacy suites. Unknown, setup-only or inactive-profile
+or empty selections fail before credentials, state creation or provisioning; `--case` is valid only
+for `run`/`all`. `run` refuses
+an incomplete or cleaned lab rather than silently rebuilding it. Clean failed setup
+before provisioning a replacement. Authentication and transport failures retain their
+original errors; they are not evidence that the lab is missing.
+
+Core fixtures include deterministic CSVs with nulls, duplicates, Unicode and quoting;
+server-provisioned managed datasets; sync, Prepare, join, fuzzy-join, grouping and Python
+recipes; folders, scenarios, variables, wiki, notebooks, dashboards, insights, libraries,
+metrics and quality rules. Project export/import/duplicate cases use separate owned
+projects. Managed dataset types, paths and recipe output schemas come from DSS rather
+than tutorial-specific connection guesses.
+
+Profiles add to core: `ml` trains and deploys a small decision tree and checks clustering;
+`applications` requires `DATAIKU_LIVE_APP_TEMPLATE_ID`; `infrastructure` requires
+`DATAIKU_SQL_CONNECTION` or `DATAIKU_SQL_DATASET_FULL_NAME` for read-only SQL.
+The SQL case permits only the fixed, table-free `SELECT 1 AS one` probe with an
+explicit target and an owned project whose incarnation is checked before execution.
+It does not authorize arbitrary SQL, alternate query inputs or global mutations. Missing
+prerequisites are recorded as **blocked**, never passed. Required blocked cases exit
+nonzero; optional blocked cases remain visible in reports. Global administration,
+external Git mutations and unsupported capabilities are not silently exercised.
+
+For an admin-only disposable SQL target (verified on the hosted trial), create a uniquely
+named connection with `POST /public/api/admin/connections/` and body
+`{"name":"<unique-name>","type":"JDBC","params":{"driver":"org.sqlite.JDBC","jdbcurl":"jdbc:sqlite::memory:","properties":[]},"usableBy":"ALLOWED","allowedGroups":[],"allowWrite":false,"allowManagedDatasets":false}`.
+Run `DATAIKU_SQL_CONNECTION=<name> bun run test:live all --profile infrastructure --case infrastructure.sql-select`.
+In a `finally` block, verify that the connection still matches the created definition, then
+remove it with `DELETE /public/api/admin/connections/<name>`. `all` cleans the owned projects,
+not this separately created connection. The in-memory database creates no database file.
+
+State is ignored by Git under `.live-tests/<server-hash>/`. Use `--state-dir PATH` for
+another lab or `--manifest PATH` to select an existing manifest for `run`, `clean` or
+`status` (not `setup`/`all`). Keep the manifest and
+`cleanup.jsonl`: cleanup requires exact project identities and creation-incarnation
+hashes, never a prefix sweep. A changed server/project identity or unconfirmed creation
+fails closed; investigate its journal before manual recovery. Locks prevent concurrent
+lab runs; after an uncatchable process kill, confirm its recorded process is gone before
+removing a stale lock. Interrupting a run preserves the lab; `all` attempts cleanup.
+
+Each iteration retains logs and `report.json` with cases, timing, executed actions,
+capability reasons, coverage and external-project metadata integrity. Unavailable project
+metadata is reported separately in `integrity.unreadable`, not as confirmed drift;
+integrity remains unverified and the run fails until those reads succeed. `clean` retains
+`cleanup-report.json`, including deletion failures; starting teardown invalidates lab
+readiness even if cleanup only partially succeeds. If cleanup and integrity verification
+both fail, the cleanup error remains primary and the report preserves both results.
+Planned lifecycle commands retain ownership checks; local outputs stay inside the lab
+for both `--output` and `--output-file`. Treat local reports and exported archives as private project
+data. Coverage is an explicit inventory of every registered action, not a claim that
+every action has a live test: unexercised actions remain **uncovered**. Add cases through
+the typed catalogue in `tests/live-cases.ts`, `LiveContext.check` and guarded helpers,
+then update `tests/live-coverage.ts` when the
+registry changes; catalogue drift fails the offline gate. Plan/dry-run calls do not count
+as executed live coverage.
+
+Regular `bun run check` and `bun run lint` include the live runner and fixtures.
+For focused verification:
+
+```sh
+bun run check:live
+bun test tests/live-context.test.ts tests/live-runner.test.ts tests/live-coverage.test.ts
+```
+
 ## CLI contract
 
 The complete agent-facing contract — stdout JSON discipline, stderr JSONL diagnostics, the error
 envelope, exit codes, `--fields` projection, command discovery, and planning/safety rules — is the
-canonical skill at [`skills/dataiku-dss/SKILL.md`](skills/dataiku-dss/SKILL.md); keep that file as
-the single source of truth for agent integrations and for the `dss install-skill` payload. Human
+skill bundle rooted at [`skills/dataiku-dss/SKILL.md`](skills/dataiku-dss/SKILL.md). The short
+entrypoint routes agents to focused references; the installed command registry remains the source
+of truth for command syntax and schemas. Human
 essentials: exactly one compact JSON value on stdout per command (void success is `{ok:true}`),
 failures as one structured JSON error object on stdout with a nonzero exit code, stderr reserved
 for JSONL diagnostics only, and exit codes `0` success / `1` usage error / `2` DSS or internal
@@ -46,8 +133,7 @@ dss commands run --output commands.json
 dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility
 ```
 
-`dss commands run` prints the compact resource/action summary; registry entries (~220k tokens
-exported) never dump to stdout — they travel only via `--output PATH`. See the canonical skill for
+`dss commands run` prints the compact resource/action summary; registry entries never dump to stdout — they travel only via `--output PATH`. See the canonical skill for
 the full `--fields` projection rules and planning workflow.
 
 ## Agent skill installation
@@ -61,7 +147,7 @@ dss install-skill --global --agent omp
 
 `--list-agents` only reports targetable agents; it does not write files. Auto-detection checks supported agent binaries/config directories (`claude`, `codex`, `cursor`, `pi`, `omp`). Passing `--agent NAME` forces one entry and reports `via:"flag"`.
 
-Project installs write `SKILL.md` under the target workspace:
+Project installs write `SKILL.md` and its sibling `references/` directory under the target workspace:
 
 - Claude: `.claude/skills/dataiku-dss/SKILL.md`
 - Codex: `.codex/skills/dataiku-dss/SKILL.md`
@@ -69,16 +155,42 @@ Project installs write `SKILL.md` under the target workspace:
 - Pi: `.pi/skills/dataiku-dss/SKILL.md`
 - OMP: `.omp/skills/dataiku-dss/SKILL.md`
 
-Global installs write under the agent's home config path, for example OMP: `~/.omp/agent/skills/dataiku-dss/SKILL.md`.
+Global installs write under the agent's home config path, for example OMP: `~/.omp/agent/skills/dataiku-dss/SKILL.md`. The reported `target` is the home directory for global installs and the resolved workspace directory for project installs; `installed[].path` names each entrypoint.
+
+Each entry in the `installed` array reports pre-install bundle state:
+
+- `status`: `missing` when the entrypoint is absent; `stale` when any bundled file is missing or differs; `current` when every bundled file matches.
+- `changed`: whether any bundled file would (or did) change. Byte-identical files are not rewritten.
+- `expectedSha256` and `actualSha256`: the canonical and existing **entrypoint** hashes. The latter is absent when the entrypoint is missing.
+- `files`: each bundled file's portable `relativePath`, destination `path`, `status`, `changed`, and hashes. Missing or stale references are detected even when `SKILL.md` itself is current.
+
+`--dry-run` and `--plan` never write. Real installs replace changed files through same-directory temporary files and rename, writing references before the entrypoint. Atomicity is per file, not a bundle-wide transaction. Unrelated files in the destination are preserved.
+
+### Token-efficient skill structure
+
+The entrypoint contains bootstrap/discovery, output interpretation, and universal safety rules. Seven focused files under [references/](skills/dataiku-dss/references/) cover authentication, discovery, mutations, application releases, flow maps, coding, and troubleshooting. All are linked directly from `SKILL.md` with task-specific read conditions; agents should not preload the whole directory.
+
+The entrypoint measures **750 o200k_base tokens**, down from **851** in the previous revision (12% less) and **4,272** before progressive disclosure. The token-budget test now caps it at **825** tokens. Claude V5 reconstruction counts fell **1,420 → 1,250** and GLM5 **858 → 752**. Safety rules and all seven reference links remain. Reference content consumes context only when read; all five agent installers ship the complete bundle.
+
+All seven references are token-budgeted (each measured `o200k_base` baseline plus 5% headroom). Per-file baselines live in [the token-budget tests](tests/cli/agent-token-budget.test.ts); run `bun run test:tokens` to check them.
+
+References total **4,179 → 3,545 tokens (15.2% less)**. With the 750-token entrypoint, the whole bundle totals **4,295**; this is a sum of file counts, not a recommendation to preload them. All references shrink across ten encodings; whole-bundle Claude V5 reconstruction **8,200 → 7,362**, GLM5 **4,943 → 4,305**. Runnable examples and safety conditions are retained.
+
+This uses progressive disclosure from the [Agent Skills specification](https://agentskills.io/specification) and [Anthropic's authoring guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): concise metadata/instructions, direct relative reference links, and domain-focused documents. No scripts or assets are needed here; generated command metadata is queried from the CLI rather than duplicated in the skill.
+
+`bun run test:tokens` enforces the pinned OpenAI `o200k_base` budgets. To also check ten native encodings (OpenAI, Claude, GLM, Qwen, DeepSeek, and Kimi), point the optional development-only gate at an OMP native module:
+
+```bash
+DSS_TOKENIZER_MODULE=/absolute/path/to/oh-my-pi/packages/natives/native/index.js bun run test:tokens
+```
+
+Without this variable, only the native cross-model case is skipped. A configured missing/incompatible module fails rather than estimating tokens. The cross-model gate permits 10% growth over its recorded text baselines for bootstrap and action discovery; the pinned OpenAI gate also enforces the skill ceiling above. Claude counts use ctok reconstructions, not an official tokenizer, and all counts exclude provider message/tool framing. No native dependency is added to the CLI.
 
-Each entry in the `installed` array reports deterministic file state:
+Measured full `dataset.create` discovery versus its `usage,description,flags,examples` projection: OpenAI **1,059 → 356**, Claude V5 reconstruction **1,771 → 640**, GLM5 **1,015 → 347** tokens. Use the projection when those fields suffice; fetch the full action when schema details are needed. This is selective disclosure, not lossless compression.
 
-- `status`: `missing` (no file at the destination), `stale` (file present but bytes differ from the canonical skill), or `current` (byte-identical to the canonical skill).
-- `changed`: whether the install writes the file — `true` for `missing` and `stale`, `false` for `current`; installs skip byte-identical files and replace missing/stale files through a same-directory temporary file followed by rename.
-- `expectedSha256`: SHA-256 of the canonical skill bytes this SDK ships.
-- `actualSha256`: SHA-256 of the file currently at the destination; present only when the file exists.
+Boolean flags accept bare flags or explicit `=true`/`=false` values, including aliases. Invalid boolean values fail before dispatch. Direct, batch, and local commands share execution-mode resolution; `--plan --dry-run` returns a plan with `plannedAndDryRun:true` when both modes are supported. Unreadable JSON/text payload files produce `validation_failed` usage errors (exit 1) with the flag, path, and filesystem cause.
 
-`--dry-run` and `--plan` never write; they report the same `status`/`changed`/hash fields so you can see which copies a real install would refresh — a `stale` copy is detected and would be refreshed, while a `current` copy is already byte-identical and needs no refresh.
+For raw streaming downloads, `--request-timeout MS` bounds each pending body read, not the total transfer duration: large progressing transfers remain supported. Buffered text/JSON consumers retain their bounded body-read budget. Request retries do not replay partially consumed streams. Project, bundle, and API-service archives and managed-folder downloads are written to private temporary files beside the destination, then renamed on success. Failures leave no partial output and preserve any existing destination.
 
 ## Credentials
 

package/dist/build-metadata.json

@@ -1 +1 @@
-{"format":1,"buildRevision":"ceeb399ea1f0d7ea078db09da940b79fb732e2ad"}
+{"format":1,"buildRevision":"aa9d13ec085be8f8637265cabcc8466df4817c88"}

package/dist/src/auth.js

@@ -1,7 +1,7 @@
-import { DataikuClient, } from "./client.js";
 import { DataikuError, } from "./errors.js";
 export async function validateCredentials(url, apiKey, options = {}) {
     try {
+        const { DataikuClient, } = await import("./client.js");
         const client = new DataikuClient({
             url,
             apiKey,

package/dist/src/cli/coerce.js

@@ -169,6 +169,15 @@ function selectSingleSource(flags, sourceFlags) {
     }
     return provided[0];
 }
+function readInputText(path, flag) {
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch (error) {
+        const cause = error.code;
+        throw new UsageError(`Could not read ${flag} file: ${path}`, "validation_failed", "Verify that the path names an existing, readable file.", { flag, path, ...(cause ? { cause, } : {}), });
+    }
+}
 function resolveJsonSourceText(flags, kind) {
     const source = selectSingleSource(flags, JSON_SOURCE_FLAGS);
     if (source === undefined)
@@ -182,7 +191,7 @@ function resolveJsonSourceText(flags, kind) {
     if (source === "data-file") {
         const fileValue = flags["data-file"];
         if (typeof fileValue === "string") {
-            const jsonText = readFileSync(fileValue, "utf-8");
+            const jsonText = readInputText(fileValue, "--data-file");
             return kind === "object"
                 ? parseJsonObject(jsonText, fileValue)
                 : parseJsonValue(jsonText, fileValue);
@@ -241,7 +250,7 @@ export function textInput(flags) {
     if (source === "file") {
         const fileValue = flags["file"];
         if (typeof fileValue === "string")
-            return readFileSync(fileValue, "utf-8");
+            return readInputText(fileValue, "--file");
     }
     const contentValue = flags["content"];
     if (typeof contentValue === "string")

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

@@ -1,4 +1,5 @@
 import { requiredStringFlag, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
 import { requireArgs, } from "../usage.js";
 export const analysisCommands = {
@@ -23,7 +24,7 @@ export const analysisCommands = {
             const inputDataset = requiredStringFlag(f, "input-dataset", usage);
             const projectKey = f["project-key"];
             const options = { inputDataset, projectKey, };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "create",
@@ -45,11 +46,11 @@ export const analysisCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss analysis delete <analysisId> [--if-exists] [--dry-run] [--project-key KEY]");
             const projectKey = 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.analyses.get(a[0], projectKey));
                 if (!current)
                     return skipResult("analysis", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "analysis", id: a[0], current, };
                 }
             }

package/dist/src/cli/commands/api-service.js

@@ -1,6 +1,8 @@
 import { ClientValidationError, } from "../../errors.js";
+import { writeResponseToFile, } from "../../utils/response-file.js";
 import { stableHash, } from "../../utils/stable-hash.js";
 import { requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { requireArgs, UsageError, } from "../usage.js";
 function validateExpectHash(value) {
     if (value === undefined || value === false)
@@ -42,7 +44,7 @@ export const apiServiceCommands = {
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (service 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.apiServices.getSettings(a[0], projectKey);
                 const currentHash = stableHash(current);
                 if (expectHash !== undefined && currentHash !== expectHash.toLowerCase()) {
@@ -81,7 +83,7 @@ export const apiServiceCommands = {
                 type: "STD_PREDICTION",
                 modelRef: a[2],
             };
-            if (f["dry-run"] === true)
+            if (executionMode(f).dryRun)
                 return endpoint;
             return c.apiServices.addPredictionEndpoint(a[0], a[1], a[2], f["project-key"]);
         },
@@ -143,7 +145,7 @@ export const apiServiceCommands = {
             if (!res.body) {
                 throw new Error("apiServices.downloadPackageArchive response did not include a body");
             }
-            const bytes = await Bun.write(out, new Response(res.body), { createPath: false, });
+            const bytes = await writeResponseToFile(out, res);
             return { path: out, bytes, };
         },
         usage: "dss api-service download-package <serviceId> <packageId> --output PATH [--project-key KEY]",

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

@@ -1,6 +1,7 @@
 import { ClientValidationError, DataikuError, } from "../../errors.js";
 import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
 import { jsonInput, num, parseBooleanOption, plainRecord, requiredJsonInput, requiredStringFlag, stringField, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { appPermissionsHash, appPermissionsVerificationError, assertAppPermissionsSnapshotBinding, buildAppPermissionsSnapshot, diffAppPermissions, readAppPermissionsSnapshot, writeAppPermissionsSnapshot, } from "../helpers/app-permissions.js";
 import { createSuccessorInstance, futureTargetIdentity, isDefinitiveRejection, preflightSuccessorInstance, requireAbsentProjectTarget, safeErrorSummary, verifyAppInstance, VISUAL_UI_GATE, } from "../helpers/app-successor.js";
 import { CommandResultFailure, } from "../output.js";
@@ -385,7 +386,7 @@ export const appCommands = {
                 to: requiredStringFlag(f, "to", CREATE_SUCCESSOR_USAGE),
                 ...(f["name"] !== undefined ? { name: f["name"], } : {}),
                 copyPermissions: parseBooleanOption(f["copy-permissions"], "--copy-permissions") ?? false,
-                dryRun: parseBooleanOption(f["dry-run"], "--dry-run") ?? false,
+                dryRun: executionMode(f).dryRun,
                 timeoutMs: num(f["timeout"], "--timeout"),
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
             }, CREATE_SUCCESSOR_USAGE);
@@ -445,7 +446,7 @@ export const appCommands = {
                 ...(version !== undefined ? { version, } : {}),
                 ...(versionNotes !== undefined ? { versionNotes, } : {}),
                 ...(f["expect-hash"] !== undefined ? { expectHash: f["expect-hash"], } : {}),
-                dryRun: parseBooleanOption(f["dry-run"], "--dry-run") ?? false,
+                dryRun: executionMode(f).dryRun,
             }, f["project-key"]);
             if (result.outcome === "indeterminate") {
                 // The PUT may or may not have landed. Fail nonzero without
@@ -756,7 +757,7 @@ export const appCommands = {
             assertAppPermissionsSnapshotBinding(snapshot, projectKey, c.getBaseUrl());
             const currentProjectIncarnationHash = await requireProjectIncarnationHash(c, projectKey);
             assertAppPermissionsSnapshotBinding(snapshot, projectKey, c.getBaseUrl(), currentProjectIncarnationHash);
-            const dryRun = parseBooleanOption(f["dry-run"], "--dry-run") ?? false;
+            const dryRun = executionMode(f).dryRun;
             const before = await c.projects.getPermissions(projectKey);
             await assertProjectIncarnationHash(c, projectKey, snapshot.projectIncarnationHash);
             const beforeHash = appPermissionsHash(before);

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

@@ -1,3 +1,4 @@
+import { writeResponseToFile, } from "../../utils/response-file.js";
 import { json, parseBooleanOption, } from "../coerce.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const bundleCommands = {
@@ -48,7 +49,7 @@ export const bundleCommands = {
             if (!res.body) {
                 throw new Error("bundles.downloadExportedArchive response did not include a body");
             }
-            const bytes = await Bun.write(out, new Response(res.body), { createPath: false, });
+            const bytes = await writeResponseToFile(out, res);
             return { path: out, bytes, };
         },
         usage: "dss bundle download-exported <bundleId> --output PATH [--project-key KEY]",

package/dist/src/cli/commands/code-env.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, } from "node:fs";
 import { ClientValidationError, } from "../../errors.js";
 import { stableHash, } from "../../utils/stable-hash.js";
 import { json, jsonInput, num, numFlag, parseBooleanOption, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { enqueueCliWarning, isNotFoundError, readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 const CODE_ENV_LANGS = ["PYTHON", "R",];
@@ -175,13 +176,13 @@ export const codeEnvCommands = {
             }
             const params = codeEnvParams(f);
             const wait = codeEnvWait(f);
-            if (f["if-not-exists"] === true || f["dry-run"] === true) {
+            if (f["if-not-exists"] === true || executionMode(f).dryRun) {
                 const existing = (await c.codeEnvs.list({ envLang, }))
                     .find((env) => env.envName === a[1]);
-                if (existing && f["if-not-exists"] === true && f["dry-run"] !== true) {
+                if (existing && f["if-not-exists"] === true && !executionMode(f).dryRun) {
                     return skipResult("code-env", a[1], "exists", { envLang, current: existing, });
                 }
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "create",
@@ -224,7 +225,7 @@ export const codeEnvCommands = {
             }
             const expectHash = validateExpectHash(f["expect-hash"]);
             const definitionHash = stableHash(definition);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await readIfExists(() => c.codeEnvs.getDefinition(envLang, a[1]));
                 const currentHash = current ? stableHash(current) : undefined;
                 if (expectHash !== undefined && currentHash !== expectHash) {
@@ -260,7 +261,7 @@ export const codeEnvCommands = {
             const packages = codeEnvPackageList(f);
             const installCorePackages = parseBooleanOption(f["install-core-packages"], "--install-core-packages");
             const expectHash = validateExpectHash(f["expect-hash"]);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "set-packages",
@@ -297,7 +298,7 @@ export const codeEnvCommands = {
                 versionToUpdate,
                 wait,
             };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "update-packages",
@@ -320,7 +321,7 @@ export const codeEnvCommands = {
             const envLang = requireEnvLang(a[0], usage);
             const wait = codeEnvWait(f);
             const envVersion = typeof f["env-version"] === "string" ? f["env-version"] : undefined;
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "update-images",
@@ -350,7 +351,7 @@ export const codeEnvCommands = {
                 throw new UsageError("--active is required. Usage: dss code-env set-jupyter <lang> <name> --active true|false");
             }
             const wait = codeEnvWait(f);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "set-jupyter",
@@ -373,7 +374,7 @@ export const codeEnvCommands = {
             requireArgs(a, 2, usage);
             const envLang = requireEnvLang(a[0], usage);
             const wait = codeEnvWait(f);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await readIfExists(() => c.codeEnvs.get(envLang, a[1]));
                 if (!current)
                     return skipResult("code-env", a[1], "missing", { envLang, });

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

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import { ClientValidationError, } from "../../errors.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { jsonInput, parseBooleanOption, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const dashboardCommands = {
@@ -106,12 +107,12 @@ export const dashboardCommands = {
             if (listed !== undefined)
                 payload.listed = listed;
             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.dashboards.list(pk)).find((dashboard) => dashboard.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("dashboard", existing.id, "exists", { current: existing, });
                 }
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "create",
@@ -146,7 +147,7 @@ export const dashboardCommands = {
             if (name === undefined && listed === undefined && !data) {
                 throw new UsageError("--name, --listed, --data, --data-file, or --stdin is required.");
             }
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.dashboards.get(a[0], f["project-key"]);
                 const next = deepMerge(current, data ?? {});
                 if (name !== undefined)
@@ -170,11 +171,11 @@ export const dashboardCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss dashboard 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.dashboards.get(a[0], pk));
                 if (!current)
                     return skipResult("dashboard", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "dashboard", id: a[0], current, };
                 }
             }

package/dist/src/cli/commands/data-quality.js

@@ -1,5 +1,6 @@
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { num, parseBooleanOption, requiredJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
 /**
@@ -52,20 +53,20 @@ export const dataQualityCommands = {
                 : typeof config.displayName === "string"
                     ? config.displayName
                     : undefined;
-            if (f["if-not-exists"] === true || f["dry-run"] === true) {
+            if (f["if-not-exists"] === true || executionMode(f).dryRun) {
                 const existing = identity
                     ? (await c.dataQuality.listRules(a[0], pk)).find((rule) => rule.id === identity || rule.displayName === identity)
                     : undefined;
-                if (existing && f["if-not-exists"] === true && f["dry-run"] !== true) {
+                if (existing && f["if-not-exists"] === true && !executionMode(f).dryRun) {
                     return skipResult("data-quality", identity ?? existing.id, "exists", {
                         dataset: a[0],
                         current: existing,
                     });
                 }
-                if (f["if-not-exists"] === true && !identity && f["dry-run"] !== true) {
+                if (f["if-not-exists"] === true && !identity && !executionMode(f).dryRun) {
                     throw new UsageError("--if-not-exists requires rule id or displayName in the rule JSON.");
                 }
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "create-rule",
@@ -97,7 +98,7 @@ export const dataQualityCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 2, "dss data-quality update-rule <dataset> <rule-id> --data JSON");
             const data = requiredJsonInput(f, "--data, --data-file, or --stdin is required.");
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.dataQuality.getRule(a[0], a[1], f["project-key"]);
                 const next = deepMerge(current, data);
                 return {
@@ -125,11 +126,11 @@ export const dataQualityCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 2, "dss data-quality delete-rule <dataset> <rule-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.dataQuality.getRule(a[0], a[1], pk));
                 if (!current)
                     return skipResult("data-quality", a[1], "missing", { dataset: a[0], });
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "delete-rule",
@@ -248,7 +249,7 @@ export const dataQualityCommands = {
                 projectKey: pk,
                 timeoutMs: num(f["timeout"], "--timeout"),
             };
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const params = new URLSearchParams();
                 params.set("partition", options.partition?.trim() ? options.partition : "NP");
                 if (options.ruleId !== undefined)

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

@@ -2,6 +2,7 @@ import { buildDatasetCloneSettings, } from "../../resources/datasets.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { compareStrings, stableHash, } from "../../utils/stable-hash.js";
 import { jsonInput, num, schemaColumnsInput, unknownJsonInput, } from "../coerce.js";
+import { executionMode, } from "../flags.js";
 import { datasetSourceSummary, } from "../helpers/dataset.js";
 import { moveCreatedItemsToZone, resolveFlowZoneIdFromFlags, } from "../helpers/flow-zone.js";
 import { enqueueCliWarning, readIfExists, skipResult, } from "../output.js";
@@ -195,7 +196,7 @@ export const datasetCommands = {
             requireArgs(a, 1, usage);
             const columns = schemaColumnsInput(f, usage);
             const pk = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.datasets.schema(a[0], pk);
                 return {
                     dryRun: true,
@@ -365,13 +366,13 @@ export const datasetCommands = {
                 projectKey: pk,
             };
             const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
-            if (f["if-not-exists"] === true || f["dry-run"] === true) {
+            if (f["if-not-exists"] === true || executionMode(f).dryRun) {
                 const list = await c.datasets.list(pk);
                 const existing = list.find((d) => d.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("dataset", name, "exists", { current: existing, });
                 }
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return {
                         dryRun: true,
                         action: "create",
@@ -410,7 +411,7 @@ export const datasetCommands = {
             const current = await c.datasets.get(a[0], pk);
             const next = buildDatasetCloneSettings(current, a[1], pk ?? c.resolveProjectKey(pk), opts);
             const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 return {
                     dryRun: true,
                     action: "clone",
@@ -437,11 +438,11 @@ export const datasetCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss dataset delete <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.datasets.get(a[0], pk));
                 if (!current)
                     return skipResult("dataset", a[0], "missing");
-                if (f["dry-run"] === true) {
+                if (executionMode(f).dryRun) {
                     return { dryRun: true, action: "delete", resource: "dataset", name: a[0], current, };
                 }
             }
@@ -460,7 +461,7 @@ export const datasetCommands = {
                 throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin]");
             }
             const pk = f["project-key"];
-            if (f["dry-run"] === true) {
+            if (executionMode(f).dryRun) {
                 const current = await c.datasets.get(a[0], pk);
                 const next = deepMerge(current, data);
                 return { dryRun: true, action: "update", resource: "dataset", name: a[0], current, next, };

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

@@ -1,7 +1,9 @@
-import { runDoctor, } from "../doctor.js";
 export const doctorCommands = {
     run: {
-        handler: async (_c, _a, f) => (await runDoctor(f)).result,
+        handler: async (_c, _a, f) => {
+            const { runDoctor, } = await import("../doctor.js");
+            return (await runDoctor(f)).result;
+        },
         usage: "dss doctor [--project-key KEY] [--capabilities] [--fast]",
         description: "Run JSON diagnostics for DSS credentials, connectivity, and project access.",
         examples: ["dss doctor", "dss doctor --project-key MYPROJ", "dss doctor --capabilities --fast",],