dataiku-sdk 3.4.0 → 3.5.0

package/dist/src/cli/doctor.js

@@ -29,6 +29,7 @@ export function firstStringField(items, fields) {
     return null;
 }
 export function integrationFlag(name) {
+    // oxlint-disable-next-line dss/no-direct-process-env -- RUN_DATAIKU_* integration opt-in flags
     const value = process.env[name];
     return value === "1" || value?.toLowerCase() === "true";
 }

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

@@ -8,4 +8,6 @@ export type EnvFileProvenance = "project" | "install";
  */
 export declare function envFileProvenance(name: string): EnvFileProvenance | undefined;
 export declare function dataikuEnvironmentEnabled(): boolean;
+/** DATAIKU_PROJECT_KEY from the environment, unless `DATAIKU_DISABLE_ENV=1`. */
+export declare function ambientProjectKey(): string | undefined;
 export declare function loadEnvFile(): void;

package/dist/src/cli/env.js

@@ -20,6 +20,20 @@ export function envFileProvenance(name) {
 export function dataikuEnvironmentEnabled() {
     return process.env.DATAIKU_DISABLE_ENV !== "1";
 }
+/** DATAIKU_PROJECT_KEY from the environment, unless `DATAIKU_DISABLE_ENV=1`. */
+export function ambientProjectKey() {
+    return dataikuEnvironmentEnabled() ? process.env.DATAIKU_PROJECT_KEY : undefined;
+}
+const allowedEnvKeys = new Set(["NODE_EXTRA_CA_CERTS", "NODE_TLS_REJECT_UNAUTHORIZED",]);
+/**
+ * `.env` files are untrusted input: only the CLI's own `DATAIKU_*` variables and
+ * Node's TLS trust knobs are read. Every other key is ignored silently, so a
+ * project working tree cannot redirect the CLI (for example by smuggling in
+ * `DSS_CONFIG_DIR` and sending saved credentials elsewhere).
+ */
+function isAllowedEnvKey(key) {
+    return key.startsWith("DATAIKU_") || allowedEnvKeys.has(key);
+}
 export function loadEnvFile() {
     if (!dataikuEnvironmentEnabled())
         return;
@@ -42,7 +56,7 @@ export function loadEnvFile() {
                     continue;
                 const key = trimmed.slice(0, eq).trim();
                 const val = trimmed.slice(eq + 1).trim().replace(/^['"]|['"]$/g, "");
-                if (!process.env[key]) {
+                if (isAllowedEnvKey(key) && !process.env[key]) {
                     process.env[key] = val;
                     (index === 0 ? projectEnvVars : installEnvVars).add(key);
                 }

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

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { ClientValidationError, } from "../../errors.js";
 import { canonicalDssUrl, } from "../../utils/dss-url.js";
 import { compareStrings, } from "../../utils/stable-hash.js";
 import { parseJsonObject, plainRecord, stableHash, stableJson, } from "../coerce.js";
@@ -61,7 +62,7 @@ function writeAllSync(fd, payload) {
     while (offset < payload.length) {
         const written = fs.writeSync(fd, payload, offset, payload.length - offset, offset);
         if (written <= 0) {
-            throw new Error(`Stalled writing app permissions snapshot at byte ${offset}.`);
+            throw new ClientValidationError(`Stalled writing app permissions snapshot at byte ${offset}.`, "internal_error");
         }
         offset += written;
     }

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

@@ -1,6 +1,7 @@
 import { readFileSync, } from "node:fs";
 import { compareStrings, } from "../../utils/stable-hash.js";
 import { finiteNumberField, jsonInput, optionalStringField, parseJsonObject, plainRecord, requiredStringArray, splitCsvFlag, } from "../coerce.js";
+import { commandUsage, } from "../syntax.js";
 import { UsageError, } from "../usage.js";
 export function flowZoneId(value) {
     const trimmed = value.trim();
@@ -10,7 +11,7 @@ export function flowZoneId(value) {
 }
 export function flowZoneName(value) {
     if (typeof value !== "string" || value.trim().length === 0) {
-        throw new UsageError("--name is required. Usage: dss flow-zone create --name NAME [--color #RRGGBB]");
+        throw new UsageError(`--name is required. Usage: ${commandUsage("flow-zone", "create")}`);
     }
     return value.trim();
 }

package/dist/src/cli/helpers/recipe.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import { tmpdir, } from "node:os";
 import { join, parse as parsePath, relative as relativePath, resolve as resolvePath, sep, } from "node:path";
+import { ClientValidationError, } from "../../errors.js";
 import { sanitizeFileName, } from "../../utils/sanitize.js";
 import { normalizeLineEndings, sha256Hex, stableHash, } from "../coerce.js";
 import { UsageError, } from "../usage.js";
@@ -126,7 +127,7 @@ function writeAllSync(fd, payload) {
     while (offset < payload.length) {
         const written = fs.writeSync(fd, payload, offset, payload.length - offset, offset);
         if (written <= 0) {
-            throw new Error(`Stalled writing recipe backup at byte ${offset}.`);
+            throw new ClientValidationError(`Stalled writing recipe backup at byte ${offset}.`, "internal_error");
         }
         offset += written;
     }

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

@@ -0,0 +1,83 @@
+import type { CommandDefinition, CommandFlagChoice, CommandMeta } from "./types.js";
+/**
+ * One element of a command's usage line. `src/cli/command-syntax.json` holds an
+ * ordered node list per command; it is the source of truth for the usage text
+ * (rendered by {@link commandUsage}) and for every usage-level contract field
+ * (derived by {@link commandSyntax}).
+ */
+export type SyntaxNode = 
+/** Literal word: `dss`, the resource, the action. */
+string
+/** Positional argument, rendered `<name>` (or bare `name` when `bare`). */
+ | {
+    arg: string;
+    bare?: boolean;
+}
+/** Flag, rendered `--flag`, `--flag VALUE`, or `--flag a|b` (enum), plus an optional trailing note. */
+ | {
+    flag: string;
+    value?: string;
+    values?: string[];
+    note?: string;
+}
+/** Optional group `[a|b]`; each alternative is a node sequence. */
+ | {
+    optional: SyntaxNode[][];
+    sep?: string;
+}
+/** Required choice `(a|b)`; each alternative is a node sequence. */
+ | {
+    oneOf: SyntaxNode[][];
+    sep?: string;
+};
+export type FlagNode = Extract<SyntaxNode, {
+    flag: string;
+}>;
+export interface CommandPositionalMetadata {
+    name: string;
+    required: boolean;
+}
+/** Input channels a command accepts for its JSON payload. */
+export interface CommandInputContract {
+    stdin?: boolean;
+    dataFlag?: boolean;
+    dataFileFlag?: boolean;
+}
+/** Usage-level contract fields derived from a command's syntax tree. */
+export interface CommandSyntax {
+    /** Canonical names of the flags the usage line lists, in order. */
+    flags: string[];
+    requiredFlags: string[];
+    requiredOneOf: CommandFlagChoice[];
+    valueHints: Record<string, {
+        valueType: string;
+        enumValues?: string[];
+    }>;
+    inputContract: CommandInputContract;
+    positionalArguments: CommandPositionalMetadata[];
+    /** Alias spellings (canonical name -> raw names) the usage line uses. */
+    aliases: Record<string, string[]>;
+    dryRun: boolean;
+    producesLocalFile: boolean;
+}
+/** The syntax tree for `resource.action`, or undefined when no such command exists. */
+export declare function commandSyntaxTree(resource: string, action: string): SyntaxNode[] | undefined;
+export declare function commandSyntaxKeys(): string[];
+/** Render a node sequence as usage text; `omitOptional` drops every `[...]` group. */
+export declare function renderNodes(nodes: SyntaxNode[], omitOptional?: boolean): string;
+/** The human usage line for `resource.action`, rendered from its syntax tree. */
+export declare function commandUsage(resource: string, action: string): string;
+/**
+ * Attach each action's usage line, rendered from its syntax tree. Every command
+ * module exports its definitions through this, so a command without a syntax
+ * entry fails at load instead of shipping an undocumented contract.
+ */
+export declare function withUsage(resource: string, definitions: Record<string, CommandDefinition>): Record<string, CommandMeta>;
+/** Whether the syntax lists `--name` (the raw spelling, not an alias). */
+export declare function syntaxHasFlag(nodes: SyntaxNode[], name: string): boolean;
+/** Leading literal words after `dss` (resource and, when present, action). */
+export declare function syntaxCommandWords(nodes: SyntaxNode[]): string[];
+/** Usage-level contract fields of a syntax tree (flags, requirements, value hints, positionals, inputs). */
+export declare function deriveSyntax(nodes: SyntaxNode[]): CommandSyntax;
+/** Usage-level contract fields for `resource.action`, derived from its syntax tree. */
+export declare function commandSyntax(resource: string, action: string): CommandSyntax;

package/dist/src/cli/syntax.js

@@ -0,0 +1,217 @@
+import { ClientValidationError, } from "../errors.js";
+import commandSyntaxSource from "./command-syntax.json" with { type: "json" };
+import { FLAG_ALIASES, KNOWN_LONG_FLAGS, } from "./flags.js";
+const SOURCE = commandSyntaxSource.commands;
+/** The syntax tree for `resource.action`, or undefined when no such command exists. */
+export function commandSyntaxTree(resource, action) {
+    return Object.hasOwn(SOURCE, `${resource}.${action}`)
+        ? SOURCE[`${resource}.${action}`]
+        : undefined;
+}
+function requiredSyntaxTree(resource, action) {
+    const nodes = commandSyntaxTree(resource, action);
+    if (!nodes) {
+        throw new ClientValidationError(`No syntax for ${resource} ${action} in src/cli/command-syntax.json.`, "internal_error");
+    }
+    return nodes;
+}
+export function commandSyntaxKeys() {
+    return Object.keys(SOURCE);
+}
+function renderNode(node, omitOptional) {
+    if (typeof node === "string")
+        return node;
+    if ("arg" in node)
+        return node.bare ? node.arg : `<${node.arg}>`;
+    if ("flag" in node) {
+        const value = node.values ? node.values.join("|") : node.value;
+        return `--${node.flag}${value === undefined ? "" : ` ${value}`}${node.note ? ` ${node.note}` : ""}`;
+    }
+    if ("optional" in node) {
+        return omitOptional ? "" : `[${renderAlternatives(node.optional, node.sep, omitOptional)}]`;
+    }
+    return `(${renderAlternatives(node.oneOf, node.sep, omitOptional)})`;
+}
+function renderAlternatives(alternatives, sep, omitOptional) {
+    return alternatives.map((alternative) => renderNodes(alternative, omitOptional)).join(sep ?? "|");
+}
+/** Render a node sequence as usage text; `omitOptional` drops every `[...]` group. */
+export function renderNodes(nodes, omitOptional = false) {
+    return nodes.map((node) => renderNode(node, omitOptional)).filter((part) => part !== "").join(" ");
+}
+const usageCache = new Map();
+/** The human usage line for `resource.action`, rendered from its syntax tree. */
+export function commandUsage(resource, action) {
+    const key = `${resource}.${action}`;
+    let usage = usageCache.get(key);
+    if (usage === undefined) {
+        usage = renderNodes(requiredSyntaxTree(resource, action));
+        usageCache.set(key, usage);
+    }
+    return usage;
+}
+/**
+ * Attach each action's usage line, rendered from its syntax tree. Every command
+ * module exports its definitions through this, so a command without a syntax
+ * entry fails at load instead of shipping an undocumented contract.
+ */
+export function withUsage(resource, definitions) {
+    const commands = {};
+    for (const [action, definition,] of Object.entries(definitions)) {
+        commands[action] = { ...definition, usage: commandUsage(resource, action), };
+    }
+    return commands;
+}
+function walk(nodes, visit, context = {
+    optional: false,
+    oneOf: undefined,
+}) {
+    for (const node of nodes) {
+        if (typeof node === "string")
+            continue;
+        visit(node, context);
+        if ("optional" in node) {
+            for (const alternative of node.optional) {
+                walk(alternative, visit, { ...context, optional: true, });
+            }
+        }
+        else if ("oneOf" in node) {
+            for (const alternative of node.oneOf) {
+                walk(alternative, visit, { ...context, oneOf: node.oneOf, });
+            }
+        }
+    }
+}
+function flagNodes(nodes) {
+    const found = [];
+    walk(nodes, (node) => {
+        if ("flag" in node)
+            found.push(node);
+    });
+    return found;
+}
+/** Whether the syntax lists `--name` (the raw spelling, not an alias). */
+export function syntaxHasFlag(nodes, name) {
+    return flagNodes(nodes).some((node) => node.flag === name);
+}
+/** Leading literal words after `dss` (resource and, when present, action). */
+export function syntaxCommandWords(nodes) {
+    const words = [];
+    for (const node of nodes.slice(1)) {
+        if (typeof node !== "string")
+            break;
+        words.push(node);
+    }
+    return words;
+}
+function canonicalFlag(name) {
+    return FLAG_ALIASES[name] ?? name;
+}
+function knownCanonicalFlags(nodes) {
+    return unique(nodes.map((node) => canonicalFlag(node.flag))).filter((flag) => KNOWN_LONG_FLAGS.has(flag));
+}
+function unique(values) {
+    return [...new Set(values),];
+}
+/** Flags of a sequence outside its optional groups (a required choice's alternative). */
+function requiredFlagsOf(nodes) {
+    const found = [];
+    walk(nodes, (node, context) => {
+        if ("flag" in node && !context.optional)
+            found.push(node);
+    });
+    return knownCanonicalFlags(found);
+}
+function deriveRequired(nodes) {
+    const requiredFlags = knownCanonicalFlags(nodes.filter((node) => typeof node !== "string" && "flag" in node));
+    const requiredOneOf = [];
+    for (const node of nodes) {
+        if (typeof node === "string" || !("oneOf" in node))
+            continue;
+        const alternatives = node.oneOf.map(requiredFlagsOf);
+        if (alternatives.length <= 1) {
+            requiredFlags.push(...(alternatives[0] ?? []));
+            continue;
+        }
+        // A choice with a flagless alternative (a positional, e.g. sql query's
+        // `(SQL | --sql QUERY | ...)`) cannot be expressed as a flag-only choice:
+        // requiring one of the flags would be false. The handler stays the authority.
+        if (alternatives.some((alternative) => alternative.length === 0))
+            continue;
+        requiredOneOf.push({ oneOf: alternatives, });
+    }
+    return { requiredFlags: unique(requiredFlags), requiredOneOf, };
+}
+const PLACEHOLDER_VALUE = /^(<[^>]+>|[A-Z][A-Za-z0-9_]*)/;
+function deriveValueHints(flags) {
+    const hints = {};
+    // Enumerations take precedence over a placeholder elsewhere in the line.
+    for (const node of flags) {
+        const flag = canonicalFlag(node.flag);
+        if (node.values && hints[flag] === undefined) {
+            hints[flag] = { valueType: "enum", enumValues: node.values, };
+        }
+    }
+    for (const node of flags) {
+        const flag = canonicalFlag(node.flag);
+        const placeholder = node.value?.match(PLACEHOLDER_VALUE)?.[1];
+        if (placeholder && hints[flag] === undefined)
+            hints[flag] = { valueType: placeholder, };
+    }
+    return hints;
+}
+function derivePositionals(nodes) {
+    const positionals = [];
+    walk(nodes, (node, context) => {
+        if (!("arg" in node))
+            return;
+        const arg = node;
+        // A positional inside a required choice that offers a flag instead is optional.
+        const flagAlternative = context.oneOf?.some((alternative) => flagNodes(alternative).length > 0)
+            ?? false;
+        const required = !context.optional && !flagAlternative;
+        const existing = positionals.find((positional) => positional.name === arg.arg);
+        if (existing)
+            existing.required ||= required;
+        else
+            positionals.push({ name: arg.arg, required, });
+    });
+    return positionals;
+}
+/** Usage-level contract fields of a syntax tree (flags, requirements, value hints, positionals, inputs). */
+export function deriveSyntax(nodes) {
+    const flags = flagNodes(nodes);
+    const has = (name) => flags.some((node) => node.flag === name);
+    const aliases = {};
+    for (const [raw, canonical,] of Object.entries(FLAG_ALIASES)) {
+        if (has(raw))
+            (aliases[canonical] ??= []).push(raw);
+    }
+    return {
+        flags: knownCanonicalFlags(flags),
+        ...deriveRequired(nodes),
+        valueHints: deriveValueHints(flags),
+        inputContract: {
+            ...(has("stdin") ? { stdin: true, } : {}),
+            ...(flags.some((node) => node.flag === "data" && (node.value !== undefined || node.values !== undefined))
+                ? { dataFlag: true, }
+                : {}),
+            ...(has("data-file") ? { dataFileFlag: true, } : {}),
+        },
+        positionalArguments: derivePositionals(nodes),
+        aliases,
+        dryRun: has("dry-run"),
+        producesLocalFile: flags.some((node) => (node.flag === "output" || node.flag === "output-file") && node.value === "PATH"),
+    };
+}
+const syntaxCache = new Map();
+/** Usage-level contract fields for `resource.action`, derived from its syntax tree. */
+export function commandSyntax(resource, action) {
+    const key = `${resource}.${action}`;
+    let syntax = syntaxCache.get(key);
+    if (!syntax) {
+        syntax = deriveSyntax(requiredSyntaxTree(resource, action));
+        syntaxCache.set(key, syntax);
+    }
+    return syntax;
+}

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

@@ -28,7 +28,10 @@ export interface CommandMeta extends CommandRegistryOverride {
      * credentials are configured, instead of being masked by a missing-URL error.
      */
     validate?: (args: string[], flags: Record<string, string | boolean>) => void;
+    /** Rendered from the command's syntax tree in `src/cli/command-syntax.json`; never hand-written. */
     usage: string;
     description?: string;
     examples?: string[];
 }
+/** A command as authored: its usage line comes from `src/cli/command-syntax.json` (see `withUsage`). */
+export type CommandDefinition = Omit<CommandMeta, "usage">;

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

@@ -1,6 +1,6 @@
 import type { StableErrorCode } from "../errors.js";
 export declare const RESOURCE_NAMES: string[];
-export declare function inferRequiresProject(resource: string, action: string, usage: string): boolean;
+export declare function inferRequiresProject(resource: string, action: string): boolean;
 export declare class UsageError extends Error {
     readonly code: StableErrorCode;
     readonly hint?: string;

package/dist/src/cli/usage.js

@@ -1,3 +1,4 @@
+import { commandSyntaxTree, syntaxHasFlag, } from "./syntax.js";
 export const RESOURCE_NAMES = [
     "agent",
     "app",
@@ -79,7 +80,7 @@ const PROJECT_SCOPED_RESOURCES = new Set([
     "saved-model",
     "wiki",
 ]);
-export function inferRequiresProject(resource, action, usage) {
+export function inferRequiresProject(resource, action) {
     if (resource === "agent" || resource === "auth" || resource === "doctor" || resource === "commands"
         || resource === "install-skill" || resource === "version")
         return false;
@@ -92,7 +93,8 @@ export function inferRequiresProject(resource, action, usage) {
         return false;
     if (resource === "project-git")
         return !action.startsWith("future-");
-    return usage.includes("--project-key");
+    const syntax = commandSyntaxTree(resource, action);
+    return syntax !== undefined && syntaxHasFlag(syntax, "project-key");
 }
 export class UsageError extends Error {
     code;

package/dist/src/cli/version.js

@@ -212,8 +212,10 @@ 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 */
     return buildVersionPayload({
         packageVersion: CLI_VERSION,
         checkoutRevision: CLI_GIT_REVISION,