dataiku-sdk 2.0.0 → 3.1.0

package/LICENSE

@@ -1,21 +1,111 @@
-MIT License
+Dataiku SDK Limited Use License
+Version 1.0 — 31 August 2026
 
 Copyright (c) 2026 clssck
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+By copying, installing, accessing, or using this software and its associated
+documentation (the "Software"), you agree to this license.
+
+1. Definitions
+
+"Licensor" means clssck, the copyright holder.
+
+"Individual" means a natural person acting solely on their own behalf. A person
+acting for an employer, client, company, or other organization is not acting as
+an Individual for that use.
+
+"Company" means a for-profit legal entity, including a sole proprietorship,
+partnership, corporation, or limited liability company. Companies under common
+control are treated as one Company.
+
+"Annual Revenue" means a Company's total gross revenue, together with the gross
+revenue of every entity under common control, for its most recently completed
+fiscal year, before deductions. A Company without a completed fiscal year must
+use its good-faith projected gross revenue for its first twelve months. Revenue
+in another currency must be converted to United States dollars using a
+reasonable, consistently applied exchange rate.
+
+"Qualified User" means either:
+
+(a) an Individual; or
+(b) a Company with Annual Revenue of less than US $1,000,000.
+
+2. Free Limited License for Qualified Users
+
+Subject to every term of this license, the Licensor grants each Qualified User
+a non-exclusive, non-transferable, and non-sublicensable license, without
+a license fee, to copy, install, and run unmodified copies of the Software for
+the Qualified User's own use.
+
+Use by an employee, contractor, agent, or other person on behalf of a Company is
+use by that Company. An Individual license does not extend to such use.
+
+3. Users That Do Not Qualify
+
+A Company with Annual Revenue of US $1,000,000 or more, and any person or entity
+that is not a Qualified User, receives no right to use the Software under
+Section 2. Such a user must request and obtain a separate written license from
+the Licensor before copying, installing, or using the Software. Public access
+to the source code does not itself grant permission to use it.
+
+License and approval requests may be submitted to the Licensor through:
+https://github.com/clssck/dataiku-sdk
+
+4. Prior Written Approval Required
+
+The rights granted in Section 2 do not include any right to:
+
+(a) modify, adapt, translate, or create derivative works of the Software,
+including modifications made only for private or internal use; or
+(b) publish, distribute, provide, transfer, sublicense, sell, or otherwise make
+all or any part of the Software available to another person or entity, whether
+in source, binary, modified, or unmodified form.
+
+Each activity listed above requires the Licensor's prior written approval.
+Approval of one activity or version does not approve another. The Licensor may
+condition or deny approval at its discretion.
+
+5. Attribution and Citation
+
+Every permitted use must preserve all copyright, attribution, and license
+notices included with the Software. The following credit and link must also
+appear in documentation, notices, or an About page accompanying the use:
+
+    dataiku-sdk by clssck — https://github.com/clssck/dataiku-sdk
+
+The credit must be reasonably prominent and may not suggest endorsement by the
+Licensor. Prior written approval under Section 4 does not waive these
+requirements unless the approval expressly says so.
+
+6. No Other Rights
+
+The Software is licensed, not sold. Except for the limited rights expressly
+granted in this license or in a separate written agreement signed by the
+Licensor, the Licensor reserves all rights. This license grants no right to use
+any trademark, service mark, trade name, or logo of the Licensor.
+
+7. Termination
+
+This license terminates automatically upon breach. After termination, you must
+stop using the Software and delete every copy in your possession or control.
+Sections 5, 6, 8, 9, and 10 survive termination.
+
+8. Disclaimer of Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, TITLE, AND NON-INFRINGEMENT. YOU BEAR ALL RISK ARISING FROM USE OF THE
 SOFTWARE.
+
+9. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR WILL NOT BE LIABLE FOR ANY
+CLAIM, LOSS, OR DAMAGES ARISING FROM OR RELATED TO THE SOFTWARE OR THIS LICENSE,
+WHETHER IN CONTRACT, TORT, OR OTHERWISE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+10. Earlier Licenses
+
+This license applies only to copies of the Software distributed with this
+license. It does not revoke or restrict rights validly granted for copies that a
+recipient previously received under another license.

package/README.md

@@ -25,31 +25,30 @@ Bun is the only supported runtime and the package manager. Examples below assume
 
 ## CLI contract
 
-- 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`.
-
-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
+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
+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 (~220k tokens
+exported) 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
 
@@ -72,6 +71,15 @@ Project installs write `SKILL.md` under the target workspace:
 
 Global installs write under the agent's home config path, for example OMP: `~/.omp/agent/skills/dataiku-dss/SKILL.md`.
 
+Each entry in the `installed` array reports deterministic file state:
+
+- `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.
+
+`--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.
+
 ## Credentials
 
 Use environment variables for ephemeral runs. For disposable agent tests, set `DSS_CONFIG_DIR` to a temporary directory so saved credentials never touch your real profile.
@@ -285,6 +293,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,4 +380,81 @@ 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
+
+This project is source-available under the [Dataiku SDK Limited Use License 1.0](LICENSE), not an open-source license.
+
+- Individuals acting on their own behalf may use unmodified copies without a license fee.
+- Companies with total annual gross revenue below US $1,000,000 may use unmodified copies without a license fee.
+- Companies at or above that threshold, and all other entities, must request and obtain a separate written license before use.
+- Every modification, including private or internal changes, and every form of redistribution requires prior written approval.
+- Permitted use must preserve the license notices and display: `dataiku-sdk by clssck — https://github.com/clssck/dataiku-sdk`.
+
+Copies previously received under another license retain the rights granted for those copies. See [LICENSE](LICENSE) for the controlling terms and request path.

package/dist/build-metadata.json

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

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/cli/commands/api-service.js

@@ -1,5 +1,15 @@
+import { ClientValidationError, } from "../../errors.js";
+import { stableHash, } from "../../utils/stable-hash.js";
 import { requiredJsonInput, } from "../coerce.js";
 import { requireArgs, UsageError, } from "../usage.js";
+function validateExpectHash(value) {
+    if (value === undefined || value === false)
+        return undefined;
+    if (typeof value !== "string" || !/^[0-9a-fA-F]{64}$/.test(value)) {
+        throw new ClientValidationError("Expected API service settings hash must be a 64-character SHA-256 hex digest.", "validation_failed", "Run this update with --dry-run and capture currentHash before retrying.");
+    }
+    return value;
+}
 export const apiServiceCommands = {
     list: {
         handler: (c, _a, f) => c.apiServices.list(f["project-key"]),
@@ -26,14 +36,42 @@ export const apiServiceCommands = {
         examples: ["dss api-service get-settings my-service",],
     },
     "save-settings": {
-        handler: (c, a, f) => {
-            requireArgs(a, 1, "dss api-service save-settings <serviceId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+        handler: async (c, a, f) => {
+            const usage = "dss api-service save-settings <serviceId> (--data JSON|--data-file PATH|--stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]";
+            requireArgs(a, 1, usage);
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (service settings).");
-            return c.apiServices.saveSettings(a[0], body, f["project-key"]);
+            const projectKey = f["project-key"];
+            const expectHash = validateExpectHash(f["expect-hash"]);
+            if (f["dry-run"] === true) {
+                const current = await c.apiServices.getSettings(a[0], projectKey);
+                const currentHash = stableHash(current);
+                if (expectHash !== undefined && currentHash !== expectHash.toLowerCase()) {
+                    throw new ClientValidationError(`The API service ${JSON.stringify(a[0])} changed since it was read.`, "validation_failed", "Re-read the service settings and retry with the current hash value.", {
+                        serviceId: a[0],
+                        expectedHash: expectHash.toLowerCase(),
+                        actualHash: currentHash,
+                    });
+                }
+                return {
+                    dryRun: true,
+                    action: "save-settings",
+                    resource: "api-service",
+                    serviceId: a[0],
+                    current,
+                    next: body,
+                    currentHash,
+                    nextHash: stableHash(body),
+                    ...(expectHash !== undefined
+                        ? { expectHash: expectHash.toLowerCase(), provenanceVerified: true, }
+                        : {}),
+                };
+            }
+            const saved = await c.apiServices.saveSettings(a[0], body, projectKey, { expectHash, });
+            return { saved: a[0], ...saved, };
         },
-        usage: "dss api-service save-settings <serviceId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
-        description: "Save an API service's settings.",
-        examples: ["dss api-service save-settings my-service --data-file service.json",],
+        usage: "dss api-service save-settings <serviceId> (--data JSON|--data-file PATH|--stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]",
+        description: "Replace an API service's settings wholesale (explicit replacement: the supplied object is PUT as-is, so fetch get-settings first). --expect-hash refuses the write when the stored settings changed since they were fetched; --dry-run reports current, next, and both hashes without writing.",
+        examples: ["dss api-service save-settings my-service --data-file service.json --dry-run",],
     },
     "add-prediction-endpoint": {
         handler: async (c, a, f) => {
@@ -75,12 +113,15 @@ export const apiServiceCommands = {
     },
     "create-package": {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss api-service create-package <serviceId> <packageId> [--project-key KEY]");
-            return c.apiServices.createPackage(a[0], a[1], f["project-key"]);
+            requireArgs(a, 2, "dss api-service create-package <serviceId> <packageId> [--release-notes TEXT] [--project-key KEY]");
+            return c.apiServices.createPackage(a[0], a[1], f["project-key"], typeof f["release-notes"] === "string" ? { releaseNotes: f["release-notes"], } : {});
         },
-        usage: "dss api-service create-package <serviceId> <packageId> [--project-key KEY]",
-        description: "Build a deployable package from the current service state.",
-        examples: ["dss api-service create-package my-service v1",],
+        usage: "dss api-service create-package <serviceId> <packageId> [--release-notes TEXT] [--project-key KEY]",
+        description: "Build a deployable package from the current service state; --release-notes forwards the documented releaseNotes query parameter.",
+        examples: [
+            "dss api-service create-package my-service v1",
+            "dss api-service create-package my-service v1 --release-notes='Adds churn endpoint'",
+        ],
     },
     "delete-package": {
         handler: async (c, a, f) => {
@@ -111,11 +152,16 @@ export const apiServiceCommands = {
     },
     "publish-package": {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss api-service publish-package <serviceId> <packageId> [--project-key KEY]");
-            return c.apiServices.publishPackage(a[0], a[1], f["project-key"]);
+            requireArgs(a, 2, "dss api-service publish-package <serviceId> <packageId> [--published-service-id ID] [--project-key KEY]");
+            return c.apiServices.publishPackage(a[0], a[1], f["project-key"], typeof f["published-service-id"] === "string"
+                ? { publishedServiceId: f["published-service-id"], }
+                : {});
         },
-        usage: "dss api-service publish-package <serviceId> <packageId> [--project-key KEY]",
-        description: "Publish a package to the API Deployer.",
-        examples: ["dss api-service publish-package my-service v1",],
+        usage: "dss api-service publish-package <serviceId> <packageId> [--published-service-id ID] [--project-key KEY]",
+        description: "Publish a package to the API Deployer; --published-service-id forwards the documented publishedServiceId query parameter (a new published service is created when no match exists; the service's own id is the server-side default).",
+        examples: [
+            "dss api-service publish-package my-service v1",
+            "dss api-service publish-package my-service v1 --published-service-id=prod-churn",
+        ],
     },
 };