dataiku-sdk 3.0.0 → 3.2.0

package/README.md

@@ -23,33 +23,118 @@ 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.
 
-## CLI contract
+## 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
+```
 
-- Command results write exactly one compact JSON value to stdout; void success is `{ok:true}`. `doctor`, `batch`, and `cleanup` failure reports are their direct result objects on stdout with a nonzero exit code — use the exit code and result fields.
-- Dispatch/runtime failures write one compact structured error object on stdout (`type:"error"`, `ok:false`, `error`, `code`, `category`, `exitCode`) with a nonzero exit code; stderr carries JSONL diagnostics only.
-- Non-fatal diagnostics and `--verbose` traces are JSONL stderr events (`type:"warning"` / `type:"trace"`), flushed before both success and failure output; no prose trace lines are part of the contract.
-- `--fields a,b,c` projects those fields from an object or array-of-objects result; dotted paths (`a.b.c`) drill into nested objects, and missing fields become `null`; string and scalar results pass through unchanged.
-- No prompts, help screens, tables, banners, or prose output are part of the contract.
-- Exit codes: `0` success, `1` usage/configuration error, `2` DSS/internal error, `3` transient DSS error, `4` a failed long-running result or synchronous assertion.
-- `--retries N` controls idempotent GET retries only. `dss sql query --start-retries N` explicitly retries transient failures while starting a query; use it only when executing the SQL more than once is safe.
-- The exit code is the success signal. For portable multi-step mutations, prefer `dss batch`; shell chaining and pipeline exit semantics differ across POSIX shells, Windows PowerShell, PowerShell 7, and Command Prompt.
-- Recipe payload commands write the payload as a JSON string on stdout; use `--output PATH` to write the exact bytes to a file instead, with stdout carrying the JSON string equal to `PATH`.
+## CLI contract
 
-Discover the agent contract and command surface with scoped calls:
+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
+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
+error / `3` transient DSS error / `4` failed long-running result or assertion. `--retries N`
+controls idempotent GET retries only; `dss sql query --start-retries N` retries transient failures
+while starting a query. For portable multi-step mutations, prefer `dss batch`; shell chaining and
+pipeline exit semantics differ across platforms.
+
+Discover the command surface with scoped calls:
 
 ```text
 dss commands run
-dss commands run --fields dataset
-dss commands run --fields dataset.create
 dss commands run --fields dataset.create.usage,dataset.create.description,dataset.create.flags,dataset.create.examples
 dss commands run --output commands.json
 dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility
-dss agent contract --fields commands.actions
 ```
 
-`dss commands run` prints the compact resource/action summary — every resource keyed to its action names, about 1k tokens — and never dumps registry entries to stdout. Bootstrap contract discovery with the scoped `agent contract` call above: `protocol,agentContractVersion,cli,stdio,planning,compatibility` cover protocol/schema compatibility, stdout/stderr stream semantics, preferred discovery commands, planning rules, and compatibility guarantees in ~250 tokens; request `schemas` or `commands` only when you actually need them. Before choosing syntax, scope `commands run` with `--fields`: `--fields RESOURCE.ACTION` returns one complete registry entry, `--fields RESOURCE` returns every action of one resource, and appending `.FIELD` paths projects the metadata you need — the four-field per-action projection `usage,description,flags,examples` is the smallest self-sufficient starting point for constructing an invocation. Inspect `flags`, `structuredExamples`, `schemas`, `requiresAuth`, `requiresProject`, `sideEffect`, `async`, `idempotency`, `dryRun`, `cleanupCommand`, `unsafeOutputs`, `outputShape`, `inputContract`, and `exitCodes` instead of guessing.
-
-`--fields` takes a comma-separated list, so request several actions in one call. Each key is echoed exactly as requested (`--fields dataset.create` returns `{"dataset.create": {...}}`); an empty `--fields` is a usage error, never a silent full dump. The full registry (~220k tokens) is exported only via `--output PATH`: the command writes the registry, or the selected `--fields` subset, as compact JSON to `PATH`, and stdout carries the compact `{"path":"PATH"}` result — never the registry itself. An unknown resource or action exits with code 1 and a compact JSON error object on stdout containing the valid options.
+`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
 
@@ -62,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`
@@ -70,7 +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.
+
+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.
+
+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.
+
+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
 
@@ -285,6 +405,48 @@ never marks that external check complete. The public DSS APIs used by this SDK d
 supported app-template publish/recreate/rename workflow, recipient-level app sharing setter, or
 UI-click smoke test. The CLI does not guess private endpoints for those operations.
 
+## Flow visualization and zone planning
+
+`project map` returns one agent-oriented JSON view of the Flow: normalized nodes and edges,
+joined zone metadata, cycle-safe topological layers, weakly connected components, diagnostics, and
+a stable `topologyFingerprint`. Zone joins add `zoneId`/`zoneName` to each node; the top-level
+`zones` array preserves zone color, position, item count, and visible node IDs.
+
+```bash
+dss project map --project-key MYPROJ
+dss project map --render mermaid --project-key MYPROJ
+dss project map --render ascii --max-nodes 100 --max-edges 200 --project-key MYPROJ
+```
+
+Rendering is optional and remains inside the JSON result as `rendering.content`; stdout never
+switches to an unstructured diagram stream. Layers are computed after collapsing strongly connected
+components, so cycles are reported without blocking the analysis. Diagnostics cover cycles,
+disconnected components, isolated/default-zone nodes, cross-zone edges, duplicate assignments, and
+truncated analysis. When limits truncate the returned nodes or edges, the topology fingerprint still
+covers the full normalized Flow while layers/components/diagnostics cover the returned subset.
+
+The public API exposes zone positions and membership, not individual node pixel coordinates. The CLI
+therefore preserves only supported zone-level visual metadata and never fabricates node coordinates.
+Use the declarative export/apply loop for visual organization:
+
+```bash
+dss flow-zone plan --project-key MYPROJ > flow-zones.json
+dss flow-zone organize --file flow-zones.json --dry-run --project-key MYPROJ
+dss flow-zone organize --file flow-zones.json --project-key MYPROJ
+```
+
+`flow-zone plan` emits JSON accepted directly by `flow-zone organize`, including every
+current zone's supported metadata and explicit items. Reapplying an unchanged plan produces no
+redundant moves. `organize` compares the plan's topology fingerprint before mutation and recomputes
+it after mutation; a mismatch fails rather than claiming a visual-only change. Zone names, colors,
+positions, and membership are deliberately excluded from the fingerprint; flow node identity/kind and
+edges are included.
+
+Recipe/code analysis is a separate audit. `project map` and `flow-zone plan` do not fetch,
+hash, interpret, or grade recipe payloads. Use the recipe inspection/diff/assertion commands in a
+separate workflow when code quality or semantic review is required; never mix those findings into a
+layout plan.
+
 ## Project Git source-control safety
 
 Project Git commands require DSS 12.4.2 or newer plus read and write access to the project
@@ -330,6 +492,71 @@ applies only to external project-library operations and does not persist a remot
 The `project-git` resource does not manage these settings, so public/auth-less and
 already-configured remotes are the supported automation paths.
 
+## Coding, notebooks, and project libraries
+
+`project-library` manages files in a project's internal `lib/` tree. External Git-backed
+libraries are a different surface: inspect and change those with `project-git list-libraries`,
+`set-library`, `push-library`, and the related future commands. Internal paths are canonicalized;
+leading slashes are removed, while traversal (`..`) and empty segments are rejected.
+
+Use a read/diff/guarded-write sequence for internal files. `get-bytes` preserves binary data and
+returns its SHA-256; `diff` caps text output and detects binary files instead of dumping bytes.
+`put --expect-sha256` re-reads the remote bytes and refuses a stale overwrite. New files and
+folders never overwrite existing items; `--if-not-exists` turns an existing target into a skip.
+
+```bash
+dss project-library get-bytes python/mylib/utils.py --output ./utils.py --project-key MYPROJ
+dss project-library diff python/mylib/utils.py --file ./utils.py --project-key MYPROJ
+dss project-library put python/mylib/utils.py --file ./utils.py --expect-sha256 HASH --dry-run --project-key MYPROJ
+dss project-library put python/mylib/utils.py --file ./utils.py --expect-sha256 HASH --project-key MYPROJ
+```
+
+For one-off Python, prefer a file so shell quoting cannot change the source. `code run` creates an
+observable throwaway custom-Python scenario, waits with a bounded timeout, caps returned logs, and
+deletes only that generated scenario unless `--keep` is set.
+
+```bash
+dss code run --file inspect.py --env py311 --project-key MYPROJ
+dss recipe diff prepare_orders --file recipe.py --project-key MYPROJ
+dss recipe set-payload prepare_orders --file recipe.py --dry-run --project-key MYPROJ
+dss recipe set-payload prepare_orders --file recipe.py --backup-dir .dss-backups/recipes --project-key MYPROJ
+dss recipe run prepare_orders --dry-run --project-key MYPROJ
+```
+
+Recipe payload diffs normalize LF/CRLF. `set-payload` backs up payload, graph, settings, code-env,
+and version metadata by default; use `restore --backup FILE --dry-run` before applying a rollback.
+`recipe run --dry-run` performs live output resolution without creating a job; static
+`--plan` reports `exact:false` rather than inventing that live payload.
+
+Notebook saves are save-or-create operations. Read first, preserve the full notebook object, then
+use the persisted hash from save/dry-run output with `--expect-hash`. Jupyter output clearing uses
+the official DELETE endpoint. `unload-jupyter --all` is deliberately composed: list active
+notebooks, list their sessions, then delete each session; DSS has no unload-all endpoint.
+
+```bash
+dss notebook get-jupyter analysis.ipynb --project-key MYPROJ
+dss notebook save-jupyter analysis.ipynb --data-file notebook.json --dry-run --project-key MYPROJ
+dss notebook save-jupyter analysis.ipynb --data-file notebook.json --expect-hash HASH --project-key MYPROJ
+dss notebook clear-jupyter-outputs analysis.ipynb --dry-run --project-key MYPROJ
+dss notebook unload-jupyter --all --dry-run --project-key MYPROJ
+```
+
+Code-environment reads expose definitions, deployment mode, installed/requested packages, project
+versions, usages, and bounded build logs. Fetch the definition/hash before `set-definition` or
+`set-packages --expect-hash`; package, image, Jupyter, create, and delete operations can return DSS
+futures with `--no-wait`.
+
+Webapp updates use GET–deep-merge–PUT; API-service `save-settings` is explicit full replacement.
+Run either with `--dry-run` to inspect `currentHash`/`nextHash`, then apply with
+`--expect-hash`. Webapp restart futures support `--wait`. API packages and project bundles
+forward release notes and explicit Deployer target IDs.
+
+An agent plan with `exact:false` is an honesty boundary: live state is required and no endpoint or
+payload was guessed. Use the command's own `--dry-run` when it resolves that state. The supported
+public DSS API exposes no plugin-authoring lifecycle, notebook execution/checkpoint operation, or
+webapp/API-service delete. Use project Git for plugin source, `code run`/recipes for execution,
+and the authenticated DSS UI for unsupported lifecycle operations.
+
 For fake-DSS smoke tests, return project lists as JSON arrays such as `[{ "projectKey": "MYPROJ", "name": "My Project" }]` from `/public/api/projects/`; recipe payload commands read `/public/api/projects/<PROJECT>/recipes/<NAME>?includePayload=true` and expect a JSON object shaped like `{ "recipe": { "name": "<NAME>", "type": "python" }, "payload": "..." }`.
 
 ## License

package/dist/build-metadata.json

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

package/dist/packages/types/src/index.d.ts

@@ -430,7 +430,6 @@ export type ConnectionSummary = Static<typeof ConnectionSummarySchema>;
 export declare const CodeEnvSummarySchema: import("@sinclair/typebox").TObject<{
     envName: import("@sinclair/typebox").TString;
     envLang: import("@sinclair/typebox").TString;
-    pythonInterpreter: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     deploymentMode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
 export type CodeEnvSummary = Static<typeof CodeEnvSummarySchema>;
@@ -438,10 +437,42 @@ export declare const CodeEnvDetailsSchema: import("@sinclair/typebox").TObject<{
     envName: import("@sinclair/typebox").TString;
     envLang: import("@sinclair/typebox").TString;
     pythonInterpreter: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    deploymentMode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     requestedPackages: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
     installedPackages: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+    definitionHash: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
 export type CodeEnvDetails = Static<typeof CodeEnvDetailsSchema>;
+export declare const CodeEnvLogSummarySchema: import("@sinclair/typebox").TObject<{
+    name: import("@sinclair/typebox").TString;
+}>;
+export type CodeEnvLogSummary = Static<typeof CodeEnvLogSummarySchema>;
+export declare const CodeEnvLogSummaryArraySchema: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+    name: import("@sinclair/typebox").TString;
+}>>;
+export type CodeEnvLogSummaryArray = Static<typeof CodeEnvLogSummaryArraySchema>;
+export declare const CodeEnvLogResultSchema: import("@sinclair/typebox").TObject<{
+    log: import("@sinclair/typebox").TString;
+    bytes: import("@sinclair/typebox").TNumber;
+    truncated: import("@sinclair/typebox").TBoolean;
+    tailed: import("@sinclair/typebox").TBoolean;
+}>;
+export type CodeEnvLogResult = Static<typeof CodeEnvLogResultSchema>;
+export declare const CodeEnvGetLogOptionsSchema: import("@sinclair/typebox").TObject<{
+    maxBytes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    maxLines: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export type CodeEnvGetLogOptions = Static<typeof CodeEnvGetLogOptionsSchema>;
+export declare const CodeEnvUpdateImagesOptionsSchema: import("@sinclair/typebox").TObject<{
+    envVersion: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    wait: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
+export type CodeEnvUpdateImagesOptions = Static<typeof CodeEnvUpdateImagesOptionsSchema>;
+export declare const CodeEnvVersionForProjectSchema: import("@sinclair/typebox").TObject<{
+    version: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    bundleId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type CodeEnvVersionForProject = Static<typeof CodeEnvVersionForProjectSchema>;
 export declare const CodeEnvActionResultSchema: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
 export type CodeEnvActionResult = Static<typeof CodeEnvActionResultSchema>;
 export declare const CodeEnvCreateOptionsSchema: import("@sinclair/typebox").TObject<{
@@ -457,6 +488,7 @@ export type CodeEnvPackageList = Static<typeof CodeEnvPackageListSchema>;
 export declare const CodeEnvSetPackagesOptionsSchema: import("@sinclair/typebox").TObject<{
     packages: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>]>;
     installCorePackages: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    expectHash: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
 export type CodeEnvSetPackagesOptions = Static<typeof CodeEnvSetPackagesOptionsSchema>;
 export declare const CodeEnvUpdatePackagesOptionsSchema: import("@sinclair/typebox").TObject<{
@@ -583,7 +615,7 @@ export declare const DataQualityComputeResultSchema: import("@sinclair/typebox")
 export type DataQualityComputeResult = Static<typeof DataQualityComputeResultSchema>;
 export declare const JupyterCellSchema: import("@sinclair/typebox").TObject<{
     cell_type: import("@sinclair/typebox").TString;
-    source: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+    source: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>]>;
     metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
     outputs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnknown>>;
     execution_count: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TNull, import("@sinclair/typebox").TNumber]>>;
@@ -606,7 +638,7 @@ export declare const JupyterNotebookContentSchema: import("@sinclair/typebox").T
     nbformat_minor: import("@sinclair/typebox").TNumber;
     cells: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
         cell_type: import("@sinclair/typebox").TString;
-        source: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+        source: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>]>;
         metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
         outputs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnknown>>;
         execution_count: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TNull, import("@sinclair/typebox").TNumber]>>;
@@ -646,6 +678,9 @@ export declare const SqlNotebookContentSchema: import("@sinclair/typebox").TObje
     }>>;
 }>;
 export type SqlNotebookContent = Static<typeof SqlNotebookContentSchema>;
+/** Execution history of a SQL notebook: cell ID to the runs recorded for it. */
+export declare const SqlNotebookHistorySchema: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnknown>>;
+export type SqlNotebookHistory = Static<typeof SqlNotebookHistorySchema>;
 export declare const SqlQuerySchemaSchema: import("@sinclair/typebox").TObject<{
     name: import("@sinclair/typebox").TString;
     type: import("@sinclair/typebox").TString;
@@ -677,6 +712,7 @@ export declare const FlowMapOptionsSchema: import("@sinclair/typebox").TObject<{
     maxNodes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
     maxEdges: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
     includeRaw: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    render: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"ascii">, import("@sinclair/typebox").TLiteral<"mermaid">]>>;
 }>;
 export type FlowMapOptions = Static<typeof FlowMapOptionsSchema>;
 /**
@@ -853,7 +889,6 @@ export declare const FolderItemArraySchema: import("@sinclair/typebox").TArray<i
 export declare const CodeEnvSummaryArraySchema: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
     envName: import("@sinclair/typebox").TString;
     envLang: import("@sinclair/typebox").TString;
-    pythonInterpreter: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     deploymentMode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>>;
 export declare const WikiArticleDataArraySchema: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{

package/dist/packages/types/src/index.js

@@ -444,16 +444,39 @@ export const ConnectionSummarySchema = Type.Object({
 export const CodeEnvSummarySchema = Type.Object({
     envName: Type.String(),
     envLang: Type.String(),
-    pythonInterpreter: Type.Optional(Type.String()),
     deploymentMode: Type.Optional(Type.String()),
 }, { additionalProperties: true, });
 export const CodeEnvDetailsSchema = Type.Object({
     envName: Type.String(),
     envLang: Type.String(),
     pythonInterpreter: Type.Optional(Type.String()),
+    deploymentMode: Type.Optional(Type.String()),
     requestedPackages: Type.Array(Type.String()),
     installedPackages: Type.Array(Type.String()),
+    definitionHash: Type.Optional(Type.String()),
 });
+export const CodeEnvLogSummarySchema = Type.Object({
+    name: Type.String(),
+}, { additionalProperties: true, });
+export const CodeEnvLogSummaryArraySchema = Type.Array(CodeEnvLogSummarySchema);
+export const CodeEnvLogResultSchema = Type.Object({
+    log: Type.String(),
+    bytes: Type.Number(),
+    truncated: Type.Boolean(),
+    tailed: Type.Boolean(),
+}, { additionalProperties: false, });
+export const CodeEnvGetLogOptionsSchema = Type.Object({
+    maxBytes: Type.Optional(Type.Number()),
+    maxLines: Type.Optional(Type.Number()),
+}, { additionalProperties: false, });
+export const CodeEnvUpdateImagesOptionsSchema = Type.Object({
+    envVersion: Type.Optional(Type.String()),
+    wait: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false, });
+export const CodeEnvVersionForProjectSchema = Type.Object({
+    version: Type.Optional(Type.String()),
+    bundleId: Type.Optional(Type.String()),
+}, { additionalProperties: true, });
 export const CodeEnvActionResultSchema = Type.Record(Type.String(), Type.Unknown());
 export const CodeEnvCreateOptionsSchema = Type.Object({
     envLang: Type.String(),
@@ -469,6 +492,7 @@ export const CodeEnvPackageListSchema = Type.Union([
 export const CodeEnvSetPackagesOptionsSchema = Type.Object({
     packages: CodeEnvPackageListSchema,
     installCorePackages: Type.Optional(Type.Boolean()),
+    expectHash: Type.Optional(Type.String()),
 }, { additionalProperties: false, });
 export const CodeEnvUpdatePackagesOptionsSchema = Type.Object({
     forceRebuildEnv: Type.Optional(Type.Boolean()),
@@ -569,7 +593,9 @@ export const DataQualityComputeResultSchema = Type.Object({
 // ---------------------------------------------------------------------------
 export const JupyterCellSchema = Type.Object({
     cell_type: Type.String(),
-    source: Type.Array(Type.String()),
+    // nbformat permits a cell's source to be either a single string or an
+    // array of strings; DSS returns whichever form the notebook carries.
+    source: Type.Union([Type.String(), Type.Array(Type.String()),]),
     metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
     outputs: Type.Optional(Type.Array(Type.Unknown())),
     execution_count: Type.Optional(Type.Union([Type.Null(), Type.Number(),])),
@@ -617,6 +643,8 @@ export const SqlNotebookContentSchema = Type.Object({
     connection: Type.String(),
     cells: Type.Array(SqlNotebookCellSchema),
 }, { additionalProperties: true, });
+/** Execution history of a SQL notebook: cell ID to the runs recorded for it. */
+export const SqlNotebookHistorySchema = Type.Record(Type.String(), Type.Array(Type.Unknown()));
 // ---------------------------------------------------------------------------
 // SQL Queries
 // ---------------------------------------------------------------------------
@@ -642,6 +670,7 @@ export const FlowMapOptionsSchema = Type.Object({
     maxNodes: Type.Optional(Type.Number()),
     maxEdges: Type.Optional(Type.Number()),
     includeRaw: Type.Optional(Type.Boolean()),
+    render: Type.Optional(Type.Union([Type.Literal("ascii"), Type.Literal("mermaid"),])),
 });
 // ---------------------------------------------------------------------------
 // Project Git

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, };
                 }
             }