dataiku-sdk 1.0.0 → 1.1.0

package/README.md

@@ -20,6 +20,7 @@ npm install --global dataiku-sdk
 
 Bun is the primary development runtime and package manager. Examples below assume an installed `dss` binary. From a checkout, use `bun --no-env-file src/cli.ts ...` or the cross-runtime `bun --no-env-file ./bin/dss.js ...` launcher. Node users can invoke the same launcher as `node ./bin/dss.js ...`; if `dist/` is absent, it delegates to Bun. From another working directory, pass the checkout's absolute `bin/dss.js` path to Bun or Node.
 `--no-env-file` disables Bun's automatic preloading only; the CLI still applies its documented `.env` handling unless `DATAIKU_DISABLE_ENV=1` is set.
+`dss version` reports whether the running code came from `source` or `dist`, the Node/Bun runtime, the packaged build revision when available, and `staleBuild` when that revision differs from the checkout. Release builds generate `dist/build-metadata.json`; source snapshots without Git metadata still build but report no build revision.
 
 ## CLI contract
 
@@ -119,7 +120,14 @@ The command saves credentials and returns `{ "saved": true, "path": "..." }`.
 dss version
 dss doctor --fast
 dss project list
+dss project inspect-archive ./project.zip
+dss project import ./project.zip --target-project-key IMPORTED_PROJECT --record-cleanup cleanup.jsonl
 dss dataset list --project-key MYPROJ
+dss dataset files uploaded_input --project-key MYPROJ
+dss dataset upload-file uploaded_input ./new.csv --file-name new.csv --project-key MYPROJ
+dss dataset assert-count jmp_doe_ready --expected 12 --project-key MYPROJ
+dss dataset assert-schema jmp_doe_ready --data-file expected-schema.json --project-key MYPROJ
+dss data-quality assert-results jmp_doe_ready --project-key MYPROJ
 dss recipe get-payload compute_orders --project-key MYPROJ
 dss recipe get-payload compute_orders --output code.py --project-key MYPROJ
 dss install-skill --dry-run
@@ -136,6 +144,28 @@ dss app permissions-restore --project-key MYAPP_INSTANCE --file permissions.json
 dss cleanup --file cleanup.jsonl
 dss cleanup --file cleanup.jsonl --apply
 ```
+`project import` performs both public API stages: archive upload, then import processing. It
+first validates ZIP integrity, safe unique member paths, the export manifest, and provable Flow
+references locally. Verified success reports DSS's actual project key, explicit remapping, and a
+`creationTag` incarnation hash; `--record-cleanup` records an incarnation-bound guarded delete.
+It exits nonzero when DSS returns `success:false` even if both HTTP requests succeeded. A timeout,
+5xx, malformed response, missing used key, or failed post-import identity read is
+`ambiguous_outcome` and retains the temporary import ID for inspection before retry.
+
+`dataset upload-file` only adds a filename that is not already present and verifies its byte
+length afterward. DSS 14.7 exposes no public UploadedFiles delete or replacement endpoint;
+the command refuses an existing filename before POST instead of triggering DSS's opaque 500.
+For replacement, import a successor project archive containing the desired upload.
+
+`dataset preview` returns `truncated` and `limit`; it probes one row past the requested cap instead
+of presenting a capped sample as an exact count. `dataset assert-count`, `dataset assert-schema`,
+and `data-quality assert-results` return `satisfied` and exit `4`/`assertion_failed` on a failed
+postcondition, so they can be used as `batch` steps. Multi-job `job monitor` and `job watch`
+aggregate child failures and also exit `4` when any watched job fails.
+
+`doctor` reads the documented `DSS-Version` and `DSS-API-Version` response headers plus the HTTP
+`Date` header from the public project-list call. Feature support remains behavioral: the CLI does
+not call an undocumented feature endpoint or infer licensed capabilities from a version string.
 
 ### Application release safety
 
@@ -214,7 +244,9 @@ conditional DELETE. Cleanup rechecks type and `creationTag` immediately before d
 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.
+without a valid incarnation binding. Project-import cleanup uses the same rule: the ledger binds
+the actual imported key and verified `creationTag` hash, and `project delete
+--expect-project-incarnation` refuses a reused or unverifiable key before DELETE.
 
 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

package/bin/dss.js

@@ -56,9 +56,28 @@ if (hasFlag(["--insecure", "--skip-tls-verify",],)) {
 ) {
 	env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
 }
-
 const runningOnBun = Boolean(process.versions.bun,);
 const usesSourceCli = cliPath === sourceCliPath;
+
+// Published dist carries dist/build-metadata.json with the revision it was
+// built from. Forward it to the CLI so provenance can report dist source and
+// its build revision; only a full lowercase hexadecimal revision is accepted,
+// so an inherited or corrupt variable never stands in for packaged metadata.
+const distMetadataPath = path.resolve(here, "../dist/build-metadata.json",);
+if (!usesSourceCli) {
+	env.DSS_LOAD_SOURCE = "dist";
+	delete env.DSS_BUILD_REVISION;
+	try {
+		const metadata = JSON.parse(fs.readFileSync(distMetadataPath, "utf-8",),);
+		const revision = metadata.buildRevision;
+		if (typeof revision === "string" && /^[0-9a-f]{40}$/.test(revision,)) {
+			env.DSS_BUILD_REVISION = revision;
+		}
+	} catch {
+		// Dist without build metadata: provenance still reports dist source.
+	}
+}
+
 const runtimeBin = runningOnBun ? process.execPath : usesSourceCli ? "bun" : process.execPath;
 const runtimeArgs = runningOnBun || usesSourceCli ? ["--no-env-file",] : ["--use-system-ca",];
 const result = spawnSync(

package/dist/build-metadata.json

@@ -0,0 +1 @@
+{"format":1,"buildRevision":"70487e2275a70acce6862f126a89b1bc852ebb11"}

package/dist/src/cli/commands/data-quality.js

@@ -2,6 +2,18 @@ import { deepMerge, } from "../../utils/deep-merge.js";
 import { num, parseBooleanOption, requiredJsonInput, } from "../coerce.js";
 import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
+/**
+ * A data quality result counts as passing only when it actually carries a
+ * verdict and every verdict it carries reports OK. A result with no outcome
+ * and no status has proven nothing, and a result whose fields disagree
+ * (outcome ERROR alongside status OK) is a failure — never a pass.
+ */
+function resultReportsOk(result) {
+    const verdicts = [result.outcome, result.status,]
+        .filter((value) => typeof value === "string" && value.trim().length > 0)
+        .map((value) => value.trim().toUpperCase());
+    return verdicts.length > 0 && verdicts.every((value) => value === "OK");
+}
 export const dataQualityCommands = {
     rules: {
         handler: (c, a, f) => {
@@ -160,6 +172,36 @@ export const dataQualityCommands = {
         description: "Get latest data quality rule results for a dataset.",
         examples: ["dss data-quality last-results orders",],
     },
+    "assert-results": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss data-quality assert-results <dataset>");
+            const ruleId = f["rule-id"];
+            const pk = f["project-key"];
+            const results = await c.dataQuality.lastResults(a[0], { ruleId, projectKey: pk, });
+            const selected = results.filter((result) => ruleId === undefined || result.id === ruleId || result.ruleId === ruleId);
+            const failed = selected
+                .filter((result) => !resultReportsOk(result))
+                .map((result) => ({
+                ruleId: result.id ?? result.ruleId ?? result.name ?? null,
+                outcome: result.outcome ?? null,
+                status: result.status ?? null,
+            }));
+            return {
+                satisfied: selected.length > 0 && failed.length === 0,
+                dataset: a[0],
+                ...(ruleId !== undefined ? { ruleId, } : {}),
+                checked: selected.length,
+                failed,
+                ...(selected.length === 0 ? { reason: "no_results", } : {}),
+            };
+        },
+        usage: "dss data-quality assert-results <dataset> [--rule-id ID] [--project-key KEY]",
+        description: "Assert the latest data quality results: at least one selected rule must exist and every selected result must report OK. Returns { satisfied, checked, failed } with failed rule ids/outcomes only; a failed assertion exits 4 with assertion_failed.",
+        examples: [
+            "dss data-quality assert-results orders",
+            "dss data-quality assert-results orders --rule-id RULE_ID",
+        ],
+    },
     history: {
         handler: (c, a, f) => {
             requireArgs(a, 1, "dss data-quality history <dataset>");

package/dist/src/cli/commands/dataset.d.ts

@@ -1,2 +1,25 @@
 import type { CommandMeta } from "../types.js";
+export interface DatasetSchemaDifference {
+    /** Path from the schema root in dot/bracket notation, e.g. `columns[2].type`. */
+    path: string;
+    kind: "added" | "removed" | "changed";
+    /** SHA-256 of the deterministic JSON rendering of the expected subtree. */
+    expectedHash?: string;
+    /** SHA-256 of the deterministic JSON rendering of the actual subtree. */
+    actualHash?: string;
+}
+export interface DatasetSchemaComparison {
+    equal: boolean;
+    expectedHash: string;
+    actualHash: string;
+    differences: DatasetSchemaDifference[];
+    totalDifferences: number;
+    differencesTruncated: boolean;
+}
+/**
+ * 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 declare function compareDatasetSchemas(expected: unknown, actual: unknown): DatasetSchemaComparison;
 export declare const datasetCommands: Record<string, CommandMeta>;

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.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>;
 /**