dataiku-sdk 0.12.7 → 1.1.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(),
@@ -29,8 +39,8 @@ export const projectCommands = {
     map: {
         handler: (c, _a, f) => c.projects.map({
             projectKey: f["project-key"],
-            maxNodes: num(f["max-nodes"]),
-            maxEdges: num(f["max-edges"]),
+            maxNodes: num(f["max-nodes"], "--max-nodes"),
+            maxEdges: num(f["max-edges"], "--max-edges"),
             includeRaw: f["include-raw"] === true,
         }),
         usage: "dss project map [--max-nodes N] [--max-edges N] [--include-raw] [--project-key KEY]",
@@ -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/commands/recipe.js

@@ -79,9 +79,9 @@ export const recipeCommands = {
                 logFilter: jobLogFilterFromFlag(f["log-filter"]),
                 maxLogLines: maxLogLinesFromFlags(f),
                 partition: f["partition"],
-                pollIntervalMs: num(f["poll-interval"]),
+                pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
                 projectKey: pk,
-                timeoutMs: num(f["timeout"]),
+                timeoutMs: num(f["timeout"], "--timeout"),
                 summary: f["summary"] === true,
                 wait,
             };
@@ -164,7 +164,7 @@ export const recipeCommands = {
         handler: async (c, _a, f) => {
             const type = f["type"];
             if (!type) {
-                throw new UsageError("--type is required. Usage: dss recipe create --type TYPE --input DS (--output DS | --output-folder FOLDER_ID)");
+                throw new UsageError("--type is required. Usage: dss recipe create --type TYPE [--input DS] (--output DS | --output-folder FOLDER_ID)");
             }
             const outputDataset = f["output"];
             const outputFolder = f["output-folder"];
@@ -172,7 +172,7 @@ export const recipeCommands = {
                 throw new UsageError("--output and --output-folder are mutually exclusive.");
             }
             if (!outputDataset && !outputFolder) {
-                throw new UsageError("--output or --output-folder is required. Usage: dss recipe create --type TYPE --input DS (--output DS | --output-folder FOLDER_ID)");
+                throw new UsageError("--output or --output-folder is required. Usage: dss recipe create --type TYPE [--input DS] (--output DS | --output-folder FOLDER_ID)");
             }
             if (outputFolder && !f["output-connection"]) {
                 throw new UsageError("--output-connection is required when using --output-folder.");
@@ -197,10 +197,7 @@ export const recipeCommands = {
                 }
                 fuzzyDistance = normalized;
             }
-            const fuzzyThreshold = num(f["fuzzy-threshold"]);
-            if (typeof f["fuzzy-threshold"] === "string" && fuzzyThreshold === undefined) {
-                throw new UsageError("--fuzzy-threshold must be a finite number.", "validation_failed");
-            }
+            const fuzzyThreshold = num(f["fuzzy-threshold"], "--fuzzy-threshold");
             const payload = {
                 type,
                 name,
@@ -255,8 +252,8 @@ export const recipeCommands = {
                 },], pk);
             return { created: createdName, resource: "recipe", ...created, ...moved, };
         },
-        usage: "dss recipe create --type TYPE --input DS[,DS2] (--output DS | --output-folder FOLDER_ID) [--name NAME] [--output-connection CONN] [--zone ZONE|--zone-id ID] [--if-not-exists] [--dry-run] [--join-on COL|LEFT=RIGHT[,...]] [--join-type LEFT|INNER|RIGHT|FULL] [--fuzzy-on COL|LEFT=RIGHT[,...]] [--fuzzy-distance DAMERAU_LEVENSHTEIN|HAMMING|JACCARD|COSINE|EUCLIDEAN] [--fuzzy-threshold N] [--normalize] [--project-key KEY]",
-        description: "Create a recipe with one or more inputs and a dataset or managed-folder output.",
+        usage: "dss recipe create --type TYPE [--input DS[,DS2]] (--output DS | --output-folder FOLDER_ID) [--name NAME] [--output-connection CONN] [--zone ZONE|--zone-id ID] [--if-not-exists] [--dry-run] [--join-on COL|LEFT=RIGHT[,...]] [--join-type LEFT|INNER|RIGHT|FULL] [--fuzzy-on COL|LEFT=RIGHT[,...]] [--fuzzy-distance DAMERAU_LEVENSHTEIN|HAMMING|JACCARD|COSINE|EUCLIDEAN] [--fuzzy-threshold N] [--normalize] [--project-key KEY]",
+        description: "Create a recipe with optional inputs and a dataset or managed-folder output.",
         examples: [
             "dss recipe create --type python --input raw_orders,lookup --output orders_clean",
             "dss recipe create --type python --input orders --input customers --output orders_clean --zone Experiments",
@@ -485,23 +482,23 @@ export const recipeCommands = {
             }
             return payload;
         },
-        usage: "dss recipe get-payload <name> [--raw] [--output PATH] [--project-key KEY]",
-        description: "Print the recipe code payload as JSON; use --raw for raw bytes, not JSON.",
+        usage: "dss recipe get-payload <name> [--output PATH] [--project-key KEY]",
+        description: "Print the recipe code payload as a JSON string, or write it to a file with --output.",
         examples: [
-            "dss recipe get-payload compute_orders --raw",
+            "dss recipe get-payload compute_orders",
             "dss recipe get-payload compute_orders -o code.py",
         ],
     },
     cat: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss recipe cat <name> [--raw]");
+            requireArgs(a, 1, "dss recipe cat <name>");
             return c.recipes.getPayload(a[0], {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss recipe cat <name> [--raw] [--project-key KEY]",
-        description: "Print a recipe code payload as JSON; use --raw for raw bytes, not JSON.",
-        examples: ["dss recipe cat compute_orders --raw",],
+        usage: "dss recipe cat <name> [--project-key KEY]",
+        description: "Print the recipe code payload as a JSON string.",
+        examples: ["dss recipe cat compute_orders",],
     },
     "set-payload": {
         handler: async (c, a, f) => {

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

@@ -23,8 +23,8 @@ export const scenarioCommands = {
             requireArgs(a, 1, "dss scenario run <id>");
             const pk = f["project-key"];
             const options = {
-                pollIntervalMs: num(f["poll-interval"]),
-                timeoutMs: num(f["timeout"]),
+                pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
+                timeoutMs: num(f["timeout"], "--timeout"),
             };
             if (f["dry-run"] === true) {
                 return {
@@ -51,8 +51,8 @@ export const scenarioCommands = {
             requireArgs(a, 1, "dss scenario run-and-wait <id>");
             const pk = f["project-key"];
             const options = {
-                pollIntervalMs: num(f["poll-interval"]),
-                timeoutMs: num(f["timeout"]),
+                pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
+                timeoutMs: num(f["timeout"], "--timeout"),
             };
             if (f["dry-run"] === true) {
                 return {

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

@@ -39,7 +39,7 @@ export interface CommandStructuredExample {
 }
 export interface CommandUnsafeOutput {
     condition: string;
-    kind: "raw-stdout" | "local-file";
+    kind: "local-file";
     detail: string;
     safeAlternative?: string;
 }
@@ -80,18 +80,19 @@ export interface CommandRegistryEntry {
     cleanupHint?: string;
     agentContractVersion: number;
 }
-export declare const COMMANDS_USAGE = "dss commands run [--fields PATHS] [--json]";
+export declare const COMMANDS_USAGE = "dss commands run [--fields PATHS] [--output PATH]";
 export declare const AGENT_CONTRACT_COMMAND = "dss agent contract";
-export declare const AGENT_CONTRACT_USAGE = "dss agent contract [--fields PATHS] [--json]";
+export declare const AGENT_CONTRACT_USAGE = "dss agent contract [--fields PATHS]";
 export declare const CLEANUP_USAGE = "dss cleanup --file PATH [--dry-run|--apply] [--continue-on-error]";
 export declare function isAllowedCleanupAction(resource: string, action: string): boolean;
 export declare function buildCommandSchemas(resource: string, action: string, flags: CommandFlagMetadata[], requiredFlags: string[], requiredOneOf: CommandFlagChoice[], payloadSchema: CommandPayloadSchema | undefined, outputShape: CommandOutputShape, usage: string): CommandAgentSchemas;
-export declare function inferRequiresProject(resource: string, _action: string, usage: string): boolean;
+export declare function inferRequiresProject(resource: string, action: string, usage: string): boolean;
 export declare function inferInputContract(usage: string): CommandInputContract;
 export declare function supportsCleanupLedger(resource: string, action: string): boolean;
 export declare function inferCleanupHint(resource: string, action: string): string | undefined;
 export declare function buildCommandRegistry(): Record<string, Record<string, CommandRegistryEntry>>;
 export declare function agentContractJsonSchema(): Record<string, unknown>;
+export declare function commandActionSummary(registry: Record<string, Record<string, CommandRegistryEntry>>): Record<string, string[]>;
 export declare function buildAgentContract(): Record<string, unknown>;
 export declare function commandPlanShape(resource: string, action: string, args: string[], flags: Record<string, string | boolean>, entry: CommandRegistryEntry, projectKey: string | undefined): {
     endpoint?: string;
@@ -100,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>;
 /**