dataiku-sdk 0.12.3 → 0.12.5

package/README.md

@@ -23,23 +23,28 @@ Bun is the primary development runtime and package manager. Examples below assum
 
 ## CLI contract
 
-- Success: stdout contains one JSON result.
-- Failure: stderr contains one JSONL error event with `type:"error"`, `ok:false`, `error`, `code`, and `exitCode`.
+- Command results write exactly one JSON value to stdout, including `doctor`, `batch`, and `cleanup` failure reports; use the exit code and result fields.
+- Dispatch/runtime failures write one JSONL error event to stderr with `type:"error"`, `ok:false`, `error`, `code`, and `exitCode`, while stdout stays empty.
 - Non-fatal diagnostics and `--verbose` traces are JSONL stderr events (`type:"warning"` / `type:"trace"`); 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` completed command with failed long-running DSS work.
+- 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.
 - 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.
 - `--raw` is only for recipe payload commands. Without `--output`, stdout is raw bytes; with `--output PATH`, stdout is the JSON string equal to `PATH` and the file contains the exact raw bytes.
 
-Discover the agent protocol and complete machine-readable command surface:
+Discover the agent contract and command surface with compact, scoped, `--json` calls:
 
 ```text
-dss agent contract
-dss commands run
+dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility --json
+dss commands run --fields dataset.create --json
+dss commands run --fields dataset.create.usage,dataset.create.description,dataset.create.flags,dataset.create.examples --json
+dss commands run --fields dataset --json
+dss agent contract --fields commands.actions --json
 ```
 
-Agents should parse `agent contract` once for protocol/schema compatibility, then parse `commands run` before choosing syntax; inspect `flags`, `structuredExamples`, `schemas`, `requiresAuth`, `requiresProject`, `sideEffect`, `unsafeOutputs`, and `outputShape` instead of guessing.
+For JSON outputs, prefer `--json`: compact single-line JSON cuts the full registry's context usage by about 40% (~220k tokens versus ~358k pretty-printed). Bootstrap by scoping `agent contract` to `protocol,agentContractVersion,cli,stdio,planning,compatibility` (~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, 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": {...}}`). Enumerate every resource and action with `dss agent contract --fields commands.actions --json` (~1k tokens); the ~220k-token unscoped registry remains a compatibility surface, not a discovery workflow. An unknown resource or action exits with code 1 and a JSON error envelope on stderr containing the valid options.
 
 ## Agent skill installation
 
@@ -116,6 +121,112 @@ dss recipe get-payload compute_orders --project-key MYPROJ
 dss recipe get-payload compute_orders --raw --project-key MYPROJ
 dss recipe get-payload compute_orders --raw --output code.py --project-key MYPROJ
 dss install-skill --dry-run
+dss app validate-manifest --project-key MYAPP_INSTANCE
+dss app compare-manifest my-app --project-key MYAPP_INSTANCE
+dss app create-instance my-app --data '{"targetProjectKey":"MYAPP_INSTANCE"}' --wait --record-cleanup cleanup.jsonl
+dss app manifest-version --project-key MYAPP_TEMPLATE
+dss app set-manifest-version --manifest-version 1.4.0 --project-key MYAPP_TEMPLATE
+dss app create-successor-instance my-app --from MYAPP_INSTANCE --to MYAPP_INSTANCE_V2 --copy-permissions --record-cleanup cleanup.jsonl
+dss app verify-instance my-app --project-key MYAPP_INSTANCE_V2 --expect-version 1.4.0
+dss app permissions-snapshot --project-key MYAPP_INSTANCE --output permissions.json
+dss app permissions-diff --project-key MYAPP_INSTANCE --file permissions.json
+dss app permissions-restore --project-key MYAPP_INSTANCE --file permissions.json --dry-run
+dss cleanup --file cleanup.jsonl
+dss cleanup --file cleanup.jsonl --apply
 ```
 
+### Application release safety
+
+Use the app commands as explicit release gates around a stable template, instance project key,
+and permission set:
+
+```bash
+# Validate source-verifiable manifest references.
+dss app validate-manifest --project-key APP_TEMPLATE
+
+# Detect governed template/instance drift. Only projectKey and projectAppType are normalized away.
+dss app compare-manifest APP_ID --project-key RELEASE_INSTANCE
+
+# Read the raw `version` from the public app manifest (string fields only; never appVersion).
+dss app manifest-version --project-key APP_TEMPLATE
+
+# Write version/versionNotes through the public app-manifest endpoint. This is NOT a publish
+# transaction: it only changes the raw manifest metadata. --expect-hash SHA256 is a non-atomic
+# stale-read guard, not a conditional write: it refuses the write when the manifest already
+# changed since you read that hash, but DSS accepts every PUT unconditionally. This command can
+# overwrite a write landing between its read and PUT, and the final read cannot detect that lost
+# update when this command's payload wins. Every result reports
+# concurrencyControl: "client-side-non-atomic-stale-read-check".
+dss app set-manifest-version --manifest-version 1.4.0 --project-key APP_TEMPLATE
+
+# Create an instance only after its target key is confirmed absent, wait on the DSS future, and
+# record deterministic cleanup.
+dss app create-instance APP_ID \
+  --data '{"targetProjectKey":"RELEASE_INSTANCE","targetProjectName":"Release instance"}' \
+  --wait --record-cleanup cleanup.jsonl
+
+# Roll out a new template version to an existing instance as an additive successor: the old
+# instance is never modified or deleted, and the command always waits on the DSS future
+# (there is no --wait flag). The recorded cleanup entry targets only the new project key. If DSS
+# accepts creation but returns no future ID, cleanup stops unresolved instead of racing creation.
+dss app create-successor-instance APP_ID \
+  --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 \
+  --name "Release instance v2" --copy-permissions --record-cleanup cleanup.jsonl
+
+# API readiness gate for the successor. apiReady:true with status API_VERIFIED_UI_PENDING is an
+# API-verified state only — never visual verification. The API key authenticates public REST only;
+# visual confirmation stays an external SSO gate (pre-authenticated SSO browser session or a
+# dedicated UI test identity).
+dss app verify-instance APP_ID --project-key RELEASE_INSTANCE_V2 --expect-version 1.4.0
+
+# Retirement of the predecessor is a separate, separately guarded step after the successor is
+# verified. It is never performed implicitly by the successor flow.
+dss app delete-instance --project-key RELEASE_INSTANCE
+
+# Snapshot, compare, preview, and restore project permissions.
+dss app permissions-snapshot --project-key RELEASE_INSTANCE --output permissions.json
+dss app permissions-diff --project-key RELEASE_INSTANCE --file permissions.json
+dss app permissions-restore --project-key RELEASE_INSTANCE --file permissions.json --dry-run
+dss app permissions-restore --project-key RELEASE_INSTANCE --file permissions.json
+```
+
+Permission snapshots are written with mode `0600` and an integrity hash covering the canonical DSS
+URL, the concrete project incarnation (`creationTag`), capture metadata, and permissions. Diff and
+restore reject snapshots from another DSS server, project key, or observed incarnation. These are
+client-side, non-atomic stale-identity checks: DSS exposes no conditional permission PUT, so the
+checks narrow and detect key-reuse races but cannot serialize the final check with the write.
+Snapshots contain access-control identities; commit them only when repository policy permits.
+`validate-manifest` checks `SCENARIO_RUN` scenario IDs, `DOWNLOAD_FILE`
+managed-folder IDs, and runtime-form parameter names against supported public project APIs.
+
+Some DSS deployments hide unknown project keys behind `403` instead of returning `404`.
+Instance creation requires confirmed target absence before POST: an inaccessible target not present
+in the visible project list is still unconfirmed and is rejected rather than risking cleanup
+against a pre-existing project. A definitive create rejection never produces a cleanup entry.
+
+Every new cleanup entry records the canonical DSS URL. App-instance cleanup records a
+`creationTag` hash observed after the DSS future identifies the target key; unconfirmed creation
+stops unresolved. The future target and later `creationTag` are independent, non-atomic
+observations: the public API exposes neither an immutable project ID joined to the future nor a
+conditional DELETE. Cleanup rechecks type and `creationTag` immediately before deletion, rejecting
+detected key reuse, but cannot eliminate replacement in the remaining check-to-DELETE gap.
+`cleanup --apply` validates the full ledger before issuing any request and rejects legacy entries
+without server identity, mixed-server ledgers, entries for another DSS URL, and app cleanup entries
+without a valid incarnation binding.
+
+Saving `version`/`versionNotes` in the public app manifest is a metadata write, not a publish
+transaction. If the manifest PUT or its verification read has an ambiguous transport/server
+failure, the command exits non-zero with `persisted:null`, `after:null`, and
+`outcome:"indeterminate"` rather than claiming the write failed or succeeded. Existing instances
+are never upgraded in place: new instances inherit the template's
+raw `version`, and an existing instance is rolled forward by creating an additive successor (the
+old instance is preserved) followed by a separate, guarded retirement. `verify-instance` never
+reports visual verification: its output is `apiReady:true` with
+`status:"API_VERIFIED_UI_PENDING"` and `uiPublicationVerified:false`. Its `visual-ui` gate names
+the required authentication and evidence: open the instance in a pre-authenticated SSO browser or
+with a dedicated UI test identity, then exercise the affected tiles, forms, and actions. The CLI
+never marks that external check complete. The public DSS APIs used by this SDK do not expose a
+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.
+
 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": "..." }`.

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

@@ -30,6 +30,11 @@ export declare const ProjectDetailsSchema: import("@sinclair/typebox").TObject<{
     name: import("@sinclair/typebox").TString;
     shortDesc: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     projectStatus: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    projectAppType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    creationTag: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        versionNumber: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        lastModifiedOn: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TString]>>;
+    }>>;
     ownerLogin: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     versionTag: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{

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

@@ -86,6 +86,11 @@ export const ProjectDetailsSchema = Type.Object({
     name: Type.String(),
     shortDesc: Type.Optional(Type.String()),
     projectStatus: Type.Optional(Type.String()),
+    projectAppType: Type.Optional(Type.String()),
+    creationTag: Type.Optional(Type.Object({
+        versionNumber: Type.Optional(Type.Number()),
+        lastModifiedOn: Type.Optional(Type.Union([Type.Number(), Type.String(),])),
+    }, { additionalProperties: true, })),
     ownerLogin: Type.Optional(Type.String()),
     tags: Type.Optional(Type.Array(Type.String())),
     versionTag: Type.Optional(Type.Object({

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

@@ -4,10 +4,8 @@ export declare function jobBuildTargetType(v: string | boolean | undefined): Job
 export declare function jobBuildTargetTypeFromFlags(flags: Record<string, string | boolean>): JobBuildTargetType;
 export declare function maxLogLinesFromFlags(flags: Record<string, string | boolean>): number | undefined;
 export declare function jobLogFilterFromFlag(v: string | boolean | undefined): JobLogFilter | undefined;
-export declare function sha256Hex(value: string): string;
+export { sha256Hex, stableHash, stableJson, } from "../utils/stable-hash.js";
 export declare function normalizeLineEndings(value: string): string;
-export declare function stableJson(value: unknown): string;
-export declare function stableHash(value: unknown): string;
 export declare function splitCsvFlag(v: string | boolean | undefined): string[];
 export declare function recipeInputDatasetsFromFlags(flags: Record<string, string | boolean>): string[] | undefined;
 export declare function rewritePairsFromFlags(flags: Record<string, string | boolean>, flagName: string): Record<string, string>;

package/dist/src/cli/coerce.js

@@ -1,4 +1,3 @@
-import { createHash, } from "node:crypto";
 import { readFileSync, } from "node:fs";
 import { UsageError, } from "./usage.js";
 export function num(v) {
@@ -37,25 +36,10 @@ export function jobLogFilterFromFlag(v) {
     }
     throw new UsageError("Invalid --log-filter value. Use stdout, stderr, user, or errors.", "invalid_enum");
 }
-export function sha256Hex(value) {
-    return createHash("sha256").update(value).digest("hex");
-}
+export { sha256Hex, stableHash, stableJson, } from "../utils/stable-hash.js";
 export function normalizeLineEndings(value) {
     return value.replace(/\r\n/g, "\n");
 }
-export function stableJson(value) {
-    if (value === undefined)
-        return "undefined";
-    if (value === null || typeof value !== "object")
-        return JSON.stringify(value);
-    if (Array.isArray(value))
-        return `[${value.map((item) => stableJson(item)).join(",")}]`;
-    const entries = Object.entries(value).sort(([a,], [b,]) => a.localeCompare(b));
-    return `{${entries.map(([key, item,]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
-}
-export function stableHash(value) {
-    return sha256Hex(stableJson(value));
-}
 export function splitCsvFlag(v) {
     if (typeof v !== "string")
         return [];