dataiku-sdk 4.0.0 → 4.1.0

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

@@ -10,4 +10,10 @@ export declare function envFileProvenance(name: string): EnvFileProvenance | und
 export declare function dataikuEnvironmentEnabled(): boolean;
 /** DATAIKU_PROJECT_KEY from the environment, unless `DATAIKU_DISABLE_ENV=1`. */
 export declare function ambientProjectKey(): string | undefined;
+/**
+ * `DSS_PRETTY=1` indents stdout JSON. Agent shells that cut long lines (omp at
+ * 768 bytes) truncate a one-line result; indented output keeps each line short.
+ * Read from the process environment only, never from a `.env` file.
+ */
+export declare function prettyOutputEnabled(): boolean;
 export declare function loadEnvFile(): void;

package/dist/src/cli/env.js

@@ -23,6 +23,14 @@ export function dataikuEnvironmentEnabled() {
 export function ambientProjectKey() {
     return dataikuEnvironmentEnabled() ? process.env.DATAIKU_PROJECT_KEY : undefined;
 }
+/**
+ * `DSS_PRETTY=1` indents stdout JSON. Agent shells that cut long lines (omp at
+ * 768 bytes) truncate a one-line result; indented output keeps each line short.
+ * Read from the process environment only, never from a `.env` file.
+ */
+export function prettyOutputEnabled() {
+    return process.env.DSS_PRETTY === "1";
+}
 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

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

@@ -11,6 +11,8 @@ export declare function pickResultFields(item: unknown, fields: string[]): unkno
  * that are absent become null so every row keeps a stable, predictable shape.
  */
 export declare function projectResultFields(result: unknown, fields: string[], availableFieldNames?: () => string[]): unknown;
+/** One JSON value plus newline for stdout; indented when `DSS_PRETTY=1`. */
+export declare function stdoutJson(value: unknown): string;
 export declare function writeCommandResult(result: unknown): void;
 export declare function addTransientTargetContext(error: unknown, target: string, elapsedMs: number): never;
 export declare function isFailedWaitResult(result: unknown): boolean;

package/dist/src/cli/output.js

@@ -1,4 +1,5 @@
 import { DataikuError, } from "../errors.js";
+import { prettyOutputEnabled, } from "./env.js";
 let outputFieldProjection;
 export function setOutputFieldProjection(fields) {
     outputFieldProjection = fields;
@@ -98,12 +99,16 @@ export function projectResultFields(result, fields, availableFieldNames) {
         return result.map((item) => pickResultFields(item, fields));
     return pickResultFields(result, fields);
 }
+/** One JSON value plus newline for stdout; indented when `DSS_PRETTY=1`. */
+export function stdoutJson(value) {
+    return `${JSON.stringify(value, null, prettyOutputEnabled() ? 2 : undefined)}\n`;
+}
 export function writeCommandResult(result) {
     const projected = outputFieldProjection
         ? projectResultFields(result, outputFieldProjection)
         : result;
     flushCliWarnings();
-    process.stdout.write(`${JSON.stringify(projected ?? { ok: true, })}\n`);
+    process.stdout.write(stdoutJson(projected ?? { ok: true, }));
 }
 export function addTransientTargetContext(error, target, elapsedMs) {
     if (error instanceof DataikuError && error.category === "transient") {
@@ -200,13 +205,28 @@ export function commandFailureMessage(result) {
             const resume = typeof record.resume === "string" ? ` Resume with: ${record.resume}` : "";
             return `Timed out waiting for job ${record.jobId} after ${record.elapsedMs}ms (last known state: ${record.state}); the job is still running in DSS and was not cancelled.${resume}`;
         }
+        if (record.timedOut === true) {
+            // ML training, scenario runs, futures, code run: the client stopped waiting. Only a
+            // result that says `cancelled: false` proves nothing was stopped; `code run` cleans up
+            // its throwaway scenario, so its `cleanup` status is what tells.
+            const known = typeof record.state === "string"
+                ? record.state
+                : typeof record.outcome === "string"
+                    ? record.outcome
+                    : undefined;
+            const elapsed = typeof record.elapsedMs === "number" ? ` after ${record.elapsedMs}ms` : "";
+            const after = record.cancelled === false
+                ? "the operation was not cancelled and may still be running in DSS."
+                : record.cleanup !== undefined
+                    ? "the client stopped waiting; see `cleanup` for what happened to the run."
+                    : "the client stopped waiting; the operation may still be running in DSS.";
+            return `Timed out waiting${elapsed}${known ? ` (last known state: ${known})` : ""}; ${after}`;
+        }
         const state = typeof record.state === "string"
             ? record.state
             : typeof record.outcome === "string"
                 ? record.outcome
-                : typeof record.timedOut === "boolean"
-                    ? "timed out"
-                    : undefined;
+                : undefined;
         return `Command completed with failed long-running result${state ? `: ${state}` : ""}.`;
     }
     if (isAssertionFailureResult(result)) {

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

@@ -32,6 +32,28 @@ export function compactReadOutputSchemas() {
         additionalProperties: false,
         properties: { type: STRING, message: STRING, },
     };
+    const triggerSchema = {
+        type: "object",
+        additionalProperties: false,
+        properties: { type: STRING, name: STRING, },
+    };
+    const failureSchema = {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            stepId: STRING,
+            jobId: STRING,
+            dataset: STRING,
+            recipe: STRING,
+            inputs: { type: "array", items: { type: "string", }, },
+            message: STRING,
+        },
+    };
+    const nextSchema = {
+        type: "array",
+        description: "Next commands to run, each as an argv array.",
+        items: { type: "array", items: STRING, },
+    };
     return {
         "job.get": {
             type: "object",
@@ -110,5 +132,73 @@ export function compactReadOutputSchemas() {
                 lastModifiedBy: STRING,
             },
         },
+        "scenario.get-run": {
+            type: "object",
+            additionalProperties: false,
+            required: ["runId", "steps",],
+            properties: {
+                runId: STRING,
+                scenarioId: STRING,
+                projectKey: STRING,
+                outcome: STRING,
+                start: NUMBER,
+                end: NUMBER,
+                durationMs: NUMBER,
+                trigger: triggerSchema,
+                steps: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            id: STRING,
+                            name: STRING,
+                            type: STRING,
+                            outcome: STRING,
+                            message: STRING,
+                            datasets: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    additionalProperties: false,
+                                    properties: { dataset: STRING, projectKey: STRING, partition: STRING, outcome: STRING, },
+                                },
+                            },
+                            jobs: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    additionalProperties: false,
+                                    properties: { jobId: STRING, outcome: STRING, message: STRING, },
+                                },
+                            },
+                        },
+                    },
+                },
+                failure: failureSchema,
+                next: nextSchema,
+                hint: {
+                    type: "string",
+                    description: "Edit-and-rerun commands when the failed recipe is known.",
+                },
+            },
+        },
+        "scenario.last-runs": {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["runId",],
+                properties: {
+                    runId: STRING,
+                    outcome: STRING,
+                    start: NUMBER,
+                    end: NUMBER,
+                    trigger: triggerSchema,
+                    failure: { type: "object", additionalProperties: false, properties: { message: STRING, }, },
+                    next: nextSchema,
+                },
+            },
+        },
     };
 }

package/dist/src/cli/result-shapes.d.ts

@@ -1,6 +1,24 @@
+type Item = Record<string, unknown>;
+/** The failed activity of a job: the recipe that failed and the datasets it read. */
+export interface FailedActivity {
+    recipe: string;
+    inputs: string[];
+}
+/**
+ * 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 declare function scenarioRunDiagnosis(details: unknown, activity?: FailedActivity): {
+    failure?: Item;
+    next?: string[][];
+    hint?: string;
+};
 /**
  * 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 declare function shapeCommandResult(resource: string, action: string, result: unknown, flags: Record<string, string | boolean>): unknown;
+export {};

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 = 5;
+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-v5.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

@@ -203,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 = 5;
+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-v5.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.