dataiku-sdk 0.12.1 → 0.12.2

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.js

@@ -969,7 +969,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 +1033,5 @@ async function main() {
 }
 main().catch((err) => {
     writeErrorReport(err);
-    process.exit(errorExitCode(err));
+    process.exitCode = errorExitCode(err);
 });

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.2",
 	"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"
+	]
 }