dataiku-sdk 0.6.1 → 0.7.0

package/dist/src/resources/flow-zones.js

@@ -24,15 +24,17 @@ export class FlowZonesResource extends BaseResource {
         const raw = await this.client.post(`/public/api/projects/${this.enc(opts.projectKey)}/flow/zones`, {
             name: opts.name,
             color: opts.color ?? "#2ab1ac",
+            ...(opts.position !== undefined ? { position: opts.position, } : {}),
         });
         return this.client.safeParse(FlowZoneSchema, raw, "flowZones.create");
     }
-    /** Update flow zone settings such as name and color. */
+    /** Update flow zone settings such as name, color, and manual position. */
     async update(zoneId, opts) {
         const current = await this.get(zoneId, opts.projectKey);
         const merged = deepMerge(current, {
             ...(opts.name !== undefined ? { name: opts.name, } : {}),
             ...(opts.color !== undefined ? { color: opts.color, } : {}),
+            ...(opts.position !== undefined ? { position: opts.position, } : {}),
         });
         await this.client.putVoid(`/public/api/projects/${this.enc(opts.projectKey)}/flow/zones/${encodeURIComponent(zoneId)}`, merged);
         return this.get(zoneId, opts.projectKey);

package/dist/src/resources/jobs.d.ts

@@ -62,6 +62,7 @@ export declare class JobsResource extends BaseResource {
     log(jobId: string, opts?: {
         activity?: string;
         logId?: string;
+        logFilter?: JobLogFilter;
         maxLogLines?: number;
         projectKey?: string;
     }): Promise<string>;

package/dist/src/resources/jobs.js

@@ -181,7 +181,7 @@ export class JobsResource extends BaseResource {
         // DSS cat-activity-log URLs require a browser session; API-key callers must use the public log endpoint.
         const path = `/public/api/projects/${this.enc(opts?.projectKey)}/jobs/${jobEnc}/log/${query}`;
         const log = await this.client.getText(path);
-        return limitJobLog(log, opts?.maxLogLines);
+        return limitJobLog(filterJobLog(log, opts?.logFilter), opts?.maxLogLines);
     }
     async logFromUrl(logUrl, opts) {
         const parsed = new URL(logUrl, "http://dss.local");

package/dist/src/resources/recipes.d.ts

@@ -53,6 +53,7 @@ export interface RecipeCloneOptions {
     copyOutputSettings?: boolean;
     outputPath?: string;
     metastoreTableName?: string;
+    recipeType?: string;
 }
 export interface RecipeCloneResult {
     sourceRecipeName: string;

package/dist/src/resources/recipes.js

@@ -108,7 +108,44 @@ function rewriteRefs(value, rewrites) {
 function escapedRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function rewritePayload(payload, rewrites, payloadTextRewrites = {}) {
+function isSqlRecipeType(recipeType) {
+    return typeof recipeType === "string" && recipeType.toLowerCase().includes("sql");
+}
+function rewriteSqlTableReferences(payload, rewrites) {
+    const bareIdentifierPattern = /^[A-Za-z_][A-Za-z0-9_$]*(?:\.[A-Za-z_][A-Za-z0-9_$]*)*$/;
+    const escapeQuotedIdentifier = (identifier, quote) => {
+        if (quote === "\"")
+            return identifier.replace(/"/g, '""');
+        if (quote === "`")
+            return identifier.replace(/`/g, "``");
+        return identifier;
+    };
+    const escapeBracketIdentifier = (identifier) => identifier.replace(/\]/g, "]]");
+    let next = payload;
+    for (const [from, to,] of Object.entries(rewrites)) {
+        if (!from)
+            continue;
+        const escaped = escapedRegExp(from);
+        const pattern = new RegExp(String
+            .raw `\b(FROM|JOIN)(\s+)(?:(["\`])${escaped}\3|(\[)${escaped}\]|${escaped})(?![A-Za-z0-9_.])`, "gi");
+        next = next.replace(pattern, (_match, keyword, space, quote, bracket) => {
+            if (quote) {
+                const escapedTo = escapeQuotedIdentifier(to, quote);
+                return `${keyword}${space}${quote}${escapedTo}${quote}`;
+            }
+            if (bracket) {
+                const escapedTo = escapeBracketIdentifier(to);
+                return `${keyword}${space}[${escapedTo}]`;
+            }
+            if (!bareIdentifierPattern.test(to)) {
+                throw new Error(`Unsafe SQL rewrite target for ${from}: ${to}`);
+            }
+            return `${keyword}${space}${to}`;
+        });
+    }
+    return next;
+}
+function rewritePayload(payload, rewrites, payloadTextRewrites = {}, recipeType) {
     if (payload === undefined
         || (Object.keys(rewrites).length === 0 && Object.keys(payloadTextRewrites).length === 0)) {
         return payload;
@@ -120,6 +157,9 @@ function rewritePayload(payload, rewrites, payloadTextRewrites = {}) {
         const escaped = escapedRegExp(from);
         next = next.replace(new RegExp(`\\bdataiku\\.(Dataset|Folder)\\(\\s*(['"])${escaped}\\2\\s*\\)`, "g"), (_match, kind, quote) => `dataiku.${kind}(${quote}${to}${quote})`);
     }
+    if (isSqlRecipeType(recipeType)) {
+        next = rewriteSqlTableReferences(next, rewrites);
+    }
     for (const [from, to,] of Object.entries(payloadTextRewrites)) {
         if (from.length > 0)
             next = next.split(from).join(to);
@@ -647,7 +687,7 @@ export class RecipesResource extends BaseResource {
         if (opts.payloadTextRewrites)
             Object.assign(payloadTextRewrites, opts.payloadTextRewrites);
         const recipe = cloneRecipeDefinition(source.recipe, opts.name, pk, graphRewrites);
-        const payload = rewritePayload(source.payload, payloadRewrites, payloadTextRewrites);
+        const payload = rewritePayload(source.payload, payloadRewrites, payloadTextRewrites, opts.recipeType ?? source.recipe.type);
         const copiedOutputDatasets = [];
         if (opts.copyOutputSettings) {
             for (const [from, to,] of Object.entries(outputRewrites)) {

package/dist/src/resources/scenarios.d.ts

@@ -31,6 +31,17 @@ export interface ScenarioUpdateResult extends ScenarioUpdatePreview {
     verified: true;
     mismatches: [];
 }
+export interface ScenarioScriptRunResult {
+    scenarioId: string;
+    runId: string;
+    outcome: string;
+    success: boolean;
+    elapsedMs: number;
+    pollCount: number;
+    output?: string;
+    log: string;
+    envName?: string;
+}
 export declare function normalizeScenarioUpdateData(data: Record<string, unknown>): {
     normalizedData: Record<string, unknown>;
     normalization: ScenarioUpdateNormalization[];
@@ -68,4 +79,17 @@ export declare class ScenariosResource extends BaseResource {
         timeoutMs?: number;
         projectKey?: string;
     }): Promise<ScenarioWaitResult>;
+    /**
+     * Run a one-off Python script in a throwaway custom-python scenario and return
+     * its outcome plus the captured run log. The scenario is deleted afterward
+     * unless `keepScenario` is set. This is the only DSS public-API path to execute
+     * ad-hoc code in a code env without a persisted recipe or notebook.
+     */
+    runScript(script: string, opts?: {
+        envName?: string;
+        projectKey?: string;
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+        keepScenario?: boolean;
+    }): Promise<ScenarioScriptRunResult>;
 }

package/dist/src/resources/scenarios.js

@@ -1,3 +1,4 @@
+import { randomUUID, } from "node:crypto";
 import { DataikuError, } from "../errors.js";
 import { ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioSummaryArraySchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
@@ -11,6 +12,76 @@ export const SCENARIO_CANONICAL_EDITABLE_FIELDS = [
     "active",
     "name",
 ];
+const CODE_RUN_OUTPUT_START = "<<<DSS_CODE_RUN_OUTPUT_b7e3a1>>>";
+const CODE_RUN_OUTPUT_END = "<<<DSS_CODE_RUN_OUTPUT_END_b7e3a1>>>";
+/**
+ * Wrap a user Python script so its stdout/stderr (and any traceback) are captured
+ * into a buffer and re-emitted between unique markers, isolated from DSS scenario
+ * wrapper noise. The script is base64-encoded to avoid quoting/escaping issues and
+ * exec'd as `__main__`. A failing script re-raises SystemExit(1) so the scenario
+ * outcome is FAILED while the captured traceback still lands between the markers.
+ */
+function buildCodeRunScript(script) {
+    const encoded = Buffer.from(script, "utf-8").toString("base64");
+    return [
+        "import base64 as _dku_b64, sys as _dku_sys, io as _dku_io, traceback as _dku_tb",
+        `_dku_src = _dku_b64.b64decode("${encoded}").decode("utf-8")`,
+        "_dku_buf = _dku_io.StringIO()",
+        "_dku_out, _dku_err = _dku_sys.stdout, _dku_sys.stderr",
+        "_dku_sys.stdout = _dku_sys.stderr = _dku_buf",
+        "_dku_code = 0",
+        "try:",
+        '\texec(compile(_dku_src, "<dss_code_run>", "exec"), {"__name__": "__main__"})',
+        "except SystemExit as _dku_e:",
+        "\t_dku_code = _dku_e.code if isinstance(_dku_e.code, int) else (0 if _dku_e.code is None else 1)",
+        "except BaseException:",
+        "\t_dku_code = 1",
+        "\t_dku_tb.print_exc()",
+        "finally:",
+        "\t_dku_sys.stdout, _dku_sys.stderr = _dku_out, _dku_err",
+        `\t_dku_out.write("${CODE_RUN_OUTPUT_START}\\n")`,
+        "\t_dku_out.write(_dku_buf.getvalue())",
+        `\t_dku_out.write("\\n${CODE_RUN_OUTPUT_END}\\n")`,
+        "\t_dku_out.flush()",
+        "if _dku_code:",
+        "\traise SystemExit(_dku_code)",
+        "",
+    ].join("\n");
+}
+/**
+ * Pull the script's own stdout/stderr back out of the full DSS run log by slicing
+ * the `[process]` lines between the markers emitted by {@link buildCodeRunScript}.
+ * Returns undefined if the markers are absent (e.g. the harness never ran), in which
+ * case callers should fall back to the full log.
+ */
+function extractCodeRunOutput(log) {
+    const messageRe = /^\[[^\]]*\] \[[^\]]*\] \[[^\]]*\] \[process\]  - (.*)$/;
+    const contents = [];
+    for (const rawLine of log.split("\n")) {
+        const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+        const match = messageRe.exec(line);
+        if (match)
+            contents.push(match[1] ?? "");
+    }
+    // First start + last end, so a script that prints a marker string stays body content.
+    const start = contents.indexOf(CODE_RUN_OUTPUT_START);
+    if (start < 0)
+        return undefined;
+    let end = -1;
+    for (let i = contents.length - 1; i > start; i--) {
+        if (contents[i] === CODE_RUN_OUTPUT_END) {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0)
+        return undefined;
+    const body = contents.slice(start + 1, end);
+    // Drop only the single trailing separator the harness writes before the end marker.
+    if (body.length > 0 && body[body.length - 1] === "")
+        body.pop();
+    return body.join("\n");
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -260,4 +331,94 @@ export class ScenariosResource extends BaseResource {
             await new Promise((r) => setTimeout(r, Math.min(nextDelayMs, timeout - elapsedMs)));
         }
     }
+    /**
+     * Run a one-off Python script in a throwaway custom-python scenario and return
+     * its outcome plus the captured run log. The scenario is deleted afterward
+     * unless `keepScenario` is set. This is the only DSS public-API path to execute
+     * ad-hoc code in a code env without a persisted recipe or notebook.
+     */
+    async runScript(script, opts) {
+        const pk = this.resolveProjectKey(opts?.projectKey);
+        const pkEnc = this.enc(opts?.projectKey);
+        const scenarioId = `dss_cli_code_run_${Date.now()}_${randomUUID().replace(/-/g, "")}`;
+        const base = `/public/api/projects/${pkEnc}/scenarios/${encodeURIComponent(scenarioId)}`;
+        const envSelection = opts?.envName
+            ? { envMode: "EXPLICIT_ENV", envName: opts.envName, }
+            : { envMode: "INHERIT", };
+        const startedAt = Date.now();
+        const baseIntervalMs = Math.max(1, opts?.pollIntervalMs ?? 2_000);
+        const adaptivePolling = opts?.pollIntervalMs === undefined;
+        const timeout = Math.max(baseIntervalMs, opts?.timeoutMs ?? 120_000);
+        try {
+            await this.client.post(`/public/api/projects/${pkEnc}/scenarios/`, {
+                id: scenarioId,
+                name: `dss code run (${scenarioId})`,
+                projectKey: pk,
+                type: "custom_python",
+                params: { envSelection, },
+            });
+            await this.client.putVoid(`${base}/payload`, { script: buildCodeRunScript(script), extension: "py", });
+            const trigger = await this.client.post(`${base}/run/`, {});
+            const triggerObj = trigger.trigger;
+            const triggerId = triggerObj?.id ?? "manual";
+            const triggerRunId = String(trigger.runId ?? "");
+            if (!triggerRunId) {
+                throw new DataikuError(500, "Scenario run not started", `Scenario "${scenarioId}" run trigger returned no run id; cannot track the run.`);
+            }
+            const trigQuery = `triggerId=${encodeURIComponent(triggerId)}&triggerRunId=${encodeURIComponent(triggerRunId)}`;
+            let runId = "";
+            let outcome = "UNKNOWN";
+            let pollCount = 0;
+            while (true) {
+                if (Date.now() - startedAt >= timeout) {
+                    outcome = "TIMEOUT";
+                    break;
+                }
+                pollCount += 1;
+                const run = await this.client.get(`${base}/get-run-for-trigger?${trigQuery}`);
+                const scenarioRun = run.scenarioRun;
+                if (scenarioRun) {
+                    runId = scenarioRun.runId ?? runId;
+                    const result = scenarioRun.result;
+                    const finished = result?.outcome;
+                    if (finished) {
+                        outcome = finished;
+                        break;
+                    }
+                }
+                const nextDelayMs = computeNextPollDelayMs({
+                    pollCount,
+                    baseIntervalMs,
+                    adaptiveEnabled: adaptivePolling,
+                });
+                await new Promise((r) => setTimeout(r, Math.min(nextDelayMs, Math.max(1, timeout - (Date.now() - startedAt)))));
+            }
+            let log = "";
+            if (runId && outcome !== "TIMEOUT") {
+                log = await this.client.getText(`${base}/${encodeURIComponent(runId)}/log`);
+            }
+            const output = extractCodeRunOutput(log);
+            return {
+                scenarioId,
+                runId,
+                outcome,
+                success: outcome === "SUCCESS",
+                elapsedMs: Date.now() - startedAt,
+                pollCount,
+                output,
+                log,
+                ...(opts?.envName ? { envName: opts.envName, } : {}),
+            };
+        }
+        finally {
+            if (opts?.keepScenario !== true) {
+                try {
+                    await this.client.del(base);
+                }
+                catch {
+                    // Best-effort cleanup of the throwaway scenario.
+                }
+            }
+        }
+    }
 }

package/dist/src/schemas.d.ts

@@ -3,5 +3,5 @@
  * The types package (packages/types/) owns the TypeBox schema definitions.
  * SDK consumers get everything through this re-export.
  */
-export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";
-export type { BuildMode, CodeEnvActionResult, CodeEnvCreateOptions, CodeEnvDetails, CodeEnvPackageList, CodeEnvSetPackagesOptions, CodeEnvSummary, CodeEnvUpdatePackagesOptions, CodeEnvUsage, CodeEnvWaitOptions, ConnectionSummary, DashboardDetails, DashboardSummary, DataQualityComputeResult, DataQualityProjectStatus, DataQualityRule, DataQualityRuleResult, DataQualityRules, DataQualityStatus, DataQualityStatusByPartition, DataQualityTimeline, DataQualityTimelineEntry, DatasetCreateOptions, DatasetDetails, DatasetSchema, DatasetSummary, FlowMapOptions, FlowZone, FlowZoneCreateOptions, FlowZoneItem, FlowZoneObjectType, FlowZoneUpdateOptions, FolderCreateOptions, FolderDetails, FolderItem, FolderSummary, FutureState, FutureWaitResult, InsightDetails, InsightSummary, JobSummary, JobWaitResult, JupyterCell, JupyterNotebookContent, JupyterNotebookSummary, NotebookSession, ProjectDetails, ProjectMetadata, ProjectSummary, ProjectVariables, RecipeCreateOptions, RecipeCreateResult, RecipeDetails, RecipeSummary, SafeParseResult, ScenarioDetails, ScenarioStatus, ScenarioSummary, ScenarioWaitResult, SqlNotebookCell, SqlNotebookContent, SqlNotebookSummary, SqlQueryResponse, SqlQueryResult, SqlQuerySchema, WikiArticleData, WikiArticleMetadata, WikiSettings, WikiTaxonomyNode, } from "../packages/types/src/index.js";
+export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";
+export type { BuildMode, CodeEnvActionResult, CodeEnvCreateOptions, CodeEnvDetails, CodeEnvPackageList, CodeEnvSetPackagesOptions, CodeEnvSummary, CodeEnvUpdatePackagesOptions, CodeEnvUsage, CodeEnvWaitOptions, ConnectionSummary, DashboardDetails, DashboardSummary, DataQualityComputeResult, DataQualityProjectStatus, DataQualityRule, DataQualityRuleResult, DataQualityRules, DataQualityStatus, DataQualityStatusByPartition, DataQualityTimeline, DataQualityTimelineEntry, DatasetCreateOptions, DatasetDetails, DatasetSchema, DatasetSummary, FlowMapOptions, FlowZone, FlowZoneCreateOptions, FlowZoneItem, FlowZoneObjectType, FlowZonePosition, FlowZoneUpdateOptions, FolderCreateOptions, FolderDetails, FolderItem, FolderSummary, FutureState, FutureWaitResult, InsightDetails, InsightSummary, JobSummary, JobWaitResult, JupyterCell, JupyterNotebookContent, JupyterNotebookSummary, NotebookSession, ProjectDetails, ProjectMetadata, ProjectSummary, ProjectVariables, RecipeCreateOptions, RecipeCreateResult, RecipeDetails, RecipeSummary, SafeParseResult, ScenarioDetails, ScenarioStatus, ScenarioSummary, ScenarioWaitResult, SqlNotebookCell, SqlNotebookContent, SqlNotebookSummary, SqlQueryResponse, SqlQueryResult, SqlQuerySchema, WikiArticleData, WikiArticleMetadata, WikiSettings, WikiTaxonomyNode, } from "../packages/types/src/index.js";

package/dist/src/schemas.js

@@ -3,4 +3,4 @@
  * The types package (packages/types/) owns the TypeBox schema definitions.
  * SDK consumers get everything through this re-export.
  */
-export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";
+export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";

package/dist/src/skill.d.ts

@@ -31,7 +31,12 @@ export declare function findWorkspaceRoot(startDir: string): string;
 export interface InstallResult {
     agent: string;
     path: string;
+    via: DetectedAgent["via"];
 }
+export declare function planSkillInstalls(agents: DetectedAgent[], opts: {
+    global: boolean;
+    cwd: string;
+}): InstallResult[];
 export declare function installSkill(agents: DetectedAgent[], opts: {
     global: boolean;
     cwd: string;

package/dist/src/skill.js

@@ -2,124 +2,118 @@ import { execFileSync, } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync, } from "node:fs";
 import { homedir, } from "node:os";
 import { dirname, join, } from "node:path";
-const SKILL_BODY = `# Dataiku DSS CLI
+const SKILL_BODY = `# Dataiku DSS agent CLI
 
-The \`dss\` CLI (npm: dataiku-sdk) manages Dataiku DSS resources from the terminal.
+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 ...\`.
+\`--no-env-file\` disables Bun's automatic preloading only; the CLI still applies its documented \`.env\` handling unless \`DATAIKU_DISABLE_ENV=1\` is set.
 
-## When to use
+## Contract
 
-- Query, create, or modify DSS projects, datasets, recipes, jobs, or scenarios.
-- Build datasets or run scenarios and wait for completion.
-- Download or upload recipe code, dataset data, or managed folder files.
-- Run SQL queries against DSS connections.
-- Inspect project flows, job logs, or dataset schemas.
+- Success writes exactly one JSON result to stdout.
+- Failure writes exactly one JSON error envelope to stderr with \`ok:false\`, \`error\`, \`code\`, and \`exitCode\`.
+- \`--verbose\` may add HTTP trace lines to stderr.
+- No prompts, help screens, tables, banners, or prose output are part of the contract.
+- Exit codes: 0 success, 1 usage/configuration error, 2 DSS or internal error, 3 transient/retryable DSS error, 4 completed command with failed long-running DSS work.
+- \`--raw\` is the only stdout escape hatch: recipe payload commands emit raw bytes to stdout unless \`--output PATH\` is also set; with \`--output\`, stdout is the JSON string equal to \`PATH\` and the file receives exact raw bytes.
+- \`--fields a,b,c\` projects those fields from object or array-of-objects results; dotted paths (\`a.b.c\`) drill into nested objects, and missing fields become \`null\`; string and scalar results pass through unchanged.
 
-## Installation
-
-Requires [Bun](https://bun.sh) runtime.
+## Discover commands
 
 \`\`\`bash
-bun add -g dataiku-sdk              # global install \u2014 provides the \`dss\` command
+dss commands run
 \`\`\`
 
-Or run without installing:
-
-\`\`\`bash
-bunx dataiku-sdk <command>           # e.g. bunx dataiku-sdk auth login
-\`\`\`
+The registry is the canonical schema for resources, actions, flags, positional arguments, side effects, auth requirements, output shape, idempotency, dry-run support, payload schemas, cleanup hints, and exit codes. Use it before choosing command syntax.
+Credential lookup order is flags first, then \`DATAIKU_*\` environment variables, then saved credentials.
+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 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.
 
 ## Authentication
 
-\`\`\`bash
-dss auth login                       # interactive: prompts for URL, API key, project key
-dss auth login --url https://dss.example.com --api-key YOUR_KEY
-dss auth status                      # verify connection
-\`\`\`
-
-Credentials are saved to \`~/.config/dataiku/credentials.json\`. Alternatively set environment variables:
+Prefer environment variables for ephemeral agent runs:
 
 \`\`\`bash
 export DATAIKU_URL=https://dss.example.com
 export DATAIKU_API_KEY=your-api-key
-export DATAIKU_PROJECT_KEY=MYPROJ    # optional default project
+export DATAIKU_PROJECT_KEY=MYPROJ
 \`\`\`
 
-## Workflows
-
-### Inspect a project
+To persist credentials for later invocations:
 
 \`\`\`bash
-dss project list                              # find the project key
-dss dataset list --project-key MYPROJ         # list its datasets
-dss dataset preview orders --max-rows 10      # peek at data
-dss dataset schema orders                     # inspect columns
+dss auth login --url https://dss.example.com --api-key YOUR_KEY --project-key MYPROJ
 \`\`\`
 
-### Edit recipe code
+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.
+\`auth login\` validates by listing accessible projects before saving credentials, so the API key must be allowed to call DSS project-list APIs.
 
-\`\`\`bash
-dss recipe download-code my-recipe -o code.py # download
-# ... edit code.py ...
-dss recipe diff my-recipe --file code.py      # review changes
-dss recipe set-payload my-recipe --file code.py  # upload
-\`\`\`
+TLS flags: \`--insecure\` disables certificate verification; \`--ca-cert PATH\` adds a PEM CA bundle. Environment equivalents: \`NODE_TLS_REJECT_UNAUTHORIZED\`, \`NODE_EXTRA_CA_CERTS\`.
 
-### Build and monitor
+## Common workflows
 
 \`\`\`bash
-dss job build-and-wait my-dataset --include-logs  # build + wait + stream logs
-dss job list                                      # recent jobs
-dss job log <job-id>                               # full log output
+dss version
+dss project list
+dss doctor --fast
+dss dataset list --project-key MYPROJ
+dss dataset list --project-key MYPROJ --fields name,type
+dss dataset preview orders --max-rows 10 --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 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 scenario run daily_build --project-key MYPROJ
+dss sql query --connection analytics --sql "select 1" --project-key MYPROJ
+dss batch --data-file steps.json
 \`\`\`
+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":"..."}\`.
 
-### Run a scenario
+## Confirming mutations
 
-\`\`\`bash
-dss scenario run my-scenario
-dss scenario status my-scenario               # check if finished
-\`\`\`
+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.
 
-## Command reference
+- 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.
+- 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.
 
-\`\`\`
-dss <resource> <action> [args...] [--flags]
+## Platform & debugging notes
 
-Resources: project, dataset, recipe, job, scenario, folder, notebook,
-           variable, code-env, connection, sql, auth, install-skill
-\`\`\`
+- Pass code and SQL via \`--file\`/\`--sql-file\`, not inline: shells (especially PowerShell) mangle quotes, \`$\`, and newlines in multi-line snippets.
+- On a non-UTF-8 console (e.g. Windows cp1252), don't print non-ASCII results; write them to a UTF-8 file and read that, or use \`--output PATH\`.
+- Build failures: \`dss job log <id> --errors-only\` surfaces just error/traceback lines, and \`--output PATH\` saves the full log to a file. Logs are one long line with JVM noise; the \`Error in Python process: At line <N>\` marker maps \`<N>\` straight to your recipe payload's source line.
+- Schema changes aren't automatic: after changing a recipe's output columns run \`dss dataset refresh-schema\` (or rebuild) before downstream reads, and \`dss dataset validate-build\` to catch file-backed misconfig before launching a build.
+- \`dss dataset download\` is capped (default 100k rows) and returns \`{ path, rows, truncated, limit }\`: check \`truncated\` and raise \`--limit N\` when you need more — treat it as a sample, not a guaranteed full export. For very large tables, aggregate in SQL or read inside a recipe instead.
 
-Use \`dss <resource> --help\` to see all actions and flags for any resource.
+## Error envelope
 
-## Key flags
+Parse stderr as JSON when exit code is non-zero:
 
+\`\`\`json
+{
+  "ok": false,
+  "error": "Missing API key.",
+  "code": "usage_error",
+  "category": "usage",
+  "exitCode": 1,
+  "resource": "dataset",
+  "action": "list"
+}
 \`\`\`
--f, --format FORMAT    json (default) | tsv | table | quiet
--o, --output PATH      write output to file instead of stdout
--v, --verbose          log HTTP requests to stderr
-    --project-key KEY  override default project for any command
-    --timeout MS       request timeout (default: 30000)
-    --insecure         disable TLS certificate verification
-    --ca-cert PATH     trust an extra PEM CA bundle
-    --stdin            read command input from stdin (JSON or SQL, depending on command)
-\`\`\`
-
-## Gotchas
 
-- **Most commands need a project key.** Set it once via \`dss auth login\` or \`DATAIKU_PROJECT_KEY\` to avoid passing \`--project-key\` on every call.
-- **Output is JSON by default.** Use \`-f table\` when showing results to a user; use \`-f tsv\` when piping to scripts.
-- **\`dss job build\` returns immediately.** Use \`dss job build-and-wait\` to block until the build finishes. Add \`--include-logs\` to stream log output.
-- **Folder commands accept names or IDs.** If a folder name contains spaces, quote it. The CLI resolves names to IDs automatically.
-- **Recipe set-payload overwrites the entire payload.** Always download first, edit, diff, then upload.
-- **Transient errors exit code 3, API errors exit code 2, usage errors exit code 1.** Check exit codes to distinguish retriable failures.
+Use \`code\`, \`category\`, \`exitCode\`, \`retryable\`, \`status\`, and \`details\` for recovery logic. Do not scrape message text when a structured field is available.
 `;
 const SKILL_FRONTMATTER = `---
 name: dataiku-dss
 description: >-
-  Interact with Dataiku DSS from the command line \u2014 list projects, query datasets,
-  download and upload recipe code, build datasets, run scenarios, and manage jobs.
-  Use when the user wants to work with Dataiku DSS resources, inspect a DSS project,
-  modify recipes, trigger builds, check job logs, or run SQL against DSS connections,
-  even if they don't explicitly mention the dss CLI.
+  Agent-only JSON CLI for Dataiku DSS. Use to inspect or mutate DSS projects,
+  datasets, recipes, jobs, scenarios, folders, notebooks, SQL, variables,
+  code envs, and connections. Discover the full machine-readable surface with
+  dss commands run.
 ---
 
 `;
@@ -227,30 +221,29 @@ export function findWorkspaceRoot(startDir) {
     }
     return startDir;
 }
-export function installSkill(agents, opts) {
+export function planSkillInstalls(agents, opts) {
     const home = homedir();
     const results = [];
-    for (const { id, def, } of agents) {
-        let dir;
-        if (opts.global) {
-            const globalDir = def.globalPath(home);
-            if (!globalDir) {
-                process.stderr.write(`  ${def.name}: skipped (no global path available)\n`);
-                continue;
-            }
-            dir = globalDir;
-        }
-        else {
-            if (!def.projectPath) {
-                process.stderr.write(`  ${def.name}: skipped (no project path available)\n`);
-                continue;
-            }
-            dir = join(opts.cwd, def.projectPath);
-        }
-        mkdirSync(dir, { recursive: true, });
-        const filePath = join(dir, def.filename);
-        writeFileSync(filePath, def.content(), "utf-8");
-        results.push({ agent: id, path: filePath, });
+    for (const { id, def, via, } of agents) {
+        const dir = opts.global
+            ? def.globalPath(home)
+            : def.projectPath
+                ? join(opts.cwd, def.projectPath)
+                : undefined;
+        if (!dir)
+            continue;
+        results.push({ agent: id, path: join(dir, def.filename), via, });
+    }
+    return results;
+}
+export function installSkill(agents, opts) {
+    const results = planSkillInstalls(agents, opts);
+    for (const result of results) {
+        const def = AGENTS[result.agent];
+        if (!def)
+            continue;
+        mkdirSync(dirname(result.path), { recursive: true, });
+        writeFileSync(result.path, def.content(), "utf-8");
     }
     return results;
 }