dataiku-sdk 1.0.0 → 2.0.0

package/dist/src/cli/contract.js

@@ -234,7 +234,7 @@ const AGENT_CONTRACT_EXAMPLES = [
     "dss agent contract --fields commands.actions",
 ];
 const VERSION_USAGE = "dss version";
-const VERSION_DESCRIPTION = "Print the CLI version and git revision as JSON.";
+const VERSION_DESCRIPTION = "Print the CLI version, checkout/build revisions, load source, runtime, and stale-build status as JSON.";
 const VERSION_EXAMPLES = ["dss version", "dss --version",];
 const INSTALL_SKILL_USAGE = "dss install-skill [--global] [--agent NAME] [--target PATH] [--list-agents] [--dry-run] [--plan]";
 const INSTALL_SKILL_DESCRIPTION = "Install the dataiku-dss agent skill for detected coding agents.";
@@ -270,6 +270,7 @@ const ALLOWED_CLEANUP_ACTIONS = new Set([
     "code-env delete",
     "folder delete",
     "folder delete-file",
+    "project delete",
     "app delete-instance",
 ]);
 export function isAllowedCleanupAction(resource, action) {
@@ -676,6 +677,7 @@ export function inferRequiresProject(resource, action, usage) {
 const ARRAY_OUTPUT_ACTIONS = new Set([
     "history",
     "find",
+    "files",
     "infer",
     "last-results",
     "list",
@@ -861,6 +863,9 @@ function inferPayloadSchema(inputContract) {
 function inferExitCodes(resource, action, asyncKind) {
     const longRunning = asyncKind !== "none" || `${resource}.${action}` === "batch.run";
     const assertion = `${resource}.${action}` === "recipe.assert-unchanged"
+        || `${resource}.${action}` === "dataset.assert-count"
+        || `${resource}.${action}` === "dataset.assert-schema"
+        || `${resource}.${action}` === "data-quality.assert-results"
         || `${resource}.${action}` === "batch.run";
     return {
         ok: 0,
@@ -872,6 +877,9 @@ function inferExitCodes(resource, action, asyncKind) {
     };
 }
 function cleanupCommandFromDeleteUsage(resource, action) {
+    if (`${resource}.${action}` === "project.import") {
+        return "dss project delete <used-project-key> --if-exists --expect-project-incarnation <hash>";
+    }
     if (resource === "project" && (action === "create" || action === "duplicate")) {
         return undefined;
     }
@@ -895,9 +903,20 @@ export function supportsCleanupLedger(resource, action) {
     return cleanupCommandFromDeleteUsage(resource, action) !== undefined
         || `${resource}.${action}` === "folder.upload";
 }
+/**
+ * Write actions that no public DSS route can undo. `dataset upload-file` adds a
+ * file to the dataset's uploaded-files set, and DSS exposes no endpoint to
+ * replace or delete an individual uploaded file, so the write is permanent and
+ * no cleanup-ledger entry can recover the previous file set.
+ */
+const EXPLICIT_DESTRUCTIVE_KEYS = {
+    "dataset.upload-file": true,
+};
 function inferDestructiveLevel(resource, sideEffect, action) {
     if (sideEffect !== "write")
         return "none";
+    if (EXPLICIT_DESTRUCTIVE_KEYS[`${resource}.${action}`] === true)
+        return "destructive";
     if (resource === "project-git") {
         return PROJECT_GIT_DESTRUCTIVE_ACTIONS[action] === true ? "destructive" : "reversible";
     }
@@ -992,7 +1011,7 @@ export function inferCleanupHint(resource, action) {
     return `Delete with \`dss ${resource} delete <id>${ifExists}\` when the created object is disposable.`;
 }
 function buildRegistryEntry(resource, action, meta) {
-    const requiresAuth = inferRequiresAuth(resource);
+    const requiresAuth = meta.localHandler === undefined && inferRequiresAuth(resource);
     const requiresProject = inferRequiresProject(resource, action, meta.usage);
     const sideEffect = inferSideEffect(resource, action);
     const destructive = inferDestructiveLevel(resource, sideEffect, action);
@@ -1781,6 +1800,38 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: { oldName: args[0], newName: args[1], },
                 payload: { oldName: args[0], newName: args[1], },
             };
+        case "dataset.upload-file": {
+            const fileName = requiredPlanFlag(flags, "file-name", entry.usage);
+            const datasetEndpoint = projectEndpoint(`/datasets/${encodeURIComponent(args[0])}`);
+            const filesEndpoint = `${datasetEndpoint}/uploaded/files`;
+            const upload = {
+                method: "POST",
+                endpoint: filesEndpoint,
+                payload: { ...uploadPayload(args[1]), fileName, },
+            };
+            return {
+                ...upload,
+                identifiers: {
+                    datasetName: args[0],
+                    localPath: args[1],
+                    fileName,
+                },
+                requests: [
+                    { sequence: 1, method: "GET", endpoint: datasetEndpoint, },
+                    { sequence: 2, method: "GET", endpoint: filesEndpoint, },
+                    { sequence: 3, ...upload, },
+                    {
+                        sequence: 4,
+                        method: "GET",
+                        endpoint: filesEndpoint,
+                        assert: {
+                            filename: fileName,
+                            length: "local file byte length",
+                        },
+                    },
+                ],
+            };
+        }
         case "dataset.delete":
             return {
                 method: "DELETE",
@@ -2264,6 +2315,8 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: {
                     appId: id,
                     targetProjectKey,
+                    preflightExecuted: false,
+                    preflightWillRunDuringApply: true,
                     incarnationControl: "client-side-non-atomic-future-target-and-creation-tag-join",
                     incarnationObservationRequests: [
                         {
@@ -2286,7 +2339,13 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                             method: "GET",
                             endpoint: "/public/api/projects/",
                             when: "conditional",
-                            intent: "Fallback list probe issued only when the direct project GET is forbidden (403) to confirm the target is absent; an unconfirmed target rejects creation.",
+                            intent: "Fallback list probe issued only when the direct project GET is forbidden (403). Presence proves a collision; absence cannot prove availability.",
+                        },
+                        {
+                            method: "GET",
+                            endpoint: `/public/api/apps/${encodeURIComponent(id)}/instances/`,
+                            when: "conditional",
+                            intent: "Fallback app-instance list probe issued when the direct project GET is forbidden (403). Presence proves a collision; absence still rejects creation as unverifiable.",
                         },
                     ],
                     note: "Strict preflight: the instance POST runs only after the payload targetProjectKey is confirmed absent. Creation never writes into an existing or unprovable project.",
@@ -2348,6 +2407,8 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                     appId: id,
                     sourceProjectKey,
                     targetProjectKey,
+                    preflightExecuted: false,
+                    preflightWillRunDuringApply: true,
                     ...(targetProjectName !== undefined ? { targetProjectName, } : {}),
                     copyPermissions,
                     incarnationControl: "client-side-non-atomic-future-target-and-creation-tag-join",
@@ -2386,7 +2447,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                             method: "GET",
                             endpoint: "/public/api/projects/",
                             when: "conditional",
-                            intent: "Fallback list probe issued only when the direct project GET is forbidden (403) to confirm the target is absent; an unconfirmed target rejects creation.",
+                            intent: "Fallback list probe issued only when the direct project GET is forbidden (403). Presence proves a collision; absence cannot prove availability and rejects creation.",
                         },
                     ],
                     ...(copyPermissions
@@ -2812,17 +2873,74 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 },
             };
         }
-        case "project.delete":
+        case "project.delete": {
+            const expectedProjectIncarnation = flags["expect-project-incarnation"] === undefined
+                ? undefined
+                : requiredPlanFlag(flags, "expect-project-incarnation", entry.usage);
+            if (expectedProjectIncarnation !== undefined
+                && !/^[0-9a-f]{64}$/.test(expectedProjectIncarnation)) {
+                throw new UsageError("--expect-project-incarnation must be a 64-character lowercase SHA-256 hash.", "validation_failed");
+            }
+            const endpoint = `/public/api/projects/${encodeURIComponent(id)}${querySuffix({
+                clearManagedDatasets: flags["drop-data"] === true,
+                clearOutputManagedFolders: false,
+                clearJobAndScenarioLogs: true,
+                wait: true,
+            })}`;
+            const guarded = flags["if-exists"] === true
+                || flags["dry-run"] === true
+                || expectedProjectIncarnation !== undefined;
+            if (!guarded) {
+                return {
+                    method: "DELETE",
+                    endpoint,
+                    identifiers: { projectKey: id, },
+                };
+            }
+            const projectProbe = `/public/api/projects/${encodeURIComponent(id)}/`;
+            const incarnationGate = expectedProjectIncarnation === undefined
+                ? { required: false, provided: false, }
+                : {
+                    required: true,
+                    provided: true,
+                    expectedHash: expectedProjectIncarnation,
+                };
+            if (flags["dry-run"] === true) {
+                return {
+                    method: "GET",
+                    endpoint: projectProbe,
+                    identifiers: {
+                        projectKey: id,
+                        dryRun: true,
+                        ifExists: flags["if-exists"] === true,
+                        projectIncarnationGate: incarnationGate,
+                        note: "Read-only guarded-delete preflight. No DELETE is issued; a supplied creationTag hash must match.",
+                    },
+                };
+            }
             return {
                 method: "DELETE",
-                endpoint: `/public/api/projects/${encodeURIComponent(id)}${querySuffix({
-                    clearManagedDatasets: flags["drop-data"] === true,
-                    clearOutputManagedFolders: false,
-                    clearJobAndScenarioLogs: true,
-                    wait: true,
-                })}`,
-                identifiers: { projectKey: id, },
+                endpoint,
+                identifiers: {
+                    projectKey: id,
+                    ifExists: flags["if-exists"] === true,
+                    projectIncarnationGate: incarnationGate,
+                    incarnationControl: expectedProjectIncarnation === undefined
+                        ? "none"
+                        : "client-side-non-atomic-stale-identity-check",
+                    preflightRequests: [{
+                            method: "GET",
+                            endpoint: projectProbe,
+                            intent: expectedProjectIncarnation === undefined
+                                ? "Confirm existence before a convergent delete."
+                                : "Recompute the current project-incarnation hash from creationTag before DELETE.",
+                        },],
+                    note: expectedProjectIncarnation === undefined
+                        ? "Convergent delete: a 404 preflight is an already-absent success only with --if-exists."
+                        : "Incarnation-bound delete: the GET must match the expected creationTag hash before an unconditional DELETE. DSS exposes no conditional project DELETE, so the client-side gate cannot serialize against key reuse after the GET.",
+                },
             };
+        }
         case "project.duplicate": {
             const options = jsonInput(flags);
             return {
@@ -2844,11 +2962,32 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 },
             };
         }
-        case "project.import":
-            return {
+        case "project.import": {
+            const settings = jsonInput(flags) ?? {};
+            const rawTarget = flags["target-project-key"];
+            const targetProjectKey = rawTarget?.trim();
+            if (rawTarget !== undefined && targetProjectKey === "") {
+                throw new UsageError(`--target-project-key must not be empty. Usage: ${entry.usage}`);
+            }
+            const settingsTarget = settings.targetProjectKey;
+            if (settingsTarget !== undefined
+                && (typeof settingsTarget !== "string" || settingsTarget.trim() === "")) {
+                throw new UsageError(`targetProjectKey in import settings must be a non-empty string. Usage: ${entry.usage}`);
+            }
+            if (targetProjectKey !== undefined
+                && settingsTarget !== undefined
+                && targetProjectKey !== settingsTarget.trim()) {
+                throw new UsageError(`--target-project-key conflicts with targetProjectKey in import settings. Usage: ${entry.usage}`);
+            }
+            const processPayload = targetProjectKey === undefined
+                ? settings
+                : { ...settings, targetProjectKey, };
+            const finalizedPayload = Object.keys(processPayload).length === 0
+                ? { _: "_", }
+                : processPayload;
+            const upload = {
                 method: "POST",
                 endpoint: "/public/api/projects/import/upload",
-                identifiers: { filePath: id, },
                 payload: {
                     contentType: "multipart/form-data",
                     fileField: "file",
@@ -2856,6 +2995,46 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                     fileName: "tmp-import.zip",
                 },
             };
+            return {
+                ...upload,
+                identifiers: {
+                    filePath: id,
+                    ...(targetProjectKey ? { targetProjectKey, } : {}),
+                    archivePreflight: {
+                        local: true,
+                        required: true,
+                        checks: [
+                            "zip-integrity",
+                            "safe-unique-members",
+                            "manifest",
+                            "flow-references",
+                            "orphan-members",
+                        ],
+                    },
+                    successVerification: {
+                        usedProjectKeyRequired: true,
+                        projectReadRequired: true,
+                        projectIncarnationRequired: true,
+                        remappingReported: true,
+                    },
+                    ...(flags["record-cleanup"] === undefined
+                        ? {}
+                        : {
+                            cleanupBinding: "actual used project key plus verified creationTag incarnation hash",
+                        }),
+                },
+                requests: [
+                    { sequence: 1, ...upload, },
+                    {
+                        sequence: 2,
+                        method: "POST",
+                        endpoint: "/public/api/projects/import/{importId}/process",
+                        pathBindings: { importId: "requests[0].response.id", },
+                        payload: finalizedPayload,
+                    },
+                ],
+            };
+        }
         case "project.settings-set":
             return {
                 method: "PUT",

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

@@ -38,6 +38,7 @@ export interface FixtureDiscoveryResult {
 export interface DoctorEnvironment {
     projectKey?: string;
     dssVersion?: string;
+    dssApiVersion?: string;
     instanceTime?: string;
     integrationFlags: {
         mutating: boolean;
@@ -48,6 +49,15 @@ export interface DoctorEnvironment {
         apiServices: boolean;
     };
 }
+/**
+ * Server provenance captured from documented response headers on the public
+ * project-list connectivity call. Null entries mean the header was absent.
+ */
+export interface DoctorVersionInfo {
+    dssVersion: string | null;
+    dssApiVersion: string | null;
+    instanceTime: string | null;
+}
 export interface DoctorResult {
     ok: boolean;
     checks: DoctorCheck[];
@@ -66,7 +76,7 @@ export interface DoctorResult {
 export declare function errorDetails(error: unknown): Record<string, unknown>;
 export declare function firstStringField(items: unknown[] | undefined, fields: string[]): string | null;
 export declare function integrationFlag(name: string): boolean;
-export declare function doctorEnvironment(projectKey?: string): DoctorEnvironment;
+export declare function doctorEnvironment(projectKey?: string, versionInfo?: DoctorVersionInfo): DoctorEnvironment;
 export declare function permissionStatusForError(error: unknown): PermissionStatus;
 export declare function probeDoctorPermission(probe: () => Promise<unknown>): Promise<{
     status: PermissionStatus;
@@ -96,7 +106,7 @@ export declare function firstSafeJupyterNotebook(items: unknown[]): {
     unsafe: FixtureReject[];
 };
 export declare function discoverFixtureReport(client: DataikuClient, projectKey: string, flags: Record<string, string | boolean>): Promise<FixtureDiscoveryResult>;
-export declare function doctorCapabilities(client: DataikuClient, projectKey: string | undefined, accessibleProjects: unknown[] | undefined, flags: Record<string, string | boolean>): Promise<Pick<DoctorResult, "permissions" | "permissionDetails" | "fixtures" | "environment">>;
+export declare function doctorCapabilities(client: DataikuClient, projectKey: string | undefined, accessibleProjects: unknown[] | undefined, flags: Record<string, string | boolean>, versionInfo?: DoctorVersionInfo): Promise<Pick<DoctorResult, "permissions" | "permissionDetails" | "fixtures" | "environment">>;
 export declare function runDoctor(flags: Record<string, string | boolean>): Promise<{
     result: DoctorResult;
     exitCode: number;

package/dist/src/cli/doctor.js

@@ -1,5 +1,6 @@
 import { DataikuClient, } from "../client.js";
 import { DataikuError, } from "../errors.js";
+import { ProjectSummaryArraySchema, safeParseSchema, } from "../schemas.js";
 import { num, splitCsvFlag, stringField, } from "./coerce.js";
 import { currentCommandContext, resolveCredentials, } from "./runtime.js";
 import { UsageError, } from "./usage.js";
@@ -31,9 +32,12 @@ export function integrationFlag(name) {
     const value = process.env[name];
     return value === "1" || value?.toLowerCase() === "true";
 }
-export function doctorEnvironment(projectKey) {
+export function doctorEnvironment(projectKey, versionInfo) {
     return {
         ...(projectKey ? { projectKey, } : {}),
+        ...(versionInfo?.dssVersion ? { dssVersion: versionInfo.dssVersion, } : {}),
+        ...(versionInfo?.dssApiVersion ? { dssApiVersion: versionInfo.dssApiVersion, } : {}),
+        ...(versionInfo?.instanceTime ? { instanceTime: versionInfo.instanceTime, } : {}),
         integrationFlags: {
             mutating: integrationFlag("RUN_DATAIKU_INTEGRATION_MUTATING"),
             adminMutating: integrationFlag("RUN_DATAIKU_ADMIN_MUTATING"),
@@ -174,7 +178,7 @@ export async function discoverFixtureReport(client, projectKey, flags) {
         },
     };
 }
-export async function doctorCapabilities(client, projectKey, accessibleProjects, flags) {
+export async function doctorCapabilities(client, projectKey, accessibleProjects, flags, versionInfo) {
     const probeProjectKey = projectKey ?? firstStringField(accessibleProjects, ["projectKey",])
         ?? undefined;
     const probes = {
@@ -210,7 +214,7 @@ export async function doctorCapabilities(client, projectKey, accessibleProjects,
     const capabilityResult = {
         permissions,
         ...(Object.keys(permissionDetails).length > 0 ? { permissionDetails, } : {}),
-        environment: doctorEnvironment(projectKey),
+        environment: doctorEnvironment(projectKey, versionInfo),
     };
     if (flags["fast"] !== true && probeProjectKey) {
         try {
@@ -255,6 +259,7 @@ export async function runDoctor(flags) {
             : "Missing Dataiku URL and/or API key. Set DATAIKU_URL/DATAIKU_API_KEY or pass --url/--api-key.",
     });
     let accessibleProjects;
+    let environmentVersion;
     if (credentialsOk) {
         const requestTimeoutMs = num(flags["request-timeout"], "--request-timeout");
         const retryMaxAttempts = num(flags["retries"], "--retries");
@@ -269,14 +274,40 @@ export async function runDoctor(flags) {
             caCertPath,
         });
         try {
-            const projects = await client.projects.list();
-            accessibleProjects = projects;
-            checks.push({
-                name: "connectivity",
-                ok: true,
-                message: "Connected to DSS and listed accessible projects.",
-                details: { projectCount: projects.length, },
-            });
+            const projects = await client.getWithMetadata("/public/api/projects/");
+            // Documented headers on the public project-list call populate the
+            // optional environment fields; absent headers stay absent. Header
+            // provenance is independent of the body being well-formed.
+            environmentVersion = {
+                dssVersion: projects.meta.dssVersion,
+                dssApiVersion: projects.meta.dssApiVersion,
+                instanceTime: projects.meta.date,
+            };
+            // A reachable endpoint that answers with something other than a
+            // project list is not working connectivity: the body never becomes
+            // capability input, so probes cannot iterate a non-array.
+            const parsed = safeParseSchema(ProjectSummaryArraySchema, projects.data);
+            if (parsed.success) {
+                accessibleProjects = parsed.data;
+                checks.push({
+                    name: "connectivity",
+                    ok: true,
+                    message: "Connected to DSS and listed accessible projects.",
+                    details: { projectCount: parsed.data.length, },
+                });
+            }
+            else {
+                checks.push({
+                    name: "connectivity",
+                    ok: false,
+                    message: "Connected to DSS but the project list response was not a project list.",
+                    details: {
+                        reason: "invalid_project_list",
+                        errorCount: parsed.errors.length,
+                        errors: parsed.errors.slice(0, 5),
+                    },
+                });
+            }
         }
         catch (error) {
             checks.push({
@@ -323,8 +354,8 @@ export async function runDoctor(flags) {
             tlsRejectUnauthorized,
             caCertPath,
         });
-        result.environment = doctorEnvironment(projectKey);
-        Object.assign(result, await doctorCapabilities(client, projectKey, accessibleProjects, flags));
+        result.environment = doctorEnvironment(projectKey, environmentVersion);
+        Object.assign(result, await doctorCapabilities(client, projectKey, accessibleProjects, flags, environmentVersion));
     }
     return { result, exitCode: result.ok ? 0 : 2, };
 }

package/dist/src/cli/flags.js

@@ -96,11 +96,13 @@ export const VALUE_FLAGS = new Set([
     "env-version",
     "expect-hash",
     "expect-project-incarnation",
+    "expected",
     "expect-version",
     "data-file",
     "database",
     "dataset",
     "file",
+    "file-name",
     "file-type",
     "env",
     "install-core-packages",

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

@@ -87,12 +87,22 @@ export declare function futureTargetIdentity(result: unknown): {
     projectKey: string;
     field: "targetProjectKey" | "projectKey";
 } | null;
+interface TargetAbsenceContext {
+    appId: string;
+    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.
  */
-export declare function requireAbsentProjectTarget(client: DataikuClient, targetProjectKey: string, targetFlag: "--to" | "targetProjectKey"): Promise<void>;
+export declare function requireAbsentProjectTarget(client: DataikuClient, targetProjectKey: string, targetFlag: "--to" | "targetProjectKey", context: TargetAbsenceContext): Promise<void>;
+/**
+ * Run every read-only gate used by successor creation without changing the
+ * template version or issuing the creation POST. Its manifest hash is suitable
+ * for the subsequent set-manifest-version --expect-hash guard.
+ */
+export declare function preflightSuccessorInstance(client: DataikuClient, request: SuccessorInstanceRequest, usage: string): Promise<Record<string, unknown>>;
 /**
  * Create a new app instance from the current template version alongside an
  * existing instance. Classic app instances have no public upgrade endpoint, so
@@ -100,7 +110,9 @@ export declare function requireAbsentProjectTarget(client: DataikuClient, target
  * and deliberately retired.
  *
  * After the creation POST this function never throws. A post-POST failure
- * returns a failed-wait result carrying the target project key, so the CLI still
- * exits 4 and the cleanup ledger still records an addressable successor.
+ * returns a failed-wait result. Only a DSS future ID or verified project
+ * incarnation can authorize cleanup; an ambiguous POST with neither stays
+ * indeterminate and produces no cleanup entry.
  */
 export declare function createSuccessorInstance(client: DataikuClient, request: SuccessorInstanceRequest, usage: string): Promise<Record<string, unknown>>;
+export {};