dataiku-sdk 3.2.0 → 3.3.0

package/dist/src/cli/flags.js

@@ -61,6 +61,10 @@ export const BOOLEAN_FLAGS = new Set([
     "peek",
     "raw-data",
     "all",
+    "connected",
+    "conda",
+    "force",
+    "partitioning-folder",
 ]);
 export const SHORT_FLAGS = {
     v: "verbose",
@@ -82,9 +86,12 @@ export const VALUE_FLAGS = new Set([
     "owner",
     "topic",
     "reply",
-    "text",
+    "configuration",
     "partitions",
     "since",
+    "keys",
+    "candidates",
+    "text",
     "activity",
     "agent",
     "api-key",
@@ -225,6 +232,28 @@ export const VALUE_FLAGS = new Set([
     "to",
     "zone",
     "zone-id",
+    "purpose",
+    "step-id",
+    "max-bytes",
+    "type-option-id",
+    "format-option-id",
+    "copy-partitioning-from",
+    "creation-mode",
+    "max-dataset-count",
+    "logins",
+    "max-log-bytes",
+    "llm-id",
+    "remove-intermediate",
+    "code-env",
+    "container-exec-config",
+    "set-active",
+    "binary-classification-threshold",
+    "sampling",
+    "use-optimal-threshold",
+    "skip-expensive-reports",
+    "full-class-name",
+    "include-libs",
+    "archive",
 ]);
 export const REPEATABLE_VALUE_FLAGS = new Set([
     "dataset",

package/dist/src/cli/helpers/app-successor.d.ts

@@ -13,6 +13,14 @@ export declare const VISUAL_UI_GATE: {
     readonly requiredAuthentication: "pre-authenticated-sso-or-dedicated-ui-test-identity";
     readonly evidenceRequired: "Open the instance in the Dataiku Apps UI and exercise the affected tiles, forms, and actions to confirm the release behaves as intended.";
 };
+/**
+ * The one generated instance-key shape shared by `app create-instance` and
+ * `app create-successor-instance` when no caller-chosen target is supplied:
+ * `APP_` plus 122 random bits of UUIDv4 hex, matching the official client's
+ * random-key mode. Collisions are negligible, so a generated key is never
+ * probed for absence and is never retried under an alternate key.
+ */
+export declare function generatedInstanceKey(): string;
 export type AppInstanceCheckName = "project-type" | "app-registration" | "manifest-version" | "manifest-references";
 export interface AppInstanceCheck {
     check: AppInstanceCheckName;
@@ -46,7 +54,11 @@ export interface AppInstanceVerification {
 export interface SuccessorInstanceRequest {
     appId: string;
     from: string;
-    to: string;
+    /**
+     * Caller-chosen successor key. Omitted for generated-key mode: the key is
+     * generated once during apply and DSS's own creation future names it.
+     */
+    to?: string;
     name?: string;
     copyPermissions: boolean;
     dryRun: boolean;
@@ -92,9 +104,12 @@ interface TargetAbsenceContext {
     visibleAppInstanceKeys?: readonly (string | undefined)[];
 }
 /**
- * Creation cleanup is safe only when the target was proven absent before POST.
- * A hidden 403 is not absence: project listing can prove a collision, but it
- * cannot prove that an inaccessible project does not exist.
+ * Caller-chosen-key guard: when the caller supplies the target key, creation
+ * cleanup is safe only when that target was proven absent before POST. A
+ * hidden 403 is not absence: project listing can prove a collision, but it
+ * cannot prove that an inaccessible project does not exist. Generated keys
+ * (app create-instance with targetProjectKey omitted) skip this guard: a
+ * freshly generated random key does not need an absence probe.
  */
 export declare function requireAbsentProjectTarget(client: DataikuClient, targetProjectKey: string, targetFlag: "--to" | "targetProjectKey", context: TargetAbsenceContext): Promise<void>;
 /**

package/dist/src/cli/helpers/app-successor.js

@@ -1,3 +1,4 @@
+import { randomUUID, } from "node:crypto";
 import { DataikuError, } from "../../errors.js";
 import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
 import { stableHash, stringField, } from "../coerce.js";
@@ -17,6 +18,16 @@ export const VISUAL_UI_GATE = {
     requiredAuthentication: "pre-authenticated-sso-or-dedicated-ui-test-identity",
     evidenceRequired: "Open the instance in the Dataiku Apps UI and exercise the affected tiles, forms, and actions to confirm the release behaves as intended.",
 };
+/**
+ * The one generated instance-key shape shared by `app create-instance` and
+ * `app create-successor-instance` when no caller-chosen target is supplied:
+ * `APP_` plus 122 random bits of UUIDv4 hex, matching the official client's
+ * random-key mode. Collisions are negligible, so a generated key is never
+ * probed for absence and is never retried under an alternate key.
+ */
+export function generatedInstanceKey() {
+    return `APP_${randomUUID().replace(/-/g, "").toUpperCase()}`;
+}
 /**
  * DSS answers the app-manifest probe with 400 ("neither an app template nor an
  * app instance") for ordinary projects and 404 for missing ones. Both mean "not
@@ -183,9 +194,12 @@ export function futureTargetIdentity(result) {
     return null;
 }
 /**
- * Creation cleanup is safe only when the target was proven absent before POST.
- * A hidden 403 is not absence: project listing can prove a collision, but it
- * cannot prove that an inaccessible project does not exist.
+ * Caller-chosen-key guard: when the caller supplies the target key, creation
+ * cleanup is safe only when that target was proven absent before POST. A
+ * hidden 403 is not absence: project listing can prove a collision, but it
+ * cannot prove that an inaccessible project does not exist. Generated keys
+ * (app create-instance with targetProjectKey omitted) skip this guard: a
+ * freshly generated random key does not need an absence probe.
  */
 export async function requireAbsentProjectTarget(client, targetProjectKey, targetFlag, context) {
     if (context.visibleAppInstanceKeys?.includes(targetProjectKey) === true) {
@@ -251,11 +265,14 @@ export async function requireAbsentProjectTarget(client, targetProjectKey, targe
             creationPostAttempted: false,
         };
         if (targetVisibleInProjectList !== true && targetVisibleInAppInstances !== true) {
-            throw new UsageError(`Could not confirm target project ${targetProjectKey} is absent.`, "target_absence_unverifiable", "DSS exposes no permission-independent project-key availability endpoint, and app-instance creation has no published atomic duplicate-key guarantee. Retry with an identity that has global project visibility; creation was not attempted.", {
+            throw new UsageError(`Could not confirm target project ${targetProjectKey} is absent.`, "target_absence_unverifiable", "Creation was not attempted. For a fresh instance with a different key, omit targetProjectKey from `dss app create-instance`. To keep this exact key, retry with an identity that has global project visibility. DSS exposes no permission-independent key-availability endpoint or published atomic duplicate-key guarantee.", {
                 ...probeDetails,
                 targetProbe: "forbidden-and-not-listable",
                 deploymentMasksUnknownProjects: "possible-but-unproven",
-                supportedRecoveryModes: ["grant-global-project-visibility",],
+                supportedRecoveryModes: [
+                    "create-instance-with-generated-key",
+                    "grant-global-project-visibility",
+                ],
                 unavailableRecoveryModes: [
                     "use-supported-key-availability-endpoint",
                     "server-atomic-create",
@@ -272,7 +289,7 @@ export async function requireAbsentProjectTarget(client, targetProjectKey, targe
  */
 async function preflightSuccessor(client, request, usage) {
     const { appId, from, to, } = request;
-    if (from === to) {
+    if (to !== undefined && from === to) {
         throw new UsageError("--from and --to must be different project keys: a successor instance is created alongside its predecessor.", "validation_failed", `Usage: ${usage}`, { sourceProjectKey: from, targetProjectKey: to, });
     }
     const instances = await client.applications.listInstances(appId);
@@ -290,10 +307,16 @@ async function preflightSuccessor(client, request, usage) {
     if (source.projectAppType !== "APP_INSTANCE") {
         throw new UsageError(`Project ${from} is a ${source.projectAppType ?? "non-app"} project, not a classic Dataiku App instance.`, "validation_failed", "--from must name an APP_INSTANCE project; app templates are versioned with `dss app set-manifest-version`.", { sourceProjectKey: from, projectAppType: source.projectAppType ?? null, });
     }
-    await requireAbsentProjectTarget(client, to, "--to", {
-        appId,
-        visibleAppInstanceKeys: instances.map((instance) => instance.projectKey),
-    });
+    if (to !== undefined) {
+        // Caller-chosen keys must be proven absent before the single POST.
+        // Generated keys skip the probe entirely: the key does not exist yet,
+        // so an absence probe would prove nothing and probe a project the
+        // caller never named.
+        await requireAbsentProjectTarget(client, to, "--to", {
+            appId,
+            visibleAppInstanceKeys: instances.map((instance) => instance.projectKey),
+        });
+    }
     const templateManifest = await client.applications.getAppManifest(appId);
     const templateVersion = rawVersion(templateManifest);
     if (templateVersion === null) {
@@ -317,8 +340,10 @@ async function preflightSuccessor(client, request, usage) {
         sourceProjectAppType: source.projectAppType,
         sourceVersion: source.version,
         sourceManifestHash: source.manifestHash,
-        targetProjectName: request.name ?? to,
-        targetExists: false,
+        generatedTarget: to === undefined,
+        ...(request.name !== undefined || to !== undefined
+            ? { targetProjectName: request.name ?? to, }
+            : {}),
         templateManifestHash: stableHash(templateManifest),
         templateVersion,
         templateReferenceValidation,
@@ -343,6 +368,7 @@ export async function preflightSuccessorInstance(client, request, usage) {
         preflightExecuted: true,
         creationPostAttempted: false,
         versionMutationAttempted: false,
+        ...(preflight.generatedTarget ? { targetProjectKeyGeneratedDuringApply: true, } : {}),
         appId: request.appId,
         source: {
             projectKey: request.from,
@@ -353,12 +379,28 @@ export async function preflightSuccessorInstance(client, request, usage) {
                 ? { permissionsHash: preflight.sourcePermissionsHash, }
                 : {}),
         },
-        target: {
-            projectKey: request.to,
-            name: preflight.targetProjectName,
-            exists: false,
-        },
-        targetPreflight: "confirmed-absent",
+        ...(preflight.generatedTarget
+            ? {
+                // Generated mode: the target key does not exist yet, so no
+                // absence probe ran and none can be claimed. The plan/receipt
+                // names no key at all: it is generated once during apply and
+                // named by DSS's own terminal creation future.
+                target: {
+                    targetProjectKeyGeneratedDuringApply: true,
+                    ...(preflight.targetProjectName !== undefined
+                        ? { name: preflight.targetProjectName, }
+                        : { targetProjectNameGeneratedDuringApply: true, }),
+                },
+                targetPreflight: "not-applicable-generated-key",
+            }
+            : {
+                target: {
+                    projectKey: request.to,
+                    name: preflight.targetProjectName,
+                    exists: false,
+                },
+                targetPreflight: "confirmed-absent",
+            }),
         template: {
             projectKey: request.appId,
             version: preflight.templateVersion,
@@ -372,7 +414,7 @@ export async function preflightSuccessorInstance(client, request, usage) {
         copyPermissions: request.copyPermissions,
         next: {
             setVersion: `dss app set-manifest-version --manifest-version <VERSION> --expect-hash ${preflight.templateManifestHash} --project-key ${request.appId}`,
-            createSuccessor: `dss app create-successor-instance ${request.appId} --from ${request.from} --to ${request.to}${request.name !== undefined ? ` --name ${JSON.stringify(request.name)}` : ""}${request.copyPermissions ? " --copy-permissions" : ""}`,
+            createSuccessor: `dss app create-successor-instance ${request.appId} --from ${request.from}${request.to !== undefined ? ` --to ${request.to}` : ""}${request.name !== undefined ? ` --name ${JSON.stringify(request.name)}` : ""}${request.copyPermissions ? " --copy-permissions" : ""}`,
         },
     };
 }
@@ -388,7 +430,8 @@ export async function preflightSuccessorInstance(client, request, usage) {
  * indeterminate and produces no cleanup entry.
  */
 export async function createSuccessorInstance(client, request, usage) {
-    const { appId, from, to, } = request;
+    const { appId, from, } = request;
+    const generatedTarget = request.to === undefined;
     const preflight = await preflightSuccessor(client, request, usage);
     const source = {
         projectKey: from,
@@ -408,27 +451,44 @@ export async function createSuccessorInstance(client, request, usage) {
         sourcePreserved: true,
         uiPublicationVerified: false,
         requiredExternalGates: [VISUAL_UI_GATE,],
-        targetPreflight: "confirmed-absent",
+        // Generated mode never probes a target, so it must not claim the
+        // probe-backed absence verdict: no target existed to verify.
+        targetPreflight: generatedTarget ? "not-applicable-generated-key" : "confirmed-absent",
     };
     if (request.dryRun) {
         return {
             dryRun: true,
             action: "create-successor-instance",
             ...shared,
-            target: {
-                projectKey: to,
-                name: preflight.targetProjectName,
-                exists: false,
-            },
+            ...(generatedTarget
+                ? { targetProjectKeyGeneratedDuringApply: true, }
+                : {}),
+            target: generatedTarget
+                ? {
+                    targetProjectKeyGeneratedDuringApply: true,
+                    ...(preflight.targetProjectName !== undefined
+                        ? { name: preflight.targetProjectName, }
+                        : { targetProjectNameGeneratedDuringApply: true, }),
+                }
+                : {
+                    projectKey: request.to,
+                    name: preflight.targetProjectName,
+                    exists: false,
+                },
             copyPermissions: request.copyPermissions,
             preflight: "passed",
         };
     }
+    // Generated exactly once, here, immediately before the single POST: plan,
+    // preflight and dry-run never allocate. A definitive rejection does not
+    // retry and does not fall back to an alternate key.
+    const to = request.to ?? generatedInstanceKey();
+    const targetProjectName = preflight.targetProjectName ?? to;
     let created;
     try {
         created = await client.applications.createInstance(appId, {
             targetProjectKey: to,
-            targetProjectName: preflight.targetProjectName,
+            targetProjectName,
         });
     }
     catch (error) {
@@ -436,7 +496,7 @@ export async function createSuccessorInstance(client, request, usage) {
         return {
             ...shared,
             projectKey: to,
-            target: { projectKey: to, name: preflight.targetProjectName, },
+            target: { projectKey: to, name: targetProjectName, },
             success: false,
             state: rejected ? "CREATE_FAILED" : "INDETERMINATE",
             elapsedMs: 0,
@@ -465,7 +525,7 @@ export async function createSuccessorInstance(client, request, usage) {
         return {
             ...shared,
             projectKey: to,
-            target: { projectKey: to, name: preflight.targetProjectName, },
+            target: { projectKey: to, name: targetProjectName, },
             success: false,
             state: "VERIFICATION_FAILED",
             elapsedMs: 0,
@@ -485,7 +545,7 @@ export async function createSuccessorInstance(client, request, usage) {
     const base = {
         ...shared,
         projectKey: to,
-        target: { projectKey: to, name: preflight.targetProjectName, },
+        target: { projectKey: to, name: targetProjectName, },
         ...(instance ? { instance, } : {}),
     };
     let waited;

package/dist/src/cli/helpers/cleanup.js

@@ -280,7 +280,9 @@ export function cleanupLedgerEntry(resource, action, args, flags, result, projec
             };
         }
         case "notebook.save-sql": {
-            const id = args[0];
+            // On create the persisted id is the server receipt (`saved`), not the
+            // requested handle, which only becomes the display name.
+            const id = stringField(record, ["saved", "id",]) ?? args[0];
             if (!id)
                 return undefined;
             return {

package/dist/src/cli/helpers/flow-zone.js

@@ -116,8 +116,7 @@ export function flowZonePlanPosition(value, source) {
     };
 }
 export function flowZoneCurrentPosition(zone) {
-    const record = zone;
-    const position = plainRecord(record.position);
+    const position = plainRecord(zone.position);
     if (!position)
         return undefined;
     const x = position.x;

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

@@ -10,7 +10,7 @@ export declare function pickResultFields(item: unknown, fields: string[]): unkno
  * element-wise; scalars and string results pass through untouched. Requested keys
  * that are absent become null so every row keeps a stable, predictable shape.
  */
-export declare function projectResultFields(result: unknown, fields: string[]): unknown;
+export declare function projectResultFields(result: unknown, fields: string[], availableFieldNames?: () => string[]): unknown;
 export declare function writeCommandResult(result: unknown): void;
 export declare function transientBodyWithTargetContext(body: string, target: string, elapsedMs: number): string;
 export declare function addTransientTargetContext(error: unknown, target: string, elapsedMs: number): never;

package/dist/src/cli/output.js

@@ -47,14 +47,15 @@ function projectionRecords(result) {
     const items = Array.isArray(result) ? result : [result,];
     return items.filter((item) => item !== null && typeof item === "object" && !Array.isArray(item));
 }
-function warnUnknownProjectionFields(result, fields) {
+function warnUnknownProjectionFields(result, fields, availableFieldNames) {
     const records = projectionRecords(result);
     if (records.length === 0)
         return;
     const unknownFields = fields.filter((field) => !records.some((record) => resolveFieldPath(record, field).found));
     if (unknownFields.length === 0)
         return;
-    const availableFields = [...new Set(records.flatMap((record) => Object.keys(record))),].sort();
+    const availableFields = availableFieldNames?.()
+        ?? [...new Set(records.flatMap((record) => Object.keys(record))),].sort();
     enqueueCliWarning({
         code: "field_projection_missing",
         fields: unknownFields,
@@ -67,8 +68,8 @@ function warnUnknownProjectionFields(result, fields) {
  * element-wise; scalars and string results pass through untouched. Requested keys
  * that are absent become null so every row keeps a stable, predictable shape.
  */
-export function projectResultFields(result, fields) {
-    warnUnknownProjectionFields(result, fields);
+export function projectResultFields(result, fields, availableFieldNames) {
+    warnUnknownProjectionFields(result, fields, availableFieldNames);
     if (Array.isArray(result))
         return result.map((item) => pickResultFields(item, fields));
     return pickResultFields(result, fields);
@@ -98,7 +99,7 @@ export function transientBodyWithTargetContext(body, target, elapsedMs) {
 }
 export function addTransientTargetContext(error, target, elapsedMs) {
     if (error instanceof DataikuError && error.category === "transient") {
-        throw new DataikuError(error.status, error.statusText, transientBodyWithTargetContext(error.body, target, elapsedMs), error.retry, error.requestId, { target, elapsedMs, });
+        throw new DataikuError(error.status, error.statusText, transientBodyWithTargetContext(error.body, target, elapsedMs), error.retry, error.requestId, { target, elapsedMs, bodyTruncated: error.bodyTruncated, });
     }
     throw error;
 }
@@ -106,10 +107,16 @@ export function isFailedWaitResult(result) {
     if (result === null || typeof result !== "object" || Array.isArray(result))
         return false;
     const record = result;
-    return record.success === false
-        && typeof record.elapsedMs === "number"
-        && typeof record.pollCount === "number"
-        && (typeof record.state === "string" || typeof record.outcome === "string");
+    if (record.success !== false)
+        return false;
+    if (typeof record.elapsedMs !== "number" || typeof record.pollCount !== "number")
+        return false;
+    // Job/future wait results name the terminal state as a string; macro wait
+    // results identify themselves by their runnable identity fields with the
+    // poll state attached as an object (or omitted entirely).
+    if (typeof record.state === "string" || typeof record.outcome === "string")
+        return true;
+    return typeof record.runnableType === "string" && typeof record.runId === "string";
 }
 export function isAssertionFailureResult(result) {
     if (result === null || typeof result !== "object" || Array.isArray(result))
@@ -172,7 +179,13 @@ export class CommandResultFailure extends Error {
 export function commandFailureMessage(result) {
     if (isFailedWaitResult(result)) {
         const record = result;
-        const state = typeof record.state === "string" ? record.state : record.outcome;
+        const state = typeof record.state === "string"
+            ? record.state
+            : typeof record.outcome === "string"
+                ? record.outcome
+                : typeof record.timedOut === "boolean"
+                    ? "timed out"
+                    : undefined;
         return `Command completed with failed long-running result${state ? `: ${state}` : ""}.`;
     }
     if (isAssertionFailureResult(result)) {

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

@@ -1,5 +1,6 @@
 import type { StableErrorCode } from "../errors.js";
 export declare const RESOURCE_NAMES: string[];
+export declare function inferRequiresProject(resource: string, action: string, usage: string): boolean;
 export declare class UsageError extends Error {
     readonly code: StableErrorCode;
     readonly hint?: string;

package/dist/src/cli/usage.js

@@ -9,6 +9,15 @@ export const RESOURCE_NAMES = [
     "bundle",
     "project-deployer",
     "project-git",
+    "project-folder",
+    "data-collection",
+    "llm",
+    "knowledge-bank",
+    "macro",
+    "plugin",
+    "user",
+    "group",
+    "project",
     "project-library",
     "streaming-endpoint",
     "continuous-activity",
@@ -44,10 +53,47 @@ export const RESOURCE_NAMES = [
     "commands",
     "fixtures",
     "install-skill",
-    "project",
     "version",
 ]
     .sort();
+const PROJECT_SCOPED_RESOURCES = new Set([
+    "analysis",
+    "data-quality",
+    "dashboard",
+    "knowledge-bank",
+    "dataset",
+    "llm",
+    "flow-zone",
+    "insight",
+    "folder",
+    "fixtures",
+    "job",
+    "notebook",
+    "macro",
+    "ml-task",
+    "model-evaluation-store",
+    "recipe",
+    "scenario",
+    "sql",
+    "variable",
+    "saved-model",
+    "wiki",
+]);
+export function inferRequiresProject(resource, action, usage) {
+    if (resource === "agent" || resource === "auth" || resource === "doctor" || resource === "commands"
+        || resource === "install-skill" || resource === "version")
+        return false;
+    if (resource === "sql" && action === "query")
+        return false;
+    if (PROJECT_SCOPED_RESOURCES.has(resource))
+        return true;
+    // Plugin project scope is optional, not a requirement.
+    if (resource === "plugin")
+        return false;
+    if (resource === "project-git")
+        return !action.startsWith("future-");
+    return usage.includes("--project-key");
+}
 export class UsageError extends Error {
     code;
     hint;