dataiku-sdk 3.9.0 → 4.1.0

package/dist/src/cli/result-shapes.js

@@ -1,7 +1,8 @@
 /**
- * Compact default results of the four large read commands (`job get`,
- * `dataset info`, `dataset get`, `project get`), plus the single dispatch
- * point for compacting command results (`shapeCommandResult`).
+ * Compact default results of the large read commands (`job get`,
+ * `dataset info`, `dataset get`, `project get`, `scenario get-run`,
+ * `scenario last-runs`), plus the single dispatch point for compacting
+ * command results (`shapeCommandResult`).
  *
  * The SDK resources keep returning the raw DSS objects; only the CLI compacts.
  * `--full` returns the DSS object unchanged, and `--fields` projects DSS paths
@@ -213,16 +214,238 @@ function shapeProjectGet(result) {
     const pruned = record(pruneEmpty(settings));
     return { ...pruned, deniedPermissions, };
 }
+/** Scenario/step/job outcomes that count as a failure worth diagnosing. */
+const FAILED_OUTCOMES = { FAILED: true, ABORTED: true, };
+function isFailedOutcome(value) {
+    return typeof value === "string" && FAILED_OUTCOMES[value] === true;
+}
+/** Message of a DSS `thrown` exception object (`{ clazz, message, ... }`). */
+function thrownMessage(value) {
+    const thrown = record(value);
+    return nonEmptyString(thrown["message"]) ?? nonEmptyString(thrown["detailedMessage"]);
+}
+function reportItems(stepRun, type) {
+    const items = stepRun["additionalReportItems"];
+    return Array.isArray(items)
+        ? items.filter((item) => isRecord(item) && item["type"] === type)
+        : [];
+}
+/**
+ * One `stepRuns[]` entry: the step identity and outcome, the datasets it built
+ * (`BUILT_DATASET` report items) and the jobs it ran (`JOB_EXECUTED`, with the
+ * thrown message). The job log tail DSS embeds in the report is dropped.
+ */
+function shapeScenarioStep(stepRun, runProjectKey) {
+    const fields = record(stepRun);
+    const step = record(fields["step"]);
+    const result = record(fields["result"]);
+    const datasets = reportItems(fields, "BUILT_DATASET").map((item) => {
+        const target = record(item["target"]);
+        const partition = target["partition"];
+        return defined({
+            dataset: target["datasetName"],
+            projectKey: typeof target["projectKey"] === "string" && target["projectKey"] !== runProjectKey
+                ? target["projectKey"]
+                : undefined,
+            partition: typeof partition === "string" && partition !== "NP" ? partition : undefined,
+            outcome: item["outcome"],
+        });
+    });
+    const jobs = reportItems(fields, "JOB_EXECUTED").map((item) => defined({
+        jobId: item["jobId"],
+        outcome: item["outcome"],
+        message: thrownMessage(item["thrown"]),
+    }));
+    return defined({
+        id: step["id"],
+        name: step["name"],
+        type: step["type"],
+        outcome: result["outcome"],
+        message: thrownMessage(result["thrown"]),
+        datasets: datasets.length > 0 ? datasets : undefined,
+        jobs: jobs.length > 0 ? jobs : undefined,
+    });
+}
+/**
+ * First failure of a shaped run: the failed step, its failed job and dataset,
+ * and the most specific message (job, then step, then scenario).
+ */
+function firstScenarioFailure(steps, runThrown) {
+    for (const step of steps) {
+        const jobs = step["jobs"] ?? [];
+        const job = jobs.find((entry) => isFailedOutcome(entry["outcome"]));
+        if (!isFailedOutcome(step["outcome"]) && !job)
+            continue;
+        const datasets = step["datasets"] ?? [];
+        const dataset = datasets.find((entry) => isFailedOutcome(entry["outcome"]));
+        return defined({
+            stepId: step["id"],
+            jobId: job?.["jobId"],
+            dataset: dataset?.["dataset"],
+            message: nonEmptyString(job?.["message"]) ?? nonEmptyString(step["message"])
+                ?? thrownMessage(runThrown),
+        });
+    }
+    const message = thrownMessage(runThrown);
+    return message === undefined ? undefined : { message, };
+}
+function projectKeyArgs(projectKey) {
+    return typeof projectKey === "string" && projectKey.length > 0
+        ? ["--project-key", projectKey,]
+        : [];
+}
+/**
+ * Next-step argv for a failure. With the failed recipe known: its code and the
+ * schemas of its inputs (what a "column not found" or type error needs), then
+ * the job's error log; else the job's error log, else the scenario run log.
+ */
+function failureNextSteps(failure, scenarioId, runId, projectKey, activity) {
+    const pk = projectKeyArgs(projectKey);
+    const inspect = activity
+        ? [
+            ["dss", "recipe", "cat", activity.recipe, ...pk,],
+            ...activity.inputs.slice(0, 3).map((input) => ["dss", "dataset", "schema", input, ...pk,]),
+        ]
+        : [];
+    if (typeof failure["jobId"] === "string") {
+        return [...inspect, ["dss", "job", "log", failure["jobId"], "--errors-only", ...pk,],];
+    }
+    if (typeof scenarioId !== "string" || typeof runId !== "string")
+        return undefined;
+    const stepArgs = typeof failure["stepId"] === "string" ? ["--step-id", failure["stepId"],] : [];
+    return [["dss", "scenario", "log", scenarioId, runId, ...stepArgs, ...pk,],];
+}
+/** Scenario identity of a run object (`scenarioRun` or a last-runs item). */
+function runScenarioIdentity(run) {
+    const scenario = record(run["scenario"]);
+    const target = record(record(run["result"])["target"]);
+    return {
+        scenarioId: scenario["id"] ?? target["scenarioId"],
+        projectKey: scenario["projectKey"] ?? target["projectKey"],
+    };
+}
+function runTrigger(run) {
+    const trigger = record(record(run["trigger"])["trigger"]);
+    const shaped = defined({
+        type: nonEmptyString(trigger["type"]),
+        name: nonEmptyString(trigger["name"]),
+    });
+    return Object.keys(shaped).length > 0 ? shaped : undefined;
+}
+/**
+ * Failure diagnosis of a raw `scenario get-run` report: the first failure
+ * (`{ stepId, jobId, dataset, message }`) and the next command(s) to run as
+ * argv arrays. With the failed recipe known, `hint` names the edit-and-rerun
+ * loop, so the agent does not look up the write commands. Empty when the run did not fail.
+ */
+export function scenarioRunDiagnosis(details, activity) {
+    const fields = record(details);
+    const run = record(fields["scenarioRun"]);
+    const result = record(run["result"]);
+    const { scenarioId, projectKey, } = runScenarioIdentity(run);
+    const steps = Array.isArray(fields["stepRuns"])
+        ? fields["stepRuns"].map((stepRun) => shapeScenarioStep(stepRun, projectKey))
+        : [];
+    const failed = isFailedOutcome(result["outcome"])
+        || steps.some((step) => isFailedOutcome(step["outcome"]));
+    const failure = failed ? firstScenarioFailure(steps, result["thrown"]) : undefined;
+    if (!failure)
+        return {};
+    if (!activity) {
+        const next = failureNextSteps(failure, scenarioId, run["runId"], projectKey, undefined);
+        return next ? { failure, next, } : { failure, };
+    }
+    const located = { ...failure, recipe: activity.recipe, inputs: activity.inputs, };
+    const next = failureNextSteps(located, scenarioId, run["runId"], projectKey, activity);
+    const pk = projectKeyArgs(projectKey).join(" ");
+    const suffix = pk === "" ? "" : ` ${pk}`;
+    const rerun = typeof scenarioId === "string"
+        ? `; rerun: dss scenario run-and-wait ${scenarioId}${suffix}`
+        : "";
+    const hint = `To fix: dss recipe get-payload ${activity.recipe} --output FILE${suffix}, edit FILE, `
+        + `dss recipe set-payload ${activity.recipe} --file FILE${suffix}${rerun}.`;
+    return next ? { failure: located, next, hint, } : { failure: located, hint, };
+}
+/**
+ * `scenario get-run`: run identity, outcome, timing, trigger, per-step
+ * datasets/jobs, the first failure, and next-step argv. Never the trigger
+ * auth context, run-as user, API key metadata, or job log tails.
+ */
+function shapeScenarioGetRun(result) {
+    if (!isRecord(result) || !isRecord(result["scenarioRun"]))
+        return result;
+    const run = result["scenarioRun"];
+    const runResult = record(run["result"]);
+    const { scenarioId, projectKey, } = runScenarioIdentity(run);
+    const start = typeof run["start"] === "number" ? run["start"] : undefined;
+    const end = typeof run["end"] === "number" ? run["end"] : undefined;
+    const steps = Array.isArray(result["stepRuns"])
+        ? result["stepRuns"].map((stepRun) => shapeScenarioStep(stepRun, projectKey))
+        : [];
+    const { failure, next, } = scenarioRunDiagnosis(result);
+    return defined({
+        runId: run["runId"],
+        scenarioId,
+        projectKey,
+        outcome: runResult["outcome"],
+        start,
+        end,
+        durationMs: start !== undefined && end !== undefined && end >= start ? end - start : undefined,
+        trigger: runTrigger(run),
+        steps,
+        failure,
+        next,
+    });
+}
+/**
+ * One `scenario last-runs` item: identity, outcome, timing, trigger, failure
+ * message, and for a failed run the `scenario get-run` argv that shows why.
+ */
+function shapeScenarioRunSummary(item) {
+    if (!isRecord(item))
+        return item;
+    const result = record(item["result"]);
+    const message = thrownMessage(result["thrown"]);
+    const { scenarioId, projectKey, } = runScenarioIdentity(item);
+    const next = isFailedOutcome(result["outcome"]) && typeof scenarioId === "string"
+        && typeof item["runId"] === "string"
+        ? [[
+                "dss",
+                "scenario",
+                "get-run",
+                scenarioId,
+                item["runId"],
+                ...(typeof projectKey === "string" ? ["--project-key", projectKey,] : []),
+            ],]
+        : undefined;
+    // DSS lists an in-progress run with `end: 0` and no result outcome.
+    const running = result["outcome"] === undefined && item["end"] === 0;
+    return defined({
+        runId: item["runId"],
+        outcome: running ? "RUNNING" : result["outcome"],
+        start: item["start"] ?? result["start"],
+        end: item["end"] ?? result["end"],
+        trigger: runTrigger(item),
+        failure: message === undefined ? undefined : { message, },
+        next,
+    });
+}
+/** `scenario last-runs`: one small object per run, newest first as DSS returns them. */
+function shapeScenarioLastRuns(result) {
+    return Array.isArray(result) ? result.map(shapeScenarioRunSummary) : result;
+}
 /** Compact read shapers by `resource.action`. */
 const READ_SHAPERS = {
     "job.get": shapeJobGet,
     "dataset.info": shapeDatasetInfo,
     "dataset.get": shapeDatasetGet,
     "project.get": shapeProjectGet,
+    "scenario.get-run": shapeScenarioGetRun,
+    "scenario.last-runs": shapeScenarioLastRuns,
 };
 /**
  * Compact a command result for agents: `*.list` items (filter, cap, compact
- * fields) and the four large read commands. `--full` and `--fields` bypass
+ * fields) and the large read commands. `--full` and `--fields` bypass
  * the read shapers so the DSS object (or a projection of it) is returned.
  */
 export function shapeCommandResult(resource, action, result, flags) {

package/dist/src/cli/selector-suggestions.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Did-you-mean suggestions for `commands run --fields RESOURCE[.ACTION[.FIELD...]]`
+ * selectors that name no resource or action. Pure data in, strings out.
+ */
+/**
+ * Selectors worth trying instead of an unknown `resource` / `resource.action`
+ * selector, keeping any trailing `.field` path. For a known resource: the same
+ * action name under other resources (`flow.map.usage` -> `project.map.usage`),
+ * then close action names of that resource. For an unknown resource: close
+ * resource names (keeping the action), else the action under other resources.
+ *
+ * @param actionsByResource resource -> action names (`commandActionSummary()`).
+ */
+export declare function suggestSelectors(selector: string, actionsByResource: Record<string, string[]>): string[];

package/dist/src/cli/selector-suggestions.js

@@ -0,0 +1,56 @@
+/**
+ * Did-you-mean suggestions for `commands run --fields RESOURCE[.ACTION[.FIELD...]]`
+ * selectors that name no resource or action. Pure data in, strings out.
+ */
+const MAX_SUGGESTIONS = 4;
+/** Levenshtein distance with a single rolling row. */
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1, }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i,];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current.push(Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost));
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** Names close to `name`: a typo (distance <= 2, <= 1 for short names) or one containing it. */
+function closeNames(name, candidates) {
+    const maxDistance = name.length >= 5 ? 2 : 1;
+    return candidates.filter((candidate) => candidate !== name
+        && (editDistance(name, candidate) <= maxDistance
+            || (name.length >= 3 && candidate.includes(name))));
+}
+/**
+ * Selectors worth trying instead of an unknown `resource` / `resource.action`
+ * selector, keeping any trailing `.field` path. For a known resource: the same
+ * action name under other resources (`flow.map.usage` -> `project.map.usage`),
+ * then close action names of that resource. For an unknown resource: close
+ * resource names (keeping the action), else the action under other resources.
+ *
+ * @param actionsByResource resource -> action names (`commandActionSummary()`).
+ */
+export function suggestSelectors(selector, actionsByResource) {
+    const [resource = "", action, ...rest] = selector.split(".");
+    const suffix = rest.length > 0 ? `.${rest.join(".")}` : "";
+    const resources = Object.keys(actionsByResource);
+    const sameActionElsewhere = action === undefined
+        ? []
+        : resources.filter((other) => other !== resource && actionsByResource[other].includes(action))
+            .map((other) => `${other}.${action}${suffix}`);
+    let suggestions;
+    if (Object.hasOwn(actionsByResource, resource)) {
+        const closeActions = action === undefined
+            ? []
+            : closeNames(action, actionsByResource[resource]).map((close) => `${resource}.${close}${suffix}`);
+        suggestions = [...sameActionElsewhere, ...closeActions,];
+    }
+    else {
+        const tail = action === undefined ? "" : `.${[action, ...rest,].join(".")}`;
+        const closeResources = closeNames(resource, resources).map((close) => `${close}${tail}`);
+        suggestions = closeResources.length > 0 ? closeResources : sameActionElsewhere;
+    }
+    return [...new Set(suggestions),].slice(0, MAX_SUGGESTIONS);
+}

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

@@ -11,7 +11,7 @@ export declare const COMMANDS_RUN_HINT = "Use `dss commands run --fields RESOURC
 export declare function unsupportedHelpFlag(): UsageError;
 export declare function noCommandError(): UsageError;
 export declare function missingActionError(resource: string, validActions: string[], usage?: string): UsageError;
-export declare function unknownResourceError(resource: string): UsageError;
+export declare function unknownResourceError(resource: string, action?: string): UsageError;
 /**
  * Agents rarely mistype; they reuse plausible flags from other commands or
  * CLIs. When the command is known, the hint is its usage line, which lists

package/dist/src/cli/usage.js

@@ -1,4 +1,23 @@
-import { commandSyntaxTree, renderNodes, syntaxHasFlag, } from "./syntax.js";
+import { suggestSelectors, } from "./selector-suggestions.js";
+import { commandSyntaxKeys, commandSyntaxTree, renderNodes, syntaxHasFlag, } from "./syntax.js";
+/**
+ * `dss resource action` commands close to a mistyped one (`flow map` -> `project map`,
+ * `recipes list` -> `recipe list`), from the syntax tree, so the error names the fix.
+ */
+function commandSuggestions(resource, action) {
+    const actionsByResource = {};
+    for (const key of commandSyntaxKeys()) {
+        const dot = key.indexOf(".");
+        (actionsByResource[key.slice(0, dot)] ??= []).push(key.slice(dot + 1));
+    }
+    return suggestSelectors(action ? `${resource}.${action}` : resource, actionsByResource)
+        .map((selector) => `dss ${selector.replace(".", " ")}`);
+}
+function suggestionHint(suggestions) {
+    return suggestions.length > 0
+        ? `Did you mean ${suggestions.map((command) => `\`${command}\``).join(" or ")}? ${COMMANDS_RUN_HINT}`
+        : COMMANDS_RUN_HINT;
+}
 export const RESOURCE_NAMES = [
     "agent",
     "app",
@@ -122,8 +141,13 @@ export function noCommandError() {
 export function missingActionError(resource, validActions, usage) {
     return new UsageError(`Missing action for ${resource}.`, "usage_error", usage ?? COMMANDS_RUN_HINT, { resource, validActions, });
 }
-export function unknownResourceError(resource) {
-    return new UsageError(`Unknown resource: ${resource}.`, "usage_error", COMMANDS_RUN_HINT, { resource, validResources: RESOURCE_NAMES, });
+export function unknownResourceError(resource, action) {
+    const suggestions = commandSuggestions(resource, action);
+    return new UsageError(`Unknown resource: ${resource}.`, "usage_error", suggestionHint(suggestions), {
+        resource,
+        validResources: RESOURCE_NAMES,
+        ...(suggestions.length > 0 ? { suggestions, } : {}),
+    });
 }
 /**
  * Agents rarely mistype; they reuse plausible flags from other commands or
@@ -141,7 +165,8 @@ export function unknownFlagError(flagLabel, resource, action) {
     return new UsageError(message, "unknown_flag", command ? `Usage: ${renderNodes(command)}` : undefined);
 }
 export function unknownActionError(resource, action, validActions, hint) {
-    return new UsageError(`Unknown action: ${resource} ${action ?? ""}`.trim(), "usage_error", hint ?? COMMANDS_RUN_HINT, { resource, action, validActions, });
+    const suggestions = commandSuggestions(resource, action);
+    return new UsageError(`Unknown action: ${resource} ${action ?? ""}`.trim(), "usage_error", hint ?? suggestionHint(suggestions), { resource, action, validActions, ...(suggestions.length > 0 ? { suggestions, } : {}), });
 }
 export function requireArgs(args, count, usage) {
     if (args.length < count) {

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

@@ -49,7 +49,7 @@ export declare function buildVersionPayload(input: {
 export declare const PACKAGE_ROOT: string | undefined;
 export declare const CLI_VERSION: string;
 export declare const CLI_GIT_REVISION: string | undefined;
-export declare const AGENT_CONTRACT_VERSION = 4;
+export declare const AGENT_CONTRACT_VERSION = 6;
 export declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
-export declare const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v4.json";
+export declare const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v6.json";
 export declare function cliVersionResult(): CliVersionPayload;

package/dist/src/cli/version.js

@@ -1,8 +1,7 @@
 import { readdirSync, readFileSync, statSync, } from "node:fs";
 import { dirname, resolve, } from "node:path";
-import { fileURLToPath, } from "node:url";
 export function findPackageRoot() {
-    let dir = dirname(fileURLToPath(import.meta.url));
+    let dir = import.meta.dir;
     for (let i = 0; i < 5; i++) {
         try {
             readFileSync(resolve(dir, "package.json"), "utf-8");
@@ -133,7 +132,7 @@ export function gitRevision(packageRoot) {
     const full = gitFullRevision(packageRoot);
     return full ? full.slice(0, 7) : undefined;
 }
-export function detectLoadSource(modulePath = fileURLToPath(import.meta.url)) {
+export function detectLoadSource(modulePath = import.meta.path) {
     return modulePath.replaceAll("\\", "/").includes("/dist/") ? "dist" : "source";
 }
 export function buildMetadataRevision(packageRoot) {
@@ -204,9 +203,9 @@ export function buildVersionPayload(input) {
 export const PACKAGE_ROOT = findPackageRoot();
 export const CLI_VERSION = packageVersion(PACKAGE_ROOT);
 export const CLI_GIT_REVISION = gitRevision(PACKAGE_ROOT);
-export const AGENT_CONTRACT_VERSION = 4;
+export const AGENT_CONTRACT_VERSION = 6;
 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-v4.json";
+export const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v6.json";
 export function cliVersionResult() {
     // Only code actually loaded from dist/ may report dist provenance; an
     // inherited DSS_LOAD_SOURCE on a source run is ignored.