dataiku-sdk 3.1.0 → 3.3.0

package/skills/dataiku-dss/references/discovery.md

@@ -0,0 +1,30 @@
+# Discovery and output
+
+## Contract
+
+- Stdout: exactly one compact JSON value; void success: `{ok:true}`. No prompts, help screens, tables, banners, or prose.
+- Dispatch/runtime failure: stdout error object (`type:"error"`, `ok:false`, `error`, `code`, `category`, `exitCode`), nonzero exit. `doctor`/`batch`/`cleanup` failures instead return direct result objects; inspect exit code and fields.
+- Stderr: JSONL diagnostics only; `type:"warning"` / `type:"trace"` for warnings / `--verbose` HTTP traces, flushed before success or failure output.
+- Exits: 0 success, 1 usage/configuration, 2 DSS/internal, 3 transient/retryable DSS error, 4 failed long-running result/assertion.
+- Recipe payload stdout: JSON string. With `--output PATH`: exact bytes to file, JSON string equal to `PATH` on stdout.
+- General `--fields a,b,c`: object projection, element-wise for object arrays. Dotted paths traverse nested objects; missing fields become `null`; strings/scalars pass through.
+
+## Discovery
+
+```text
+dss commands run
+dss agent contract --fields commands.actions.dataset
+dss commands run --fields dataset.create
+dss commands run --fields dataset.preview.usage,dataset.preview.description,dataset.preview.flags,dataset.preview.examples
+dss commands run --output commands.json
+dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility
+dss agent contract --fields commands.actions
+```
+
+`commands run` defaults to a resource→action-name summary (~1.6k tokens), never full entries. For a known resource, project `commands.actions.RESOURCE` from `agent contract` (~64 tokens for dataset). Bootstrap once with the six-field projection above (~250 tokens); fetch `schemas` or `commands` only as needed.
+
+Look up syntax before invoking. `--fields RESOURCE` selects every full entry (potentially large); `RESOURCE.ACTION` one complete entry; append `.FIELD` for nested metadata. Reads: prefer `usage,description,flags,examples`. Writes: fetch the full entry directly once, not compact-then-full. It includes flags, positionals, side effects, auth, output, idempotency, dry-run, examples, payload schemas, unsafe outputs, cleanup, and exits.
+
+Comma-separate selectors to batch lookups. Keys echo selectors: `--fields dataset.create` → `{"dataset.create":{...}}`. Empty `--fields` fails usage validation, never dumps everything. Unknown resources/actions exit 1 with compact JSON errors listing valid options.
+
+Full registry: `commands run --output PATH` only. With `--fields`, export that subset instead. Files contain compact JSON; stdout is `{"path":"PATH"}`, never registry content.

package/skills/dataiku-dss/references/flow-maps.md

@@ -0,0 +1,12 @@
+# Flow maps
+
+```text
+dss project map --render mermaid --project-key MYPROJ
+dss flow-zone plan --project-key MYPROJ > flow-zones.json
+dss flow-zone organize --file flow-zones.json --dry-run --project-key MYPROJ
+dss flow-zone organize --file flow-zones.json --project-key MYPROJ
+```
+
+`project map`: zones, SCC-safe layers, weak components, diagnostics, full-flow fingerprint; rendering in `rendering.content`. DSS exposes zone positions, not node pixels.
+
+Feed `flow-zone plan` to `flow-zone organize`; inspect dry-run first. Organize checks topology before/after writes and skips unchanged moves. Audit recipe payloads separately: layout commands neither fetch nor analyze code.

package/skills/dataiku-dss/references/mutations.md

@@ -0,0 +1,33 @@
+# Mutation and batch safety
+
+## Before writes
+
+- For `sideEffect:"write"`, first run exact argv with `--plan`: local derived operation, no credentials or DSS calls. Check `destructive`, `idempotency`, `async`, `unsafeOutputs`, `exitCodes` before execution.
+- `--plan` explains; `--dry-run` simulates, only when that action advertises `dryRun:true`. Never add unsupported flags.
+- For creates/uploads advertising it, pass `--record-cleanup cleanup.jsonl`. `dss cleanup --file cleanup.jsonl` previews reverse-order steps without mutation; inspect before adding `--apply`.
+- JSON: follow `inputContract`, `requiredFlags`, `requiredOneOf`. Prefer advertised `--data-file PATH` / `--stdin` over inline `--data`: preserve JSON across shells; keep large/sensitive payloads out of argv.
+- Authenticated actions expose `--request-timeout MS`, `--retries N` (idempotent GET only). Long-running actions expose `--timeout MS`, `--poll-interval MS`, log limits. Use only advertised flags.
+- Before live mutation tests, discover compatible resources with `dss fixtures`; never guess project objects.
+
+## Check results
+
+Success: small JSON ack on stdout, e.g. `{"updated":"NAME","resource":"recipe"}`, exit 0. Failure: stdout error envelope, nonzero exit. Exit code is authoritative.
+
+Prefer `dss batch` for portable multi-step writes: JSON array of argv arrays, fail-fast, one envelope with per-step `ok`/`result`/`error`, nonzero if any step fails. For separate processes, check each exit and stop on failure; chaining differs across POSIX, PowerShell 5.1/7, and Command Prompt.
+
+Never pipe mutations into fixed-string printers or stderr-merging helpers: their exit can mask failure. Branch on exits or stdout JSON acks, not hardcoded labels.
+
+## Workflows
+
+```text
+dss version
+dss project list
+dss recipe get-payload compute_orders --output code.py --project-key MYPROJ
+dss recipe diff compute_orders --file code.py --project-key MYPROJ
+dss recipe set-payload compute_orders --file code.py --project-key MYPROJ
+dss job build-and-wait orders --include-logs --project-key MYPROJ
+dss sql query --connection analytics --sql "select 1" --project-key MYPROJ
+dss batch --data-file steps.json
+```
+
+Fake DSS fixtures: `/public/api/projects/` returns an array, e.g. `[{"projectKey":"MYPROJ","name":"My Project"}]`. `/public/api/projects/<PROJECT>/recipes/<NAME>?includePayload=true` returns `{"recipe":{"name":"<NAME>","type":"python"},"payload":"..."}` for recipe payload commands.

package/skills/dataiku-dss/references/troubleshooting.md

@@ -0,0 +1,29 @@
+# Troubleshooting and data access
+
+## Platform, builds, data
+
+- Code/SQL: use `--file`/`--sql-file`; shells, especially PowerShell, mangle quotes, `$`, and multiline text. Non-UTF-8 consoles (e.g. Windows cp1252): write non-ASCII results to UTF-8 files or `--output PATH`, not the console.
+- Build errors: `dss job log <id> --errors-only` selects errors/tracebacks; `--output PATH` saves full logs. Logs are one JVM-noisy line; `Error in Python process: At line <N>` identifies the payload source line.
+- After python/SQL/prepare output-column changes, run `dss dataset refresh-schema` or rebuild before downstream reads. Run `dss dataset validate-build` before builds to catch file-backed misconfiguration. Exception: `dss recipe create --type sync` copies input schema to schemaless output at creation (`syncOutputSchemaPropagated`); fresh sync outputs build populated without manual refresh.
+- `dss dataset download`: default 100k rows; result `{ path, rows, truncated, limit }`. If truncated, raise `--limit`. Specify `--output` or read the `dataset_download_default_location` path warning. CSV is spreadsheet-safe; `--raw-data` retains formula prefixes. For large tables, aggregate in SQL or use a recipe.
+- `dss dashboard create`/`update`: before POST/PUT, every `INSIGHT` tile needs agreeing/resolvable `insightId` and `targetInsightId`; any `datasetSmartName` must resolve. Missing/stale references: `validation_failed`. Cross-project `PROJECT.DATASET` needs dataset-project read permission; `403` blocks saving an unverifiable dashboard.
+- `dss api-service list-packages SERVICE` checks parent settings first. `not_found`: missing service; verify service ID/project key. Empty array: existing service, no deployable packages. Never convert `not_found` to an empty list or retry the lower-level route.
+- `dss notebook clear-jupyter-outputs NAME --dry-run` plans the official output DELETE; apply uses it, never rewrites cells.
+
+## SQL
+
+- `dss sql query ... --dataset PROJECT.NAME` first queries via the dataset. Only when DSS rejects its connection as neither SQL nor HDFS does the CLI read metadata and retry `params.connection`, using schema/catalog as database if available. No usable connection on a readable dataset: `validation_failed`, use `--connection`. Metadata `404`/`403` propagate as `not_found`/`permission_denied`.
+- `--start-retries N` enables transient query-start POST retries with exponential backoff. Lost responses can execute SQL twice: **repetition-safe SQL only**. Ordinary `--retries N` remains GET-only.
+- No `--preview`: full stdout rows for compatibility. `--preview N`: bounded exploratory stdout. `--output PATH`: full rows to file.
+- SQL `--output`/`--output-file`: atomic complete JSON after query completion; failures preserve the destination. Replacements retain permission bits; new files use `0666` filtered by umask. Results still accumulate in memory before export.
+
+## Errors
+
+Dispatch/runtime failure: one compact stdout error:
+```json
+{"type":"error","ok":false,"error":"Missing API key.","code":"missing_required_flag","category":"usage","exitCode":1,"resource":"dataset","action":"list"}
+```
+
+`doctor`/`batch`/`cleanup` command failures return direct stdout result objects; check nonzero exit before interpreting. Recover from structured `code`, `category`, `exitCode`, `retryable`, `status`, `details`, never message scraping.
+
+`details.body` is sanitized metadata, **not the DSS response body**: at most `requestId`/`request_id`/`errorId`/`elapsedMs` plus locally trusted target/timing. `details.statusText` derives from numeric status, not remote reason phrases. Use top-level `code`, `category`, `status`, `retryable`, `requestId`, `hint`, and `details.dssCategory`; never assume server-body fields.