dataiku-sdk 0.6.2 → 0.7.0

package/README.md

@@ -0,0 +1,85 @@
+# dataiku-sdk
+
+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 ...`.
+`--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
+
+- Success: stdout contains one JSON result.
+- Failure: stderr contains one JSON error envelope with `ok:false`, `error`, `code`, and `exitCode`.
+- `--verbose` may add HTTP trace lines to stderr.
+- `--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).
+- `--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 complete machine-readable command surface:
+
+```bash
+dss commands run
+```
+
+Agents should parse `commands run` before choosing syntax; inspect `flags`, `requiresAuth`, `requiresProject`, `sideEffect`, and `outputShape` instead of guessing.
+
+## Agent skill installation
+
+```bash
+dss install-skill --list-agents
+dss install-skill --agent omp --target .
+dss install-skill --agent omp --target . --dry-run
+dss install-skill --global --agent omp
+```
+
+`--list-agents` only reports targetable agents; it does not write files. Auto-detection checks supported agent binaries/config directories (`claude`, `codex`, `cursor`, `pi`, `omp`). Passing `--agent NAME` forces one entry and reports `via:"flag"`.
+
+Project installs write `SKILL.md` under the target workspace:
+
+- Claude: `.claude/skills/dataiku-dss/SKILL.md`
+- Codex: `.codex/skills/dataiku-dss/SKILL.md`
+- Cursor: `.cursor/skills/dataiku-dss/SKILL.md`
+- Pi: `.pi/skills/dataiku-dss/SKILL.md`
+- OMP: `.omp/skills/dataiku-dss/SKILL.md`
+
+Global installs write under the agent's home config path, for example OMP: `~/.omp/agent/skills/dataiku-dss/SKILL.md`.
+
+## 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.
+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 \
+dss project list
+```
+
+Persist credentials when needed:
+
+```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": "..." }`.
+`auth login` validates by listing accessible projects before saving credentials, so the API key must be allowed to call DSS project-list APIs.
+
+## Examples
+
+```bash
+dss version
+dss doctor --fast
+dss project list
+dss dataset list --project-key MYPROJ
+dss recipe get-payload compute_orders --project-key MYPROJ
+dss recipe get-payload compute_orders --raw --project-key MYPROJ
+dss recipe get-payload compute_orders --raw --output code.py --project-key MYPROJ
+dss install-skill --dry-run
+```
+
+For fake-DSS smoke tests, return project lists as JSON arrays such as `[{ "projectKey": "MYPROJ", "name": "My Project" }]` from `/public/api/projects/`; recipe payload commands read `/public/api/projects/<PROJECT>/recipes/<NAME>?includePayload=true` and expect a JSON object shaped like `{ "recipe": { "name": "<NAME>", "type": "python" }, "payload": "..." }`.

package/bin/dss.js

@@ -1,18 +1,22 @@
 #!/usr/bin/env node
 import { spawnSync, } from "node:child_process";
+import { existsSync, } from "node:fs";
 import { dirname, resolve, } 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 cliPath = resolve(here, "../dist/src/cli.js",);
+const distCliPath = resolve(here, "../dist/src/cli.js",);
+const sourceCliPath = resolve(here, "../src/cli.ts",);
+const cliPath = existsSync(distCliPath,) ? distCliPath : sourceCliPath;
 const cliUrl = pathToFileURL(cliPath,).href;
 
 function flagValue(names,) {
-	for (let i = 0; i < args.length; i++) {
-		const arg = args[i];
+	for (let i = 0; i < optionArgs.length; i++) {
+		const arg = optionArgs[i];
 		for (const name of names) {
-			if (arg === name) return args[i + 1];
+			if (arg === name) return optionArgs[i + 1];
 			if (arg.startsWith(`${name}=`,)) return arg.slice(name.length + 1,);
 		}
 	}
@@ -20,7 +24,7 @@ function flagValue(names,) {
 }
 
 function hasFlag(names,) {
-	return names.some((name,) => args.includes(name,));
+	return names.some((name,) => optionArgs.includes(name,));
 }
 
 async function loadSavedTlsSettings() {
@@ -59,16 +63,38 @@ if (hasFlag(["--insecure", "--skip-tls-verify",],)) {
 }
 
 const nodeBin = process.versions.bun ? "node" : process.execPath;
-const nodeArgs = supportsSystemCa(nodeBin,) ? ["--use-system-ca",] : [];
-const result = spawnSync(nodeBin, [...nodeArgs, cliPath, ...args,], {
-	stdio: "inherit",
-	env,
-},);
+const usesSourceCli = cliPath === sourceCliPath;
+const nodeArgs = !usesSourceCli && supportsSystemCa(nodeBin,) ? ["--use-system-ca",] : [];
+const result = spawnSync(
+	usesSourceCli ? "bun" : nodeBin,
+	[...(usesSourceCli ? ["--no-env-file",] : nodeArgs), cliPath, ...args,],
+	{
+		stdio: "inherit",
+		env,
+	},
+);
 
 if (result.error) {
-	process.stderr.write(
-		`Unable to start Node runtime for packaged dss CLI (${result.error.message}); falling back to current runtime without Node system CA bootstrap.\n`,
-	);
+	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.`;
+	if (usesSourceCli) {
+		process.stderr.write(`${
+			JSON.stringify(
+				{
+					ok: false,
+					error: message,
+					code: "internal_error",
+					category: "internal",
+					message,
+					exitCode: 2,
+				},
+				null,
+				2,
+			)
+		}\n`,);
+		process.exit(2,);
+	}
 	await import(cliUrl);
 } else if (result.signal) {
 	process.kill(process.pid, result.signal,);