dataiku-sdk 1.0.0 → 2.0.0

package/dist/src/cli/commands/dataset.js

@@ -1,10 +1,102 @@
 import { buildDatasetCloneSettings, } from "../../resources/datasets.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
-import { jsonInput, num, schemaColumnsInput, } from "../coerce.js";
+import { compareStrings, stableHash, } from "../../utils/stable-hash.js";
+import { jsonInput, num, schemaColumnsInput, unknownJsonInput, } from "../coerce.js";
 import { datasetSourceSummary, } from "../helpers/dataset.js";
 import { moveCreatedItemsToZone, resolveFlowZoneIdFromFlags, } from "../helpers/flow-zone.js";
 import { enqueueCliWarning, readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
+const MAX_SCHEMA_DIFFERENCES = 50;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function appendSchemaPath(parent, key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+        ? (parent ? `${parent}.${key}` : key)
+        : `${parent}[${JSON.stringify(key)}]`;
+}
+function collectSchemaDifferences(expected, actual, path, acc) {
+    // Hash equality is the deterministic equivalence test: structurally equal
+    // subtrees (any key order) match exactly and are never descended into.
+    if (stableHash(expected) === stableHash(actual))
+        return;
+    if (isPlainObject(expected) && isPlainObject(actual)) {
+        const keys = [...new Set([...Object.keys(expected), ...Object.keys(actual),]),].sort(compareStrings);
+        for (const key of keys) {
+            const nextPath = appendSchemaPath(path, key);
+            const hasExpected = key in expected;
+            const hasActual = key in actual;
+            if (hasExpected && hasActual) {
+                collectSchemaDifferences(expected[key], actual[key], nextPath, acc);
+                continue;
+            }
+            acc.total += 1;
+            if (acc.items.length < MAX_SCHEMA_DIFFERENCES) {
+                acc.items.push({
+                    path: nextPath,
+                    kind: hasActual ? "added" : "removed",
+                    ...(hasActual
+                        ? { actualHash: stableHash(actual[key]), }
+                        : { expectedHash: stableHash(expected[key]), }),
+                });
+            }
+        }
+        return;
+    }
+    if (Array.isArray(expected) && Array.isArray(actual)) {
+        const shared = Math.min(expected.length, actual.length);
+        for (let i = 0; i < shared; i++) {
+            collectSchemaDifferences(expected[i], actual[i], `${path}[${i}]`, acc);
+        }
+        for (let i = shared; i < expected.length; i++) {
+            acc.total += 1;
+            if (acc.items.length < MAX_SCHEMA_DIFFERENCES) {
+                acc.items.push({
+                    path: `${path}[${i}]`,
+                    kind: "removed",
+                    expectedHash: stableHash(expected[i]),
+                });
+            }
+        }
+        for (let i = shared; i < actual.length; i++) {
+            acc.total += 1;
+            if (acc.items.length < MAX_SCHEMA_DIFFERENCES) {
+                acc.items.push({
+                    path: `${path}[${i}]`,
+                    kind: "added",
+                    actualHash: stableHash(actual[i]),
+                });
+            }
+        }
+        return;
+    }
+    acc.total += 1;
+    if (acc.items.length < MAX_SCHEMA_DIFFERENCES) {
+        acc.items.push({
+            path: path || "$",
+            kind: "changed",
+            expectedHash: stableHash(expected),
+            actualHash: stableHash(actual),
+        });
+    }
+}
+/**
+ * Compare two schema values deterministically — object key order never matters
+ * — and report each structural difference as a concise per-path entry carrying
+ * subtree hashes instead of subtree values.
+ */
+export function compareDatasetSchemas(expected, actual) {
+    const acc = { items: [], total: 0, };
+    collectSchemaDifferences(expected, actual, "", acc);
+    return {
+        equal: acc.items.length === 0,
+        expectedHash: stableHash(expected),
+        actualHash: stableHash(actual),
+        differences: acc.items,
+        totalDifferences: acc.total,
+        differencesTruncated: acc.items.length < acc.total,
+    };
+}
 export const datasetCommands = {
     list: {
         handler: (c, _a, f) => c.datasets.list(f["project-key"]),
@@ -69,6 +161,34 @@ export const datasetCommands = {
         description: "Show backing connection, catalog/schema/table, path, and format for a dataset.",
         examples: ["dss dataset source orders",],
     },
+    files: {
+        handler: (c, a, f) => {
+            requireArgs(a, 1, "dss dataset files <name> [--project-key KEY]");
+            return c.datasets.listUploadedFiles(a[0], f["project-key"]);
+        },
+        usage: "dss dataset files <name> [--project-key KEY]",
+        description: "List files stored by an UploadedFiles dataset.",
+        examples: ["dss dataset files uploaded_input",],
+    },
+    "upload-file": {
+        handler: (c, a, f) => {
+            const usage = "dss dataset upload-file <name> <localPath> --file-name NAME [--project-key KEY]";
+            requireArgs(a, 2, usage);
+            const fileName = f["file-name"];
+            if (!fileName || fileName.trim() === "") {
+                throw new UsageError(`--file-name is required. Usage: ${usage}`);
+            }
+            return c.datasets.uploadDatasetFile(a[0], a[1], {
+                fileName,
+                projectKey: f["project-key"],
+            });
+        },
+        usage: "dss dataset upload-file <name> <localPath> --file-name NAME [--project-key KEY]",
+        description: "Add one new file to an UploadedFiles dataset and verify the stored byte length.",
+        examples: [
+            "dss dataset upload-file uploaded_input ./input.csv --file-name input.csv",
+        ],
+    },
     "refresh-schema": {
         handler: async (c, a, f) => {
             const usage = "dss dataset refresh-schema <name> [--data JSON | --data-file PATH | --stdin] [--dry-run] [--project-key KEY]";
@@ -105,18 +225,79 @@ export const datasetCommands = {
         examples: ["dss dataset validate-build orders",],
     },
     preview: {
-        handler: (c, a, f) => {
-            requireArgs(a, 1, "dss dataset preview <name>");
-            return c.datasets.preview(a[0], {
-                maxRows: num(f["max-rows"], "--max-rows"),
+        handler: async (c, a, f) => {
+            const previewUsage = "dss dataset preview <name> [--max-rows N] [--rows N] [--project-key KEY] [--timeout MS]";
+            requireArgs(a, 1, previewUsage);
+            const maxRows = num(f["max-rows"], "--max-rows");
+            if (maxRows !== undefined && (!Number.isSafeInteger(maxRows) || maxRows <= 0 || maxRows > 500)) {
+                throw new UsageError(`--max-rows must be a positive integer no greater than 500 (got "${String(f["max-rows"])}"). `
+                    + `Usage: ${previewUsage}`, "validation_failed");
+            }
+            const result = await c.datasets.preview(a[0], {
+                maxRows,
                 projectKey: f["project-key"],
                 timeoutMs: num(f["timeout"], "--timeout"),
             });
+            if (result.truncated) {
+                enqueueCliWarning({
+                    code: "dataset_preview_truncated",
+                    message: `Preview of '${a[0]}' stopped at the ${result.limit}-row cap; the dataset has more rows. ${result.limit >= 500
+                        ? "The preview cap of 500 rows is the public maximum; use `dss dataset download` for more rows."
+                        : "Re-run with --max-rows N (up to 500) for more rows."}`,
+                    dataset: a[0],
+                    rows: result.rowCount,
+                    limit: result.limit,
+                });
+            }
+            return result;
         },
         usage: "dss dataset preview <name> [--max-rows N] [--rows N] [--project-key KEY] [--timeout MS]",
-        description: "Preview dataset rows (--rows is an alias for --max-rows).",
+        description: "Preview dataset rows (--rows is an alias for --max-rows). Returns { columns, rows, rowCount, truncated, limit }; when the dataset has more rows than the cap, truncated is true and a dataset_preview_truncated warning is written to stderr.",
         examples: ["dss dataset preview orders", "dss dataset preview orders --rows 5",],
     },
+    "assert-count": {
+        handler: async (c, a, f) => {
+            const assertUsage = "dss dataset assert-count <dataset> --expected N [--project-key KEY]";
+            requireArgs(a, 1, assertUsage);
+            const expected = num(f["expected"], "--expected");
+            if (expected === undefined || !Number.isSafeInteger(expected) || expected < 0) {
+                throw new UsageError(`--expected must be a non-negative integer (got "${String(f["expected"])}"). `
+                    + `Usage: ${assertUsage}`, "validation_failed");
+            }
+            const result = await c.datasets.assertRowCount(a[0], expected, f["project-key"]);
+            return { ...result, dataset: a[0], };
+        },
+        usage: "dss dataset assert-count <dataset> --expected N [--project-key KEY]",
+        description: "Stream the dataset and assert it holds exactly --expected rows, probing at most N+1 rows. Returns { satisfied, expected, count, exact }; a mismatch exits 4 with assertion_failed.",
+        examples: ["dss dataset assert-count orders --expected 1000",],
+    },
+    "assert-schema": {
+        handler: async (c, a, f) => {
+            const assertUsage = "dss dataset assert-schema <dataset> (--data JSON | --data-file PATH | --stdin) [--project-key KEY]";
+            requireArgs(a, 1, assertUsage);
+            const expected = unknownJsonInput(f);
+            if (expected === undefined) {
+                throw new UsageError(`--data, --data-file, or --stdin is required. Usage: ${assertUsage}`);
+            }
+            const actual = await c.datasets.getSchemaObject(a[0], f["project-key"]);
+            const comparison = compareDatasetSchemas(expected, actual);
+            return {
+                satisfied: comparison.equal,
+                dataset: a[0],
+                expectedHash: comparison.expectedHash,
+                actualHash: comparison.actualHash,
+                totalDifferences: comparison.totalDifferences,
+                ...(comparison.differencesTruncated ? { differencesTruncated: true, } : {}),
+                differences: comparison.differences,
+            };
+        },
+        usage: "dss dataset assert-schema <dataset> (--data JSON | --data-file PATH | --stdin) [--project-key KEY]",
+        description: "Assert the dataset's full schema equals the expected schema object; reports concise per-path differences with sha256 subtree hashes. A mismatch exits 4 with assertion_failed.",
+        examples: [
+            `dss dataset assert-schema orders --data-file expected-schema.json`,
+            `dss dataset assert-schema orders --data '{"columns":[]}'`,
+        ],
+    },
     metadata: {
         handler: (c, a, f) => {
             requireArgs(a, 1, "dss dataset metadata <name>");

package/dist/src/cli/commands/job.js

@@ -33,6 +33,19 @@ function firstNumberPath(value, paths) {
     }
     return undefined;
 }
+function aggregateJobWaitResults(jobs, until) {
+    if (jobs.length === 1)
+        return jobs[0];
+    const failed = jobs.find((job) => !job.success);
+    return {
+        elapsedMs: jobs.reduce((maximum, job) => Math.max(maximum, job.elapsedMs), 0),
+        jobs,
+        pollCount: jobs.reduce((total, job) => total + job.pollCount, 0),
+        state: failed?.state ?? "DONE",
+        success: failed === undefined,
+        until,
+    };
+}
 function jobSummaryId(job, fallback) {
     return stringPath(job, ["baseStatus", "def", "id",])
         ?? stringPath(job, ["def", "id",])
@@ -357,7 +370,7 @@ export const jobCommands = {
                 projectKey: f["project-key"],
             };
             const jobs = await Promise.all(a.map((jobId) => c.jobs.wait(jobId, options)));
-            return a.length === 1 ? jobs[0] : { jobs, until: f["until"] ?? "all-done", };
+            return aggregateJobWaitResults(jobs, String(f["until"] ?? "all-done"));
         },
         usage: "dss job monitor <id...> [--summary] [--include-logs] [--log-filter stdout|stderr|user|errors] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--until all-done] [--project-key KEY]",
         description: "Monitor one or more existing jobs and summarize progress counters from logs.",
@@ -376,7 +389,7 @@ export const jobCommands = {
                 projectKey: f["project-key"],
             };
             const jobs = await Promise.all(a.map((jobId) => c.jobs.wait(jobId, options)));
-            return a.length === 1 ? jobs[0] : { jobs, until: f["until"] ?? "all-done", };
+            return aggregateJobWaitResults(jobs, String(f["until"] ?? "all-done"));
         },
         usage: "dss job watch <id...> [--include-logs] [--log-filter stdout|stderr|user|errors] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--until all-done] [--project-key KEY]",
         description: "Watch one or more existing jobs with progress extraction enabled.",

package/dist/src/cli/commands/project-library.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, } from "node:fs";
+import * as fs from "node:fs";
 import { readStdinText, } from "../coerce.js";
 import { encodedProjectEndpoint, planResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
@@ -68,8 +68,8 @@ export const projectLibraryCommands = {
             if (!out)
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
             const bytes = await c.projectLibrary.getFileBytes(a[0], f["project-key"]);
-            writeFileSync(out, bytes);
-            return { path: out, bytes: bytes.length, };
+            const written = await Bun.write(out, bytes, { createPath: false, });
+            return { path: out, bytes: written, };
         },
         usage: "dss project-library get-bytes <path> --output PATH [--project-key KEY]",
         description: "Download a project library file's raw bytes to a local file.",
@@ -126,7 +126,7 @@ export const projectLibraryCommands = {
             const content = typeof f["content"] === "string"
                 ? f["content"]
                 : typeof f["file"] === "string"
-                    ? readFileSync(f["file"], "utf-8")
+                    ? fs.readFileSync(f["file"], "utf-8")
                     : await readStdinText();
             await c.projectLibrary.addOrUpdateFile(a[0], content, pk);
             return { updated: a[0], };

package/dist/src/cli/commands/project.js

@@ -1,6 +1,16 @@
+import { ClientValidationError, DataikuError, } from "../../errors.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
-import { jsonInput, num, requiredJsonInput, } from "../coerce.js";
+import { inspectProjectArchive, } from "../../utils/project-archive.js";
+import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
+import { jsonInput, num, requiredJsonInput, requiredStringFlag, } from "../coerce.js";
+import { CommandResultFailure, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
+const INSPECT_ARCHIVE_USAGE = "dss project inspect-archive <file>";
+/** Local, DSS-free archive inspection shared by the local handler and the command handler. */
+function inspectArchiveCommand(args) {
+    requireArgs(args, 1, INSPECT_ARCHIVE_USAGE);
+    return inspectProjectArchive(args[0]);
+}
 export const projectCommands = {
     list: {
         handler: (c) => c.projects.list(),
@@ -56,12 +66,75 @@ export const projectCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss project delete <projectKey> [--drop-data]");
-            await c.projects.deleteProject(a[0], f["drop-data"] === true);
-            return { deleted: a[0], };
+            const usage = "dss project delete <projectKey> [--drop-data] [--if-exists] [--dry-run] [--expect-project-incarnation HASH]";
+            requireArgs(a, 1, usage);
+            const projectKey = a[0];
+            const expectedIncarnation = f["expect-project-incarnation"] === undefined
+                ? undefined
+                : requiredStringFlag(f, "expect-project-incarnation", usage);
+            if (expectedIncarnation !== undefined
+                && !/^[0-9a-f]{64}$/.test(expectedIncarnation)) {
+                throw new UsageError("--expect-project-incarnation must be a 64-character lowercase SHA-256 hash.", "validation_failed");
+            }
+            const guarded = f["if-exists"] === true
+                || f["dry-run"] === true
+                || expectedIncarnation !== undefined;
+            if (!guarded) {
+                // Purely user-requested delete without any guard flag: keep the
+                // historical direct DELETE, with no preflight probe.
+                await c.projects.deleteProject(projectKey, f["drop-data"] === true);
+                return { deleted: projectKey, };
+            }
+            // Guarded path: existence and identity must be verified before any
+            // DELETE. A missing creationTag or an incarnation mismatch refuses
+            // before the DELETE under possible project-key reuse.
+            let currentIncarnation;
+            try {
+                const details = await c.projects.get(projectKey);
+                if (expectedIncarnation !== undefined) {
+                    currentIncarnation = projectIncarnationHash(projectKey, details);
+                    if (currentIncarnation === undefined) {
+                        throw new ClientValidationError(`DSS did not return creationTag identity for project ${projectKey}. Refusing to delete without project-incarnation verification.`, "validation_failed", "Project-key reuse cannot be excluded. Refusing the DELETE; re-read the project and retry with a hash captured from that incarnation.", { projectKey, });
+                    }
+                    if (currentIncarnation !== expectedIncarnation) {
+                        throw new ClientValidationError(`Project ${projectKey} is not the same project incarnation recorded for this operation. Refusing to delete after project-key reuse.`, "validation_failed", "Re-read the current project and retry only with an artifact captured from that incarnation.", {
+                            projectKey,
+                            expectedProjectIncarnationHash: expectedIncarnation,
+                            currentProjectIncarnationHash: currentIncarnation,
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                if (error instanceof DataikuError && error.status === 404) {
+                    // Already absent: converge only when the caller asked for it.
+                    if (f["if-exists"] !== true)
+                        throw error;
+                    return { deleted: false, alreadyAbsent: true, projectKey, };
+                }
+                throw error;
+            }
+            if (f["dry-run"] === true) {
+                return {
+                    deleted: false,
+                    dryRun: true,
+                    projectKey,
+                    ...(currentIncarnation !== undefined
+                        ? { projectIncarnationHash: currentIncarnation, }
+                        : {}),
+                };
+            }
+            await c.projects.deleteProject(projectKey, f["drop-data"] === true);
+            return {
+                deleted: true,
+                projectKey,
+                ...(currentIncarnation !== undefined
+                    ? { projectIncarnationHash: currentIncarnation, }
+                    : {}),
+            };
         },
-        usage: "dss project delete <projectKey> [--drop-data]",
-        description: "Delete a project (destructive). --drop-data also clears managed datasets.",
+        usage: "dss project delete <projectKey> [--drop-data] [--if-exists] [--dry-run] [--expect-project-incarnation HASH]",
+        description: "Delete a project (destructive). --drop-data also clears managed datasets; --if-exists treats an absent project as already deleted; --dry-run verifies without deleting; --expect-project-incarnation HASH refuses deletion unless the project still matches the recorded incarnation.",
         examples: ["dss project delete MY_PROJ",],
     },
     duplicate: {
@@ -87,13 +160,44 @@ export const projectCommands = {
         examples: ["dss project export MY_PROJ --output ./my_proj.zip",],
     },
     import: {
-        handler: async (c, a) => {
-            requireArgs(a, 1, "dss project import <filePath>");
-            return c.projects.importProjectFromArchive(a[0]);
+        handler: async (c, a, f) => {
+            const usage = "dss project import <filePath> [--target-project-key KEY] [--data JSON|--data-file PATH|--stdin]";
+            requireArgs(a, 1, usage);
+            const settings = jsonInput(f) ?? {};
+            const rawTarget = f["target-project-key"];
+            const targetProjectKey = rawTarget?.trim();
+            if (rawTarget !== undefined && targetProjectKey === "") {
+                throw new UsageError(`--target-project-key must not be empty. Usage: ${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: ${usage}`);
+            }
+            if (targetProjectKey !== undefined
+                && settingsTarget !== undefined
+                && targetProjectKey !== settingsTarget.trim()) {
+                throw new UsageError(`--target-project-key conflicts with targetProjectKey in import settings. Usage: ${usage}`);
+            }
+            const result = await c.projects.importProjectFromArchive(a[0], targetProjectKey === undefined ? settings : { ...settings, targetProjectKey, });
+            if (result.success !== true) {
+                throw new CommandResultFailure({ ...result, resource: "project", action: "import", stage: "process", }, 2);
+            }
+            return result;
         },
-        usage: "dss project import <filePath>",
-        description: "Upload a project archive to prepare an import (returns a temporary import id).",
-        examples: ["dss project import ./my_proj.zip",],
+        usage: "dss project import <filePath> [--target-project-key KEY] [--data JSON|--data-file PATH|--stdin]",
+        description: "Upload and process a project archive, optionally overriding its project key. The archive is validated locally before upload; verified success reports the used project key, explicit request/actual remapping, and the landed incarnation hash.",
+        examples: [
+            "dss project import ./my_proj.zip",
+            "dss project import ./my_proj.zip --target-project-key MY_PROJ",
+        ],
+    },
+    "inspect-archive": {
+        handler: async (_c, a) => inspectArchiveCommand(a),
+        localHandler: inspectArchiveCommand,
+        usage: INSPECT_ARCHIVE_USAGE,
+        description: "Read-only local inspection of a project export archive: member names, sizes, manifest validity, archive issues, and the source project key. Never contacts DSS.",
+        examples: ["dss project inspect-archive ./my_proj.zip",],
     },
     "permissions-get": {
         handler: (c, _a, f) => c.projects.getPermissions(f["project-key"]),

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

@@ -101,6 +101,7 @@ export declare function commandPlanShape(resource: string, action: string, args:
     payload?: unknown;
     localWrites?: unknown;
     wait?: unknown;
+    requests?: unknown;
 };
 export declare function buildMutationPlan(resource: string, action: string, meta: CommandMeta, args: string[], flags: Record<string, string | boolean>): Record<string, unknown>;
 /**