dataiku-sdk 0.12.1 → 0.12.3

package/README.md

@@ -2,7 +2,23 @@
 
 Agent-only TypeScript SDK and `dss` CLI for Dataiku DSS automation.
 
-Examples below assume the installed `dss` binary. From this checkout, use `./bin/dss ...` or `bun --no-env-file src/cli.ts ...` with the same arguments; from another working directory, call `/path/to/dataiku-sdk/bin/dss ...`.
+## Platform support
+
+The published `dss` CLI supports Linux, macOS, and Windows under Bun >= 1.3.14 or Node.js >= 22.15.0. The release gate runs Bun 1.3.14 with Node 24 on all three operating systems, plus a lightweight minimum-Node 22.15 package smoke on Linux. The runtime dependency is pure JavaScript, so the same package also runs on runtime-supported x64 and ARM64 systems.
+
+Run directly with Bun:
+
+```text
+bunx --bun dataiku-sdk version
+```
+
+Or install the npm binary:
+
+```text
+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.
 
 ## CLI contract
@@ -13,12 +29,12 @@ Examples below assume the installed `dss` binary. From this checkout, use `./bin
 - `--fields a,b,c` projects those fields from an object or array-of-objects result; dotted paths (`a.b.c`) drill into nested objects, and missing fields become `null`; string and scalar results pass through unchanged.
 - No prompts, help screens, tables, banners, or prose output are part of the contract.
 - Exit codes: `0` success, `1` usage/configuration error, `2` DSS/internal error, `3` transient DSS error, `4` completed command with failed long-running DSS work.
-- The exit code is the success signal: chain mutations with `&&` and never infer success from piped output that discards the exit code (e.g. `dss ... 2>&1 | helper; echo done` reports success even when the command failed).
+- The exit code is the success signal. For portable multi-step mutations, prefer `dss batch`; shell chaining and pipeline exit semantics differ across POSIX shells, Windows PowerShell, PowerShell 7, and Command Prompt.
 - `--raw` is only for recipe payload commands. Without `--output`, stdout is raw bytes; with `--output PATH`, stdout is the JSON string equal to `PATH` and the file contains the exact raw bytes.
 
 Discover the agent protocol and complete machine-readable command surface:
 
-```bash
+```text
 dss agent contract
 dss commands run
 ```
@@ -27,7 +43,7 @@ Agents should parse `agent contract` once for protocol/schema compatibility, the
 
 ## Agent skill installation
 
-```bash
+```text
 dss install-skill --list-agents
 dss install-skill --agent omp --target .
 dss install-skill --agent omp --target . --dry-run
@@ -48,22 +64,41 @@ Global installs write under the agent's home config path, for example OMP: `~/.o
 
 ## Credentials
 
-Use environment variables for ephemeral runs:
-For disposable agent tests, set `DSS_CONFIG_DIR` to a temporary directory so saved credentials never touch your real profile.
+Use environment variables for ephemeral runs. For disposable agent tests, set `DSS_CONFIG_DIR` to a temporary directory so saved credentials never touch your real profile.
 Credential precedence is flags first, then `DATAIKU_*` environment variables, then saved credentials in `DSS_CONFIG_DIR` or the platform config directory.
 Set `DATAIKU_DISABLE_ENV=1` when a test must ignore both `.env` files and `DATAIKU_*` environment variables.
 When `.env` loading is enabled, the CLI reads `.env` from the CLI build/root directory and from the command's current working directory; put test-specific `.env` files in the directory where you invoke `dss`.
 
-```bash
-DATAIKU_URL=https://dss.example.com \
-DATAIKU_API_KEY=your-api-key \
-DATAIKU_PROJECT_KEY=MYPROJ \
+POSIX shell:
+
+```sh
+export DATAIKU_URL=https://dss.example.com
+export DATAIKU_API_KEY=your-api-key
+export DATAIKU_PROJECT_KEY=MYPROJ
+dss project list
+```
+
+PowerShell:
+
+```powershell
+$env:DATAIKU_URL = "https://dss.example.com"
+$env:DATAIKU_API_KEY = "your-api-key"
+$env:DATAIKU_PROJECT_KEY = "MYPROJ"
+dss project list
+```
+
+Windows Command Prompt:
+
+```bat
+set "DATAIKU_URL=https://dss.example.com"
+set "DATAIKU_API_KEY=your-api-key"
+set "DATAIKU_PROJECT_KEY=MYPROJ"
 dss project list
 ```
 
 Persist credentials when needed:
 
-```bash
+```text
 dss auth login --url https://dss.example.com --api-key YOUR_KEY --project-key MYPROJ
 ```
 

package/bin/dss.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import { spawnSync, } from "node:child_process";
-import { existsSync, } from "node:fs";
-import { dirname, resolve, } from "node:path";
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { fileURLToPath, pathToFileURL, } from "node:url";
 
 const args = process.argv.slice(2,);
 const optionArgs = args.includes("--",) ? args.slice(0, args.indexOf("--",),) : args;
-const here = dirname(fileURLToPath(import.meta.url,),);
-const distCliPath = resolve(here, "../dist/src/cli.js",);
-const sourceCliPath = resolve(here, "../src/cli.ts",);
-const cliPath = existsSync(distCliPath,) ? distCliPath : sourceCliPath;
+const here = path.dirname(fileURLToPath(import.meta.url,),);
+const distCliPath = path.resolve(here, "../dist/src/cli.js",);
+const sourceCliPath = path.resolve(here, "../src/cli.ts",);
+const cliPath = fs.existsSync(distCliPath,) ? distCliPath : sourceCliPath;
 const cliUrl = pathToFileURL(cliPath,).href;
 
 function flagValue(names,) {
@@ -40,11 +40,6 @@ async function loadSavedTlsSettings() {
 	}
 }
 
-function supportsSystemCa(nodeBin,) {
-	const probe = spawnSync(nodeBin, ["--use-system-ca", "-e", "",], { stdio: "ignore", },);
-	return !probe.error && probe.status === 0;
-}
-
 const savedTls = await loadSavedTlsSettings();
 const env = { ...process.env, };
 const explicitCaCert = flagValue(["--ca-cert", "--extra-ca-certs",],);
@@ -62,12 +57,13 @@ if (hasFlag(["--insecure", "--skip-tls-verify",],)) {
 	env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
 }
 
-const nodeBin = process.versions.bun ? "node" : process.execPath;
+const runningOnBun = Boolean(process.versions.bun,);
 const usesSourceCli = cliPath === sourceCliPath;
-const nodeArgs = !usesSourceCli && supportsSystemCa(nodeBin,) ? ["--use-system-ca",] : [];
+const runtimeBin = runningOnBun ? process.execPath : usesSourceCli ? "bun" : process.execPath;
+const runtimeArgs = runningOnBun || usesSourceCli ? ["--no-env-file",] : ["--use-system-ca",];
 const result = spawnSync(
-	usesSourceCli ? "bun" : nodeBin,
-	[...(usesSourceCli ? ["--no-env-file",] : nodeArgs), cliPath, ...args,],
+	runtimeBin,
+	[...runtimeArgs, cliPath, ...args,],
 	{
 		stdio: "inherit",
 		env,
@@ -77,25 +73,24 @@ const result = spawnSync(
 if (result.error) {
 	const message = usesSourceCli
 		? `Unable to start Bun runtime for source dss CLI (${result.error.message}).`
-		: `Unable to start Node runtime for packaged dss CLI (${result.error.message}); falling back to current runtime without Node system CA bootstrap.`;
+		: `Unable to start ${
+			runningOnBun ? "Bun" : "Node"
+		} runtime for packaged dss CLI (${result.error.message}); falling back to the current runtime.`;
 	if (usesSourceCli) {
 		process.stderr.write(`${
-			JSON.stringify(
-				{
-					ok: false,
-					error: message,
-					code: "internal_error",
-					category: "internal",
-					message,
-					exitCode: 2,
-				},
-				null,
-				2,
-			)
+			JSON.stringify({
+				type: "error",
+				ok: false,
+				error: message,
+				code: "internal_error",
+				category: "internal",
+				exitCode: 2,
+			},)
 		}\n`,);
-		process.exit(2,);
+		process.exitCode = 2;
+	} else {
+		await import(cliUrl);
 	}
-	await import(cliUrl);
 } else if (result.signal) {
 	process.kill(process.pid, result.signal,);
 } else {

package/dist/src/cli/commands/api-service.js

@@ -59,7 +59,6 @@ export const apiServiceCommands = {
         handler: async (c, a, f) => {
             requireArgs(a, 1, "dss api-service list-packages <serviceId> [--project-key KEY]");
             const projectKey = f["project-key"];
-            await c.apiServices.getSettings(a[0], projectKey);
             return c.apiServices.listPackages(a[0], projectKey);
         },
         usage: "dss api-service list-packages <serviceId> [--project-key KEY]",

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

@@ -44,7 +44,11 @@ export const notebookCommands = {
                 const current = await c.notebooks.getJupyter(a[0], pk);
                 const next = {
                     ...current,
-                    cells: current.cells.map((cell) => ({ ...cell, outputs: [], execution_count: null, })),
+                    cells: current.cells.map((cell) => {
+                        if (cell.cell_type !== "code")
+                            return cell;
+                        return { ...cell, outputs: [], execution_count: 0, };
+                    }),
                 };
                 return {
                     dryRun: true,

package/dist/src/cli/output.js

@@ -73,7 +73,7 @@ export function transientBodyWithTargetContext(body, target, elapsedMs) {
 }
 export function addTransientTargetContext(error, target, elapsedMs) {
     if (error instanceof DataikuError && error.category === "transient") {
-        throw new DataikuError(error.status, error.statusText, transientBodyWithTargetContext(error.body, target, elapsedMs), error.retry, error.requestId);
+        throw new DataikuError(error.status, error.statusText, transientBodyWithTargetContext(error.body, target, elapsedMs), error.retry, error.requestId, { target, elapsedMs, });
     }
     throw error;
 }

package/dist/src/cli.js

@@ -12,7 +12,7 @@ import { COMMANDS_RUN_HINT, missingActionError, noCommandError, requireArgs, unk
 import { cliVersionResult, } from "./cli/version.js";
 import { DataikuClient, } from "./client.js";
 import { getCredentialsPath, } from "./config.js";
-import { ClientValidationError, DataikuError, dataikuErrorCode, } from "./errors.js";
+import { canonicalStatusText, ClientValidationError, DataikuError, dataikuErrorCode, } from "./errors.js";
 import { AGENTS, detectAgents, findWorkspaceRoot, installSkill, planSkillInstalls, } from "./skill.js";
 import { appendCleanupLedgerEntry, readCleanupLedger, } from "./utils/cleanup-ledger.js";
 // ---------------------------------------------------------------------------
@@ -833,16 +833,41 @@ function rawCommandContext() {
                 : undefined),
     };
 }
-function requestIdFromBody(body) {
+const SAFE_RESPONSE_METADATA_KEYS = [
+    "requestId",
+    "request_id",
+    "errorId",
+    "elapsedMs",
+];
+function safeResponseMetadata(body) {
     try {
         const parsed = JSON.parse(body);
-        const value = parsed.requestId ?? parsed.request_id ?? parsed.errorId;
-        return typeof value === "string" && value.length > 0 ? value : undefined;
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const metadata = {};
+        for (const key of SAFE_RESPONSE_METADATA_KEYS) {
+            const value = parsed[key];
+            if ((typeof value === "string" && value.length > 0)
+                || (typeof value === "number" && Number.isFinite(value))
+                || typeof value === "boolean") {
+                metadata[key] = value;
+            }
+        }
+        return metadata;
     }
     catch {
-        return undefined;
+        return {};
     }
 }
+function requestIdFromBody(body) {
+    const metadata = safeResponseMetadata(body);
+    for (const key of ["requestId", "request_id", "errorId",]) {
+        const value = metadata[key];
+        if (typeof value === "string")
+            return value;
+    }
+    return undefined;
+}
 const MISSING_PROJECT_KEY_ERROR_PREFIX = "projectKey is required";
 function errorExitCode(err) {
     if (err instanceof CommandResultFailure)
@@ -884,13 +909,18 @@ function buildErrorReport(err) {
         };
     }
     if (err instanceof DataikuError) {
-        const errorMessage = err.category === "not_found"
-            && err.message.includes("Dataiku instance not found")
-            && context.resource
+        const errorMessage = err.category === "not_found" && context.resource
             ? `Not found: ${context.resource}${context.action ? ` ${context.action}` : ""}`
                 + `${context.projectKey ? ` in project ${context.projectKey}` : ""}`
-                + ` — verify the object identifier and project key (DSS: ${err.message.split("\n")[0]}).`
-            : err.message;
+                + " — verify the object identifier and project key."
+                + `\nHint: ${err.retryHint}`
+            : err.safeMessage;
+        const safeMetadata = safeResponseMetadata(err.body);
+        if (err.trustedTarget)
+            safeMetadata.target = err.trustedTarget;
+        if (err.trustedElapsedMs !== undefined)
+            safeMetadata.elapsedMs = err.trustedElapsedMs;
+        const safeBody = JSON.stringify(safeMetadata);
         return {
             type: "error",
             ok: false,
@@ -904,8 +934,8 @@ function buildErrorReport(err) {
             requestId: err.requestId ?? requestIdFromBody(err.body),
             details: {
                 dssCategory: err.category,
-                statusText: err.statusText,
-                body: err.body,
+                statusText: canonicalStatusText(err.status),
+                body: safeBody,
                 ...(err.retry ? { retry: err.retry, } : {}),
             },
             ...context,
@@ -969,7 +999,7 @@ async function main() {
     if (metaCommand) {
         writeCommandResult(metaCommand.result);
         if (metaCommand.exitCode !== 0)
-            process.exit(metaCommand.exitCode);
+            process.exitCode = metaCommand.exitCode;
         return;
     }
     if (!commands[resource])
@@ -1033,5 +1063,5 @@ async function main() {
 }
 main().catch((err) => {
     writeErrorReport(err);
-    process.exit(errorExitCode(err));
+    process.exitCode = errorExitCode(err);
 });

package/dist/src/errors.d.ts

@@ -15,6 +15,11 @@ export interface DataikuRetryMetadata {
     delaysMs: number[];
     timedOut: boolean;
 }
+export interface DataikuErrorTrustedMetadata {
+    target?: string;
+    elapsedMs?: number;
+}
+export declare function canonicalStatusText(status: number): string;
 export declare class ClientValidationError extends Error {
     readonly code: StableErrorCode;
     readonly hint?: string;
@@ -31,7 +36,10 @@ export declare class DataikuError extends Error {
     retryHint: string;
     retry?: DataikuRetryMetadata;
     requestId?: string;
-    constructor(status: number, statusText: string, body: string, retry?: DataikuRetryMetadata, requestId?: string);
+    readonly trustedTarget?: string;
+    readonly trustedElapsedMs?: number;
+    constructor(status: number, statusText: string, body: string, retry?: DataikuRetryMetadata, requestId?: string, trustedMetadata?: DataikuErrorTrustedMetadata);
+    get safeMessage(): string;
     private static extractSummary;
     private static formatRetryMetadata;
     private static buildDetails;

package/dist/src/errors.js

@@ -12,6 +12,25 @@ export function dataikuErrorCode(category) {
             return "internal_error";
     }
 }
+const CANONICAL_STATUS_TEXT = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    408: "Request Timeout",
+    409: "Conflict",
+    422: "Unprocessable Entity",
+    425: "Too Early",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+};
+export function canonicalStatusText(status) {
+    return CANONICAL_STATUS_TEXT[status] ?? (status === 0 ? "Network Error" : "HTTP Error");
+}
 export class ClientValidationError extends Error {
     code;
     hint;
@@ -276,8 +295,10 @@ export class DataikuError extends Error {
     retryHint;
     retry;
     requestId;
-    constructor(status, statusText, body, retry, requestId) {
-        const details = DataikuError.buildDetails(status, statusText, body, retry);
+    trustedTarget;
+    trustedElapsedMs;
+    constructor(status, statusText, body, retry, requestId, trustedMetadata) {
+        const details = DataikuError.buildDetails(status, body, retry);
         super(details.message);
         this.status = status;
         this.statusText = statusText;
@@ -288,8 +309,20 @@ export class DataikuError extends Error {
         this.retryHint = details.retryHint;
         this.retry = retry;
         this.requestId = requestId;
+        this.trustedTarget = trustedMetadata?.target;
+        this.trustedElapsedMs = trustedMetadata?.elapsedMs;
+    }
+    get safeMessage() {
+        const retrySummary = DataikuError.formatRetryMetadata(this.retry);
+        return [
+            `${this.status} ${canonicalStatusText(this.status)}`,
+            `Error type: ${this.category}`,
+            `Retryable: ${this.retryable ? "yes" : "no"}`,
+            `Hint: ${this.retryHint}`,
+            ...(retrySummary ? [retrySummary,] : []),
+        ].join("\n");
     }
-    static extractSummary(_status, _statusText, body) {
+    static extractSummary(_status, body) {
         try {
             const parsed = JSON.parse(body);
             if (parsed.message)
@@ -316,14 +349,14 @@ export class DataikuError extends Error {
             `Timed out: ${retry.timedOut ? "yes" : "no"}`,
         ].join(" | ");
     }
-    static buildDetails(status, statusText, body, retry) {
-        const summary = DataikuError.extractSummary(status, statusText, body);
+    static buildDetails(status, body, retry) {
+        const summary = DataikuError.extractSummary(status, body);
         const taxonomy = classifyDataikuError(status, body);
         const retrySummary = DataikuError.formatRetryMetadata(retry);
         return {
             ...taxonomy,
             message: [
-                `${status} ${statusText}: ${summary}`,
+                `${status} ${canonicalStatusText(status)}: ${summary}`,
                 `Error type: ${taxonomy.category}`,
                 `Retryable: ${taxonomy.retryable ? "yes" : "no"}`,
                 `Hint: ${taxonomy.retryHint}`,

package/dist/src/resources/api-services.js

@@ -28,6 +28,7 @@ export class ApiServicesResource extends BaseResource {
     }
     /** List deployable packages for an API service. */
     async listPackages(serviceId, projectKey) {
+        await this.getSettings(serviceId, projectKey);
         return this.client.get(`${this.servicePath(serviceId, projectKey)}/packages`);
     }
     /** Get an API service package summary. */

package/dist/src/resources/notebooks.js

@@ -36,11 +36,15 @@ export class NotebooksResource extends BaseResource {
      */
     async clearJupyterOutputs(name, projectKey) {
         const notebook = await this.getJupyter(name, projectKey);
-        const clearedCells = notebook.cells.map((cell) => ({
-            ...cell,
-            outputs: [],
-            execution_count: null,
-        }));
+        const clearedCells = notebook.cells.map((cell) => {
+            if (cell.cell_type !== "code")
+                return cell;
+            return {
+                ...cell,
+                outputs: [],
+                execution_count: 0,
+            };
+        });
         await this.saveJupyter(name, { ...notebook, cells: clearedCells, }, projectKey);
     }
     /** List running kernel sessions for a Jupyter notebook. */

package/dist/src/resources/sql.js

@@ -1,4 +1,4 @@
-import { DataikuError, } from "../errors.js";
+import { ClientValidationError, DataikuError, } from "../errors.js";
 import { BaseResource, } from "./base.js";
 const UNSUPPORTED_SQL_DATASET_CONNECTION_DETAIL = "neither of sql nor hdfs type";
 function isUnsupportedSqlDatasetConnectionError(error) {
@@ -161,28 +161,23 @@ export class SqlResource extends BaseResource {
         const datasetFullName = opts.datasetFullName;
         if (!datasetFullName)
             return null;
-        try {
-            const identifier = splitDatasetIdentifier(datasetFullName, opts.projectKey);
-            const projectKey = identifier.projectKey
-                ? identifier.projectKey
-                : this.resolveProjectKey(opts.projectKey);
-            const dsEnc = encodeURIComponent(identifier.datasetName);
-            const raw = await this.client.get(`/public/api/projects/${encodeURIComponent(projectKey)}/datasets/${dsEnc}`);
-            const params = asRecord(raw.params);
-            const connection = asString(params?.connection);
-            if (!connection)
-                return null;
-            return {
-                ...opts,
-                connection,
-                datasetFullName: undefined,
-                database: opts.database ?? asString(params?.schema) ?? asString(params?.catalog),
-                projectKey,
-            };
-        }
-        catch {
+        const identifier = splitDatasetIdentifier(datasetFullName, opts.projectKey);
+        const projectKey = identifier.projectKey
+            ? identifier.projectKey
+            : this.resolveProjectKey(opts.projectKey);
+        const dsEnc = encodeURIComponent(identifier.datasetName);
+        const raw = await this.client.get(`/public/api/projects/${encodeURIComponent(projectKey)}/datasets/${dsEnc}`);
+        const params = asRecord(raw.params);
+        const connection = asString(params?.connection);
+        if (!connection)
             return null;
-        }
+        return {
+            ...opts,
+            connection,
+            datasetFullName: undefined,
+            database: opts.database ?? asString(params?.schema) ?? asString(params?.catalog),
+            projectKey,
+        };
     }
     /**
      * Execute a SQL query end-to-end: start, stream all rows, verify, return combined result.
@@ -198,9 +193,7 @@ export class SqlResource extends BaseResource {
                 withSqlErrorContext(error);
             const retryOpts = await this.resolveDatasetQueryFallback(queryOpts);
             if (!retryOpts) {
-                throw new Error(buildUnsupportedSqlDatasetConnectionMessage(queryOpts.datasetFullName), {
-                    cause: error,
-                });
+                throw new ClientValidationError(buildUnsupportedSqlDatasetConnectionMessage(queryOpts.datasetFullName));
             }
             try {
                 return await this.executeQuery(retryOpts);

package/dist/src/skill.js

@@ -1,11 +1,11 @@
 import { execFileSync, } from "node:child_process";
-import { existsSync, mkdirSync, writeFileSync, } from "node:fs";
-import { homedir, } from "node:os";
-import { dirname, join, } from "node:path";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 const SKILL_BODY = `# Dataiku DSS agent CLI
 
 Use \`dss\` when an agent needs to inspect or change Dataiku DSS resources: projects, datasets, recipes, jobs, scenarios, folders, notebooks, SQL, variables, code envs, and connections.
-If the installed \`dss\` binary is unavailable but the repository checkout is the current workspace, use \`./bin/dss ...\` or \`bun --no-env-file src/cli.ts ...\` with the same arguments; from another working directory, call \`/path/to/dataiku-sdk/bin/dss ...\`.
+If the installed \`dss\` binary is unavailable but the repository checkout is the current workspace, prefer \`bun --no-env-file src/cli.ts ...\` or \`bun --no-env-file ./bin/dss.js ...\`. Node users can invoke the same cross-runtime launcher as \`node ./bin/dss.js ...\`; when \`dist/\` has not been built, 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.
 
 ## Contract
@@ -20,7 +20,7 @@ If the installed \`dss\` binary is unavailable but the repository checkout is th
 
 ## Discover commands
 
-\`\`\`bash
+\`\`\`text
 dss agent contract
 dss commands run
 \`\`\`
@@ -31,30 +31,57 @@ Set \`DATAIKU_DISABLE_ENV=1\` when a test must ignore both \`.env\` files and \`
 When \`.env\` loading is enabled, the CLI reads \`.env\` from the command's current working directory first and then the CLI build/root directory; the invocation directory wins on conflicting keys. Put test-specific \`.env\` files in the directory where you invoke \`dss\`.
 For disposable agent tests, set \`DSS_CONFIG_DIR\` to a temporary directory so saved credentials never touch the real profile.
 
+## Planning, safety, and generic inputs
+
+- Before any registry entry with \`sideEffect:"write"\`, run the exact argv with \`--plan\` first. Planning is local: it returns the derived operation without resolving credentials or calling DSS. Check \`destructive\`, \`idempotency\`, \`async\`, \`unsafeOutputs\`, and \`exitCodes\` before execution.
+- Use \`--dry-run\` only when that action's registry entry has \`dryRun:true\`. \`--plan\` explains the operation; \`--dry-run\` exercises the action-specific simulation path. Never add an unsupported flag.
+- When a create/upload action advertises \`--record-cleanup\`, pass \`--record-cleanup cleanup.jsonl\`. \`dss cleanup --file cleanup.jsonl\` previews the recorded cleanup steps in reverse order and does not mutate DSS; add \`--apply\` only after checking the preview.
+- For JSON payload actions, follow \`inputContract\`, \`requiredFlags\`, and \`requiredOneOf\`. Prefer \`--data-file PATH\` or \`--stdin\` when advertised instead of inline \`--data\`; this preserves exact JSON across shells and keeps large or sensitive payloads out of process arguments.
+- Authenticated actions advertise \`--request-timeout MS\` and \`--retries N\`. Long-running actions separately advertise controls such as \`--timeout MS\`, \`--poll-interval MS\`, and log limits; use only the flags in that action's registry entry.
+- Before live mutation tests, use \`dss fixtures --json\` to discover compatible test resources instead of guessing project objects.
+
 ## Authentication
 
-Prefer environment variables for ephemeral agent runs:
+Prefer environment variables for ephemeral agent runs. Use the syntax for the active shell:
 
-\`\`\`bash
+POSIX shell:
+
+\`\`\`sh
 export DATAIKU_URL=https://dss.example.com
 export DATAIKU_API_KEY=your-api-key
 export DATAIKU_PROJECT_KEY=MYPROJ
 \`\`\`
 
+PowerShell:
+
+\`\`\`powershell
+$env:DATAIKU_URL = "https://dss.example.com"
+$env:DATAIKU_API_KEY = "your-api-key"
+$env:DATAIKU_PROJECT_KEY = "MYPROJ"
+\`\`\`
+
+Windows Command Prompt:
+
+\`\`\`bat
+set "DATAIKU_URL=https://dss.example.com"
+set "DATAIKU_API_KEY=your-api-key"
+set "DATAIKU_PROJECT_KEY=MYPROJ"
+\`\`\`
+
 To persist credentials for later invocations:
 
 \`\`\`bash
 dss auth login --url https://dss.example.com --api-key YOUR_KEY --project-key MYPROJ
 \`\`\`
 
-The command saves credentials and returns \`{"saved":true,"path":"..."}\`. Credentials are saved to \`~/.config/dataiku/credentials.json\` unless \`DSS_CONFIG_DIR\` or platform config env vars redirect the path.
+The command saves credentials and returns \`{"saved":true,"path":"..."}\`. \`DSS_CONFIG_DIR\` wins when set. Otherwise credentials use \`XDG_CONFIG_HOME/dataiku/credentials.json\`, the \`dataiku/credentials.json\` directory under \`APPDATA\` on Windows, or \`~/.config/dataiku/credentials.json\`.
 \`auth login\` validates by listing accessible projects before saving credentials, so the API key must be allowed to call DSS project-list APIs.
 
 TLS flags: \`--insecure\` disables certificate verification; \`--ca-cert PATH\` adds a PEM CA bundle. Environment equivalents: \`NODE_TLS_REJECT_UNAUTHORIZED\`, \`NODE_EXTRA_CA_CERTS\`.
 
 ## Common workflows
 
-\`\`\`bash
+\`\`\`text
 dss version
 dss project list
 dss doctor --fast
@@ -77,10 +104,10 @@ For fake-DSS smoke tests, return project lists as JSON arrays such as \`[{"proje
 
 Mutations print a small JSON ack to stdout and exit 0 on success (e.g. \`{"updated":"NAME","resource":"recipe"}\`); on failure they print the error envelope to stderr and exit non-zero. The exit code is the source of truth.
 
-- Chain steps with \`&&\` so a failed step halts the sequence: \`dss recipe set-payload R --file r.py --project-key P && dss recipe update R --data-file env.json --project-key P\`.
-- Never pipe a mutation into a command that prints a fixed string or merges stderr (e.g. \`dss ... 2>&1 | helper; echo done\`): the pipeline returns the helper's exit code, so a failed mutation is reported as success.
+- For portable multi-step writes, prefer \`dss batch\` (payload: a JSON array of argv arrays). It runs fail-fast, returns one envelope with per-step \`ok\`/\`result\`/\`error\`, and exits non-zero if any step fails.
+- If separate processes are required, inspect each exit code and stop before launching the next step. Do not rely on shell chaining: syntax differs between POSIX shells, Windows PowerShell 5.1, PowerShell 7, and Command Prompt.
+- Never pipe a mutation into a command that prints a fixed string or merges stderr: a pipeline may return the helper's exit code and report a failed mutation as success.
 - To branch in code, key off the exit code or the JSON ack on stdout — never a hardcoded label.
-- For multi-step writes, prefer \`dss batch\` (payload: a JSON array of argv arrays): it runs fail-fast, returns one envelope with per-step \`ok\`/\`result\`/\`error\`, and exits non-zero if any step fails — no shell chaining or per-step parsing.
 
 ## Platform & debugging notes
 
@@ -127,7 +154,7 @@ export const AGENTS = {
         name: "Claude Code",
         binary: "claude",
         configDir: ".claude",
-        globalPath: (home) => join(home, ".claude", "skills", "dataiku-dss"),
+        globalPath: (home) => path.join(home, ".claude", "skills", "dataiku-dss"),
         projectPath: ".claude/skills/dataiku-dss",
         filename: "SKILL.md",
         content: skillContent,
@@ -136,7 +163,7 @@ export const AGENTS = {
         name: "Codex",
         binary: "codex",
         configDir: ".codex",
-        globalPath: (home) => join(home, ".codex", "skills", "dataiku-dss"),
+        globalPath: (home) => path.join(home, ".codex", "skills", "dataiku-dss"),
         projectPath: ".codex/skills/dataiku-dss",
         filename: "SKILL.md",
         content: skillContent,
@@ -145,7 +172,7 @@ export const AGENTS = {
         name: "Cursor",
         binary: "cursor",
         configDir: ".cursor",
-        globalPath: (home) => join(home, ".cursor", "skills", "dataiku-dss"),
+        globalPath: (home) => path.join(home, ".cursor", "skills", "dataiku-dss"),
         projectPath: ".cursor/skills/dataiku-dss",
         filename: "SKILL.md",
         content: skillContent,
@@ -154,7 +181,7 @@ export const AGENTS = {
         name: "Pi",
         binary: "pi",
         configDir: ".pi",
-        globalPath: (home) => join(home, ".pi", "agent", "skills", "dataiku-dss"),
+        globalPath: (home) => path.join(home, ".pi", "agent", "skills", "dataiku-dss"),
         projectPath: ".pi/skills/dataiku-dss",
         filename: "SKILL.md",
         content: skillContent,
@@ -162,9 +189,9 @@ export const AGENTS = {
     omp: {
         name: "OhMyPi",
         binary: "omp",
-        configDir: join(".omp", "agent"),
+        configDir: path.join(".omp", "agent"),
         configDirRequired: true,
-        globalPath: (home) => join(home, ".omp", "agent", "skills", "dataiku-dss"),
+        globalPath: (home) => path.join(home, ".omp", "agent", "skills", "dataiku-dss"),
         projectPath: ".omp/skills/dataiku-dss",
         filename: "SKILL.md",
         content: skillContent,
@@ -184,11 +211,11 @@ function binaryExists(name) {
     }
 }
 export function detectAgents() {
-    const home = homedir();
+    const home = os.homedir();
     const found = [];
     for (const [id, def,] of Object.entries(AGENTS)) {
         const hasBinary = binaryExists(def.binary);
-        const hasConfigDir = existsSync(join(home, def.configDir));
+        const hasConfigDir = fs.existsSync(path.join(home, def.configDir));
         if (hasBinary && (!def.configDirRequired || hasConfigDir)) {
             found.push({ id, def, via: "binary", });
         }
@@ -213,10 +240,10 @@ export function findWorkspaceRoot(startDir) {
     let dir = startDir;
     for (let i = 0; i < 20; i++) {
         for (const marker of WORKSPACE_MARKERS) {
-            if (existsSync(join(dir, marker)))
+            if (fs.existsSync(path.join(dir, marker)))
                 return dir;
         }
-        const parent = dirname(dir);
+        const parent = path.dirname(dir);
         if (parent === dir)
             break;
         dir = parent;
@@ -224,17 +251,17 @@ export function findWorkspaceRoot(startDir) {
     return startDir;
 }
 export function planSkillInstalls(agents, opts) {
-    const home = homedir();
+    const home = os.homedir();
     const results = [];
     for (const { id, def, via, } of agents) {
         const dir = opts.global
             ? def.globalPath(home)
             : def.projectPath
-                ? join(opts.cwd, def.projectPath)
+                ? path.join(opts.cwd, def.projectPath)
                 : undefined;
         if (!dir)
             continue;
-        results.push({ agent: id, path: join(dir, def.filename), via, });
+        results.push({ agent: id, path: path.join(dir, def.filename), via, });
     }
     return results;
 }
@@ -244,8 +271,8 @@ export function installSkill(agents, opts) {
         const def = AGENTS[result.agent];
         if (!def)
             continue;
-        mkdirSync(dirname(result.path), { recursive: true, });
-        writeFileSync(result.path, def.content(), "utf-8");
+        fs.mkdirSync(path.dirname(result.path), { recursive: true, });
+        fs.writeFileSync(result.path, def.content(), "utf-8");
     }
     return results;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dataiku-sdk",
-	"version": "0.12.1",
+	"version": "0.12.3",
 	"description": "Dataiku DSS SDK and CLI for programmatic access to DSS REST APIs",
 	"type": "module",
 	"workspaces": [
@@ -17,25 +17,28 @@
 		"packages/types/dist/"
 	],
 	"engines": {
-		"bun": ">=1.0"
+		"node": ">=22.15.0",
+		"bun": ">=1.3.14"
 	},
 	"scripts": {
-		"build": "tsc && cd packages/types && npx tsc",
-		"prepack": "bun run build",
-		"prepublishOnly": "bun run build",
+		"build": "tsc && tsc -p packages/types/tsconfig.json",
+		"prepack": "tsc && tsc -p packages/types/tsconfig.json",
+		"prepublishOnly": "tsc && tsc -p packages/types/tsconfig.json",
 		"check": "tsc --noEmit",
 		"lint": "oxlint src/",
 		"lint:fix": "oxlint --fix src/",
 		"format": "dprint fmt",
 		"format:check": "dprint check",
 		"test": "bun test",
-		"test:integration": "RUN_DATAIKU_INTEGRATION=1 bun test tests/integration-playground.test.ts",
-		"test:integration:mutating": "RUN_DATAIKU_INTEGRATION=1 RUN_DATAIKU_INTEGRATION_MUTATING=1 bun test tests/integration-playground.test.ts",
-		"test:integration:rigorous": "RUN_DATAIKU_INTEGRATION=1 bun test tests/integration-rigorous.test.ts",
-		"test:integration:rigorous:mutating": "RUN_DATAIKU_INTEGRATION=1 RUN_DATAIKU_INTEGRATION_MUTATING=1 bun test tests/integration-rigorous.test.ts"
+		"test:platform": "bun scripts/platform-smoke.mjs",
+		"test:integration": "cross-env RUN_DATAIKU_INTEGRATION=1 bun test tests/integration-playground.test.ts",
+		"test:integration:mutating": "cross-env RUN_DATAIKU_INTEGRATION=1 RUN_DATAIKU_INTEGRATION_MUTATING=1 bun test tests/integration-playground.test.ts",
+		"test:integration:rigorous": "cross-env RUN_DATAIKU_INTEGRATION=1 bun test tests/integration-rigorous.test.ts",
+		"test:integration:rigorous:mutating": "cross-env RUN_DATAIKU_INTEGRATION=1 RUN_DATAIKU_INTEGRATION_MUTATING=1 bun test tests/integration-rigorous.test.ts"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14",
+		"cross-env": "^10.1.0",
 		"dprint": "^0.54.0",
 		"oxlint": "^1.68.0",
 		"typescript": "^6.0.3"
@@ -53,5 +56,8 @@
 	},
 	"publishConfig": {
 		"access": "public"
-	}
+	},
+	"bundleDependencies": [
+		"@sinclair/typebox"
+	]
 }