dataiku-sdk 3.5.0 → 3.6.1

package/README.md

@@ -267,7 +267,7 @@ DSS_TOKENIZER_MODULE=/absolute/path/to/oh-my-pi/packages/natives/native/index.js
 
 When configured, the native module also accelerates ordinary OpenAI token measurements after parity checks against the pinned JavaScript model. The JS fingerprint and independent cross-model reference checks remain authoritative; reserved special-token validation is preserved. Without this variable, measurements use JavaScript and only the native cross-model case is skipped. A configured missing/incompatible module fails instead of silently falling back. The cross-model gate permits 10% growth over recorded text baselines. Claude counts use ctok reconstructions, not an official tokenizer; counts exclude provider framing. No native dependency is added to the CLI.
 
-For a known resource, `dss agent contract --fields commands.actions.dataset` lists action names in **64 tokens**, versus **1,575** for the global index. For known writes, fetch the full action entry directly once: `dataset.create` costs **1,059 tokens**, versus **1,415** for compact discovery followed by the required full entry. Use compact `usage,description,flags,examples` projections for reads when those fields suffice. This is selective disclosure, not lossless compression. Scoped discovery constructs only requested action entries and materializes schemas only when requested; action-name indexes avoid payload schemas, while full registry exports and recovery hints retain their existing content. Metadata-only paths defer SDK runtime/schema imports.
+For a known resource, `dss agent contract --fields commands.actions.dataset` lists only its action names, far smaller than the global index; for known writes, fetch the full action entry directly once rather than compact discovery followed by the full entry. `bun run test:tokens` pins the current figures. Use compact `usage,description,flags,examples` projections for reads when those fields suffice. This is selective disclosure, not lossless compression. Scoped discovery constructs only requested action entries and materializes schemas only when requested; action-name indexes avoid payload schemas, while full registry exports and recovery hints retain their existing content. Metadata-only paths defer SDK runtime/schema imports.
 
 Boolean flags accept bare flags or explicit `=true`/`=false` values, including aliases. Invalid boolean values fail before dispatch. Direct, batch, and local commands share execution-mode resolution; `--plan --dry-run` returns a plan with `plannedAndDryRun:true` when both modes are supported. Unreadable JSON/text payload files produce `validation_failed` usage errors (exit 1) with the flag, path, and filesystem cause.
 

package/bin/dss.js

@@ -4,6 +4,7 @@
 // disabled; `bunx --bun` enters Bun's Node-compatibility mode, which disables
 // that loading before this module runs.
 import { spawnSync, } from "node:child_process";
+import { readFileSync, } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath, pathToFileURL, } from "node:url";
 
@@ -19,23 +20,44 @@ const bunNodeCompatibilityMode = runningUnderBun
 	);
 const envFileAutoloadDisabled = process.execArgv.includes("--no-env-file",)
 	|| bunNodeCompatibilityMode;
+// The one source of the minimum is package.json engines.bun (">=X.Y.Z").
+const MINIMUM_BUN = JSON.parse(
+	readFileSync(fileURLToPath(new URL("../package.json", import.meta.url,),), "utf-8",),
+).engines.bun.replace(/^>=/, "",);
+
+/** Whether dotted version `actual` is >= `minimum` (numeric per part). */
+function versionAtLeast(actual, minimum,) {
+	// Compare the release part only: canary builds print e.g. 1.4.3-canary.12+abc.
+	const a = actual.split(/[-+]/,)[0].split(".",).map(Number,);
+	const m = minimum.split(".",).map(Number,);
+	for (let i = 0; i < m.length; i++) {
+		if ((a[i] ?? 0) !== m[i]) return (a[i] ?? 0) > m[i];
+	}
+	return true;
+}
 
 if (!runningUnderBun) {
-	const result = spawnSync(
-		"bun",
-		["--no-env-file", fileURLToPath(import.meta.url,), ...process.argv.slice(2,),],
-		{ stdio: "inherit", env: process.env, },
-	);
+	// Check before spawning: an old Bun may reject --no-env-file during argument
+	// parsing, before any launcher code could report a JSON error.
+	const probe = spawnSync("bun", ["--version",], { encoding: "utf-8", },);
+	const found = probe.error ? undefined : probe.stdout.trim();
+	const result = found !== undefined && versionAtLeast(found, MINIMUM_BUN,)
+		? spawnSync(
+			"bun",
+			["--no-env-file", fileURLToPath(import.meta.url,), ...process.argv.slice(2,),],
+			{ stdio: "inherit", env: process.env, },
+		)
+		: { error: new Error(found ? `Bun ${found} is older than ${MINIMUM_BUN}.` : "bun not found",), };
 	if (result.error) {
 		process.stdout.write(`${
 			JSON.stringify({
 				type: "error",
 				ok: false,
-				error: "Unable to start the required Bun runtime.",
+				error: `Unable to start the required Bun runtime: ${result.error.message}`,
 				code: "internal_error",
 				category: "internal",
 				exitCode: 2,
-				hint: "Install Bun >= 1.4.0 and ensure `bun` is on PATH.",
+				hint: `Install Bun >= ${MINIMUM_BUN} and ensure \`bun\` is on PATH.`,
 			},)
 		}\n`,);
 		process.exitCode = 2;
@@ -44,6 +66,19 @@ if (!runningUnderBun) {
 	} else {
 		process.exitCode = result.status ?? 1;
 	}
+} else if (!Bun.semver.satisfies(Bun.version, `>=${MINIMUM_BUN}`,)) {
+	process.stdout.write(`${
+		JSON.stringify({
+			type: "error",
+			ok: false,
+			error: `Bun ${Bun.version} is older than the required ${MINIMUM_BUN}.`,
+			code: "internal_error",
+			category: "internal",
+			exitCode: 2,
+			hint: `Upgrade Bun to >= ${MINIMUM_BUN} (bun upgrade).`,
+		},)
+	}\n`,);
+	process.exitCode = 2;
 } else if (!envFileAutoloadDisabled) {
 	process.stdout.write(`${
 		JSON.stringify({
@@ -61,7 +96,11 @@ if (!runningUnderBun) {
 	const here = import.meta.dir;
 	const distCliPath = path.resolve(here, "../dist/src/cli.js",);
 	const sourceCliPath = path.resolve(here, "../src/cli.ts",);
-	const usesDistCli = await Bun.file(distCliPath,).exists();
+	// A source checkout always runs its source, like bin/dss; a leftover dist/
+	// would otherwise silently shadow every edit. The published package ships
+	// no src/, so installs run dist.
+	const usesDistCli = !(await Bun.file(sourceCliPath,).exists())
+		&& await Bun.file(distCliPath,).exists();
 	const cliPath = usesDistCli ? distCliPath : sourceCliPath;
 
 	// Published dist carries dist/build-metadata.json with the revision it was
@@ -69,7 +108,6 @@ if (!runningUnderBun) {
 	// build revision; only a full lowercase hexadecimal revision is accepted, so an
 	// inherited or corrupt variable never stands in for packaged metadata.
 	if (usesDistCli) {
-		process.env.DSS_LOAD_SOURCE = "dist";
 		delete process.env.DSS_BUILD_REVISION;
 		try {
 			const metadata = await Bun.file(path.resolve(here, "../dist/build-metadata.json",),).json();
@@ -80,6 +118,9 @@ if (!runningUnderBun) {
 		} catch {
 			// Dist without build metadata: provenance still reports dist source.
 		}
+	} else {
+		// Only a dist run may carry a build revision; never trust an inherited one.
+		delete process.env.DSS_BUILD_REVISION;
 	}
 
 	// Same process, same argv: the CLI sees process.argv.slice(2) exactly as before.

package/dist/build-metadata.json

@@ -1 +1 @@
-{"format":1,"buildRevision":"cb8058354cc9c7a71d47d5dc43fded12e3bb4b8c"}
+{"format":1,"buildRevision":"dae7b426ec392ff4a62bcf07fab199e02080a0f6"}

package/dist/src/cli/coerce.d.ts

@@ -10,7 +10,6 @@ export declare function normalizeLineEndings(value: string): string;
 export declare function splitCsvFlag(v: string | boolean | undefined): string[];
 export declare function recipeInputDatasetsFromFlags(flags: Record<string, string | boolean>): string[] | undefined;
 export declare function rewritePairsFromFlags(flags: Record<string, string | boolean>, flagName: string): Record<string, string>;
-export declare function plainRecord(value: unknown): Record<string, unknown> | undefined;
 export declare function requiredStringFlag(flags: Record<string, string | boolean>, name: string, usage: string): string;
 export declare function optionalStringField(record: Record<string, unknown>, keys: string[]): string | undefined;
 export declare function requiredStringArray(value: unknown, source: string): string[];

package/dist/src/cli/coerce.js

@@ -85,11 +85,6 @@ export function rewritePairsFromFlags(flags, flagName) {
     }
     return rewrites;
 }
-export function plainRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : undefined;
-}
 export function requiredStringFlag(flags, name, usage) {
     const value = flags[name];
     if (typeof value !== "string" || value.trim().length === 0) {

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

@@ -1,6 +1,7 @@
 import { ClientValidationError, DataikuError, } from "../../errors.js";
 import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
-import { jsonInput, num, parseBooleanOption, plainRecord, requiredJsonInput, requiredStringFlag, stringField, } from "../coerce.js";
+import { asRecord, } from "../../utils/records.js";
+import { jsonInput, num, parseBooleanOption, requiredJsonInput, requiredStringFlag, stringField, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { appPermissionsHash, appPermissionsVerificationError, assertAppPermissionsSnapshotBinding, buildAppPermissionsSnapshot, diffAppPermissions, readAppPermissionsSnapshot, writeAppPermissionsSnapshot, } from "../helpers/app-permissions.js";
 import { createSuccessorInstance, futureTargetIdentity, generatedInstanceKey, isDefinitiveRejection, preflightSuccessorInstance, requireAbsentProjectTarget, safeErrorSummary, verifyAppInstance, VISUAL_UI_GATE, } from "../helpers/app-successor.js";
@@ -180,7 +181,7 @@ export const appCommands = withUsage("app", {
                     ...safeErrorSummary(error),
                 };
             }
-            const instance = plainRecord(created);
+            const instance = asRecord(created);
             if (!instance) {
                 return {
                     success: false,

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

@@ -1,4 +1,5 @@
 import { deepMerge, } from "../../utils/deep-merge.js";
+import { isRecord, } from "../../utils/records.js";
 import { compareStrings, stableHash, } from "../../utils/stable-hash.js";
 import { jsonInput, num, schemaColumnsInput, unknownJsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
@@ -8,9 +9,6 @@ import { enqueueCliWarning, readIfExists, skipResult, } from "../output.js";
 import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 const MAX_SCHEMA_DIFFERENCES = 50;
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function appendSchemaPath(parent, key) {
     return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
         ? (parent ? `${parent}.${key}` : key)
@@ -21,7 +19,7 @@ function collectSchemaDifferences(expected, actual, path, acc) {
     // subtrees (any key order) match exactly and are never descended into.
     if (stableHash(expected) === stableHash(actual))
         return;
-    if (isPlainObject(expected) && isPlainObject(actual)) {
+    if (isRecord(expected) && isRecord(actual)) {
         const keys = [...new Set([...Object.keys(expected), ...Object.keys(actual),]),].sort(compareStrings);
         for (const key of keys) {
             const nextPath = appendSchemaPath(path, key);

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

@@ -1,6 +1,7 @@
 import { mkdir, writeFile, } from "node:fs/promises";
 import { dirname, resolve, } from "node:path";
-import { jobBuildTargetTypeFromFlags, jobLogFilterFromFlag, maxLogLinesFromFlags, num, plainRecord, } from "../coerce.js";
+import { asRecord, } from "../../utils/records.js";
+import { jobBuildTargetTypeFromFlags, jobLogFilterFromFlag, maxLogLinesFromFlags, num, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, } from "../output.js";
 import { commandUsage, withUsage, } from "../syntax.js";
@@ -11,7 +12,7 @@ import { requireArgs, UsageError, } from "../usage.js";
 function nestedValue(value, path) {
     let current = value;
     for (const key of path) {
-        const record = plainRecord(current);
+        const record = asRecord(current);
         if (!record)
             return undefined;
         current = record[key];
@@ -95,7 +96,7 @@ function collectWarningCounts(value, inActivity, counts) {
             collectWarningCounts(item, inActivity, counts);
         return;
     }
-    const record = plainRecord(value);
+    const record = asRecord(value);
     if (!record)
         return;
     for (const [key, item,] of Object.entries(record)) {

package/dist/src/cli/contract.js

@@ -734,7 +734,7 @@ function inferSideEffect(resource, action) {
     // LLM Mesh completions/embeddings invoke the LLM provider (cost-bearing,
     // arbitrary-prompt execution); the verb shapes match no mutating pattern
     // and would fall through to read, wrongly rejecting --plan. Knowledge-bank
-    // search stays a READ per Main's preservation directive.
+    // search stays read: it only queries an existing index.
     if (resource === "llm" && (action === "completions" || action === "embeddings")) {
         return "write";
     }

package/dist/src/cli/env.js

@@ -56,7 +56,8 @@ export function loadEnvFile() {
                     continue;
                 const key = trimmed.slice(0, eq).trim();
                 const val = trimmed.slice(eq + 1).trim().replace(/^['"]|['"]$/g, "");
-                if (isAllowedEnvKey(key) && !process.env[key]) {
+                // A variable set in the environment, even to "", wins over .env ("" clears it).
+                if (isAllowedEnvKey(key) && process.env[key] === undefined) {
                     process.env[key] = val;
                     (index === 0 ? projectEnvVars : installEnvVars).add(key);
                 }

package/dist/src/cli/flags.d.ts

@@ -1,3 +1,4 @@
+/** Planning wins dispatch; dryRun remains set for combined plan metadata. */
 export declare function executionMode(flags: Record<string, string | boolean>): {
     readonly plan: boolean;
     readonly dryRun: boolean;

package/dist/src/cli/flags.js

@@ -1,16 +1,11 @@
 import { parseBooleanOption, } from "./coerce.js";
 import { unsupportedHelpFlag, UsageError, } from "./usage.js";
 /** Planning wins dispatch; dryRun remains set for combined plan metadata. */
-const EXECUTION_MODES = [
-    Object.freeze({ plan: false, dryRun: false, }),
-    Object.freeze({ plan: false, dryRun: true, }),
-    Object.freeze({ plan: true, dryRun: false, }),
-    Object.freeze({ plan: true, dryRun: true, }),
-];
 export function executionMode(flags) {
-    const plan = parseBooleanOption(flags["plan"], "--plan") ?? false;
-    const dryRun = parseBooleanOption(flags["dry-run"], "--dry-run") ?? false;
-    return EXECUTION_MODES[(plan ? 2 : 0) + (dryRun ? 1 : 0)];
+    return {
+        plan: parseBooleanOption(flags["plan"], "--plan") ?? false,
+        dryRun: parseBooleanOption(flags["dry-run"], "--dry-run") ?? false,
+    };
 }
 export const BOOLEAN_FLAGS = new Set([
     "verbose",

package/dist/src/cli/helpers/app-permissions.js

@@ -1,8 +1,9 @@
 import * as fs from "node:fs";
 import { ClientValidationError, } from "../../errors.js";
 import { canonicalDssUrl, } from "../../utils/dss-url.js";
+import { asRecord, } from "../../utils/records.js";
 import { compareStrings, } from "../../utils/stable-hash.js";
-import { parseJsonObject, plainRecord, stableHash, stableJson, } from "../coerce.js";
+import { parseJsonObject, stableHash, stableJson, } from "../coerce.js";
 import { UsageError, } from "../usage.js";
 /**
  * Version 3 binds every snapshot to both its DSS server and the concrete project
@@ -124,7 +125,7 @@ export function parseAppPermissionsSnapshot(text, source) {
     const capturedAt = requiredSnapshotString(record, "capturedAt", source);
     const hash = requiredSnapshotString(record, "hash", source);
     const permissionsHash = requiredSnapshotString(record, "permissionsHash", source);
-    const permissions = plainRecord(record["permissions"]);
+    const permissions = asRecord(record["permissions"]);
     if (!permissions) {
         throw new UsageError(`${source} is not an app permissions snapshot: "permissions" must be a JSON object.`, "validation_failed");
     }
@@ -209,8 +210,8 @@ function pushDifference(out, path, backup, current) {
 function collectDifferences(path, backup, current, out) {
     if (stableJson(backup) === stableJson(current))
         return;
-    const backupRecord = plainRecord(backup);
-    const currentRecord = plainRecord(current);
+    const backupRecord = asRecord(backup);
+    const currentRecord = asRecord(current);
     if (backupRecord && currentRecord) {
         const keys = [...new Set([...Object.keys(backupRecord), ...Object.keys(currentRecord),]),]
             .sort(compareStrings);

package/dist/src/cli/helpers/flow-zone.js

@@ -1,6 +1,7 @@
 import { readFileSync, } from "node:fs";
+import { asRecord, } from "../../utils/records.js";
 import { compareStrings, } from "../../utils/stable-hash.js";
-import { finiteNumberField, jsonInput, optionalStringField, parseJsonObject, plainRecord, requiredStringArray, splitCsvFlag, } from "../coerce.js";
+import { finiteNumberField, jsonInput, optionalStringField, parseJsonObject, requiredStringArray, splitCsvFlag, } from "../coerce.js";
 import { commandUsage, } from "../syntax.js";
 import { UsageError, } from "../usage.js";
 export function flowZoneId(value) {
@@ -107,7 +108,7 @@ export function flowZonePlanColor(value, source) {
 export function flowZonePlanPosition(value, source) {
     if (value === undefined)
         return undefined;
-    const record = plainRecord(value);
+    const record = asRecord(value);
     if (!record) {
         throw new UsageError(`${source} must be an object with x and y.`, "validation_failed");
     }
@@ -117,7 +118,7 @@ export function flowZonePlanPosition(value, source) {
     };
 }
 export function flowZoneCurrentPosition(zone) {
-    const position = plainRecord(zone.position);
+    const position = asRecord(zone.position);
     if (!position)
         return undefined;
     const x = position.x;
@@ -134,7 +135,7 @@ export function flowZoneSamePosition(a, b) {
 export function parseFlowZonePlanItem(value, source) {
     if (typeof value === "string")
         return parseFlowZoneObject(value);
-    const record = plainRecord(value);
+    const record = asRecord(value);
     if (!record) {
         throw new UsageError(`${source} must be TYPE:ID or an object.`, "validation_failed");
     }
@@ -213,7 +214,7 @@ export function parseFlowZoneOrganizePlan(input) {
         ...(topologyFingerprint ? { topologyFingerprint, } : {}),
         zones: zones.map((value, index) => {
             const source = `zones[${index}]`;
-            const record = plainRecord(value);
+            const record = asRecord(value);
             if (!record)
                 throw new UsageError(`${source} must be an object.`, "validation_failed");
             const id = optionalStringField(record, ["id", "zoneId",]);

package/dist/src/cli/version.d.ts

@@ -37,8 +37,6 @@ export interface CliVersionPayload {
     buildRevision: string | null;
     staleBuild: boolean;
 }
-/** Bun is the only supported runtime; the field is retained for payload stability. */
-export declare function detectRuntime(): CliRuntime;
 export declare function buildVersionPayload(input: {
     packageVersion: string;
     checkoutRevision: string | undefined;

package/dist/src/cli/version.js

@@ -182,10 +182,6 @@ export function sourceTreeNewerThanBuild(packageRoot) {
         return false;
     }
 }
-/** Bun is the only supported runtime; the field is retained for payload stability. */
-export function detectRuntime() {
-    return "bun";
-}
 export function buildVersionPayload(input) {
     const isDist = input.loadSource === "dist";
     // Source execution never claims a build revision, even if the environment
@@ -212,10 +208,11 @@ export const AGENT_CONTRACT_VERSION = 2;
 export const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
 export const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v2.json";
 export function cliVersionResult() {
-    /* oxlint-disable dss/no-direct-process-env -- launcher-injected load source and build revision */
-    const loadSource = process.env["DSS_LOAD_SOURCE"] ?? detectLoadSource();
-    const envBuildRevision = process.env["DSS_BUILD_REVISION"];
-    /* oxlint-enable dss/no-direct-process-env */
+    // Only code actually loaded from dist/ may report dist provenance; an
+    // inherited DSS_LOAD_SOURCE on a source run is ignored.
+    const loadSource = detectLoadSource();
+    /* oxlint-disable-next-line dss/no-direct-process-env -- launcher-injected build revision */
+    const envBuildRevision = loadSource === "dist" ? process.env["DSS_BUILD_REVISION"] : undefined;
     return buildVersionPayload({
         packageVersion: CLI_VERSION,
         checkoutRevision: CLI_GIT_REVISION,
@@ -227,6 +224,6 @@ export function cliVersionResult() {
         sourceNewerThanBuild: loadSource === "dist"
             ? sourceTreeNewerThanBuild(PACKAGE_ROOT)
             : false,
-        runtime: detectRuntime(),
+        runtime: "bun",
     });
 }