dataiku-sdk 3.6.1 → 3.8.0

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

@@ -1,10 +1,104 @@
 import { ClientValidationError, } from "../../errors.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
+import { asRecord, } from "../../utils/records.js";
 import { executionMode, } from "../flags.js";
-import { ensureFlowZonePlanTarget, findFlowZoneForPlan, flowZoneColor, flowZoneContains, flowZoneCurrentPosition, flowZoneDetailSummary, flowZoneId, flowZoneMoveDelta, flowZoneMoveItems, flowZoneName, flowZoneOrganizeStep, flowZonePlanFromZones, flowZonePlanItemKeys, flowZonePruneItems, flowZoneSamePosition, flowZoneSummary, readFlowZoneOrganizePlan, resolveFlowZoneIdFromFlags, throwFlowZoneValidationError, validateFlowZoneOrganizeObjects, } from "../helpers/flow-zone.js";
-import { readIfExists, skipResult, } from "../output.js";
+import { applyFlowZoneUnits, ensureFlowZonePlanTarget, findFlowZoneForPlan, flowZoneColor, flowZoneContains, flowZoneCurrentPosition, flowZoneDetailSummary, flowZoneId, flowZoneMoveDelta, flowZoneMoveItems, flowZoneName, flowZoneOrganizeStep, flowZonePlanFromZones, flowZonePlanItemKeys, flowZonePruneItems, flowZoneRepositionTarget, flowZoneSamePosition, flowZoneSummary, flowZoneUnassignedItems, readFlowZoneOrganizePlan, resolveFlowZoneIdFromFlags, throwFlowZoneValidationError, validateFlowZoneOrganizeObjects, } from "../helpers/flow-zone.js";
+import { enqueueCliWarning, readIfExists, skipResult, } from "../output.js";
 import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
+const ZONE_OBJECT_IDS = { type: "array", items: { type: "string", minLength: 1, }, };
+/** JSON Schema of the `flow-zone organize` plan, as parsed by `parseFlowZoneOrganizePlan`. */
+const FLOW_ZONE_ORGANIZE_PLAN_SCHEMA = {
+    type: "object",
+    required: ["zones",],
+    properties: {
+        topologyFingerprint: {
+            type: "string",
+            pattern: "^[0-9a-f]{64}$",
+            description: "From dss flow-zone plan; organize refuses to apply if the flow topology changed since.",
+        },
+        zones: {
+            type: "array",
+            items: {
+                type: "object",
+                anyOf: [{ required: ["id",], }, { required: ["name",], },],
+                properties: {
+                    id: { type: "string", description: "Existing zone id (alias zoneId); matched before name.", },
+                    name: { type: "string", description: "Zone name; required to create a zone.", },
+                    color: { type: "string", pattern: "^#[0-9a-fA-F]{6}$", },
+                    position: {
+                        type: "object",
+                        required: ["x", "y",],
+                        properties: { x: { type: "number", }, y: { type: "number", }, },
+                        description: "Applied when the zone is created; moving an existing zone requires --recreate-on-move.",
+                    },
+                    items: {
+                        type: "array",
+                        description: "Alias objects. Each entry is TYPE:ID or {objectType|type, objectId|id|name, projectKey?}.",
+                        items: {
+                            anyOf: [
+                                { type: "string", pattern: "^[A-Z_]+:.+$", },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        object: { type: "string", },
+                                        objectType: { type: "string", },
+                                        type: { type: "string", },
+                                        objectId: { type: "string", },
+                                        id: { type: "string", },
+                                        name: { type: "string", },
+                                        projectKey: { type: "string", },
+                                    },
+                                },
+                            ],
+                        },
+                    },
+                    datasets: ZONE_OBJECT_IDS,
+                    recipes: ZONE_OBJECT_IDS,
+                    folders: ZONE_OBJECT_IDS,
+                    savedModels: ZONE_OBJECT_IDS,
+                    modelEvaluationStores: ZONE_OBJECT_IDS,
+                    streamingEndpoints: ZONE_OBJECT_IDS,
+                    labelingTasks: ZONE_OBJECT_IDS,
+                    knowledgeBanks: ZONE_OBJECT_IDS,
+                },
+            },
+        },
+    },
+};
+/**
+ * DSS stores a zone `position` sent on creation only while the project's
+ * manual zone positioning is off (with it on, DSS auto-places the new zone),
+ * and draws stored positions only while it is on.
+ */
+async function readManualPositioning(c, projectKey) {
+    try {
+        const settings = asRecord(await c.projects.getSettings(projectKey));
+        const display = asRecord(asRecord(settings?.settings)?.flowDisplaySettings);
+        return { manual: display?.zonesManualPositioning === true, };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message.split("\n")[0] : String(error), };
+    }
+}
+/** Read-modify-write of `flowDisplaySettings.zonesManualPositioning`, keeping every other setting. */
+async function setManualPositioning(c, projectKey, manual) {
+    const current = await c.projects.getSettings(projectKey);
+    const settings = asRecord(current.settings) ?? {};
+    await c.projects.setSettings(projectKey, {
+        ...current,
+        settings: {
+            ...settings,
+            flowDisplaySettings: {
+                ...asRecord(settings.flowDisplaySettings),
+                zonesManualPositioning: manual,
+            },
+        },
+    });
+}
+function enableManualPositioningCommand(projectKey) {
+    return `dss project settings-set --data '{"settings":{"flowDisplaySettings":{"zonesManualPositioning":true}}}'${projectKey ? ` --project-key ${projectKey}` : ""}`;
+}
 export const flowZoneCommands = withUsage("flow-zone", {
     list: {
         handler: async (c, _a, f) => {
@@ -165,36 +259,77 @@ export const flowZoneCommands = withUsage("flow-zone", {
     plan: {
         handler: async (c, _a, f) => {
             const pk = f["project-key"];
-            const [zones, topologyFingerprint,] = await Promise.all([
+            const [zones, { graph, topologyFingerprint, },] = await Promise.all([
                 c.flowZones.list(pk),
-                c.projects.topologyFingerprint(pk),
+                c.projects.flowTopology(pk),
             ]);
-            return flowZonePlanFromZones(zones, topologyFingerprint);
+            return {
+                ...flowZonePlanFromZones(zones, topologyFingerprint),
+                unassigned: flowZoneUnassignedItems(graph, zones),
+            };
         },
-        description: "Export current visual flow-zone organization as an organize-compatible plan.",
+        description: "Export current visual flow-zone organization as an organize-compatible plan. `unassigned` lists default-zone recipes and source objects still to place (recipe outputs follow their recipe); organize ignores it.",
         examples: ["dss flow-zone plan --project-key MYPROJ",],
     },
     organize: {
         handler: async (c, _a, f) => {
             const usage = commandUsage("flow-zone", "organize");
             const pk = f["project-key"];
-            const plan = readFlowZoneOrganizePlan(f, usage);
+            const parsed = readFlowZoneOrganizePlan(f, usage);
             const sync = f["sync"] === true;
             const validateObjects = f["validate-objects"] === true;
-            const [zones, topologyFingerprint,] = await Promise.all([
+            const recreateOnMove = f["recreate-on-move"] === true;
+            const [zones, { graph, topologyFingerprint, },] = await Promise.all([
                 c.flowZones.list(pk),
-                c.projects.topologyFingerprint(pk),
+                c.projects.flowTopology(pk),
             ]);
-            if (plan.topologyFingerprint && plan.topologyFingerprint !== topologyFingerprint) {
-                throw new ClientValidationError("Flow topology changed after this visual organization plan was generated.", "assertion_failed", "Regenerate the plan with dss flow-zone plan, then review it before applying.", { expected: plan.topologyFingerprint, actual: topologyFingerprint, });
+            if (parsed.topologyFingerprint && parsed.topologyFingerprint !== topologyFingerprint) {
+                throw new ClientValidationError("Flow topology changed after this visual organization plan was generated.", "assertion_failed", "Regenerate the plan with dss flow-zone plan, then review it before applying.", { expected: parsed.topologyFingerprint, actual: topologyFingerprint, });
             }
+            const plan = applyFlowZoneUnits(parsed, graph, zones, pk);
             const plannedItemKeys = flowZonePlanItemKeys(plan);
-            const planned = plan.zones.map((zonePlan) => flowZoneOrganizeStep(zonePlan, findFlowZoneForPlan(zones, zonePlan), sync, plannedItemKeys));
+            const targets = plan.zones.map((zonePlan) => ({
+                zonePlan,
+                existing: findFlowZoneForPlan(zones, zonePlan),
+            }));
+            const planned = targets.map(({ zonePlan, existing, }) => flowZoneOrganizeStep(zonePlan, existing, sync, plannedItemKeys));
+            const repositions = targets.flatMap(({ zonePlan, existing, }) => {
+                const requestedPosition = existing && flowZoneRepositionTarget(zonePlan, existing);
+                return requestedPosition
+                    ? [{ ...flowZoneSummary(existing), position: existing.position, requestedPosition, },]
+                    : [];
+            });
+            if (repositions.length > 0 && !recreateOnMove) {
+                throw new ClientValidationError(`DSS cannot move ${repositions.length} existing flow zone(s): its API applies a zone position only when the zone is created.`, "validation_failed", "Drop position from those zones, or pass --recreate-on-move to replace each with a new zone at the requested position (items, shared items, and metadata carry over; the zone id changes, so update scenarios that build the zone by id).", { zones: repositions, });
+            }
             const validation = validateObjects
                 ? await validateFlowZoneOrganizeObjects(c, plan, pk)
                 : undefined;
             if (validation)
                 throwFlowZoneValidationError(validation);
+            const writesPositions = repositions.length > 0
+                || targets.some(({ zonePlan, existing, }) => !existing && zonePlan.position !== undefined);
+            const positioning = writesPositions ? await readManualPositioning(c, pk) : undefined;
+            if (positioning?.error !== undefined) {
+                enqueueCliWarning({
+                    code: "zone_manual_positioning_unverified",
+                    message: `Could not read project settings (${positioning.error}). DSS stores a zone position only when manual zone positioning is off at creation, and draws it only when it is on.`,
+                    hint: enableManualPositioningCommand(pk),
+                });
+            }
+            else if (positioning?.manual === false) {
+                enqueueCliWarning({
+                    code: "zone_manual_positioning_disabled",
+                    message: "This plan sets zone positions, but the project's manual zone positioning is off, so DSS lays zones out automatically and the positions do not show.",
+                    hint: enableManualPositioningCommand(pk),
+                });
+            }
+            // With manual positioning on, DSS auto-places new zones and drops the
+            // requested position, so it is switched off while zones are created.
+            const suspendManualPositioning = positioning?.manual === true;
+            const positionReport = positioning?.error === undefined && positioning
+                ? { manualPositioning: positioning.manual, suspendManualPositioning, }
+                : {};
             const itemCount = plan.zones.reduce((count, zonePlan) => count + zonePlan.items.length, 0);
             const pruneItemCount = planned.reduce((count, step) => {
                 const pruneItems = Array.isArray(step.pruneItems) ? step.pruneItems : [];
@@ -208,10 +343,12 @@ export const flowZoneCommands = withUsage("flow-zone", {
                     projectKey: pk,
                     sync,
                     validateObjects,
+                    recreateOnMove,
                     topologyFingerprint,
                     zoneCount: plan.zones.length,
                     itemCount,
                     pruneItemCount,
+                    ...positionReport,
                     ...(validation ? { validation, } : {}),
                     planned,
                 };
@@ -219,54 +356,101 @@ export const flowZoneCommands = withUsage("flow-zone", {
             const currentZones = [...zones,];
             const created = [];
             const updated = [];
+            const recreated = [];
             const moved = [];
             const pruned = [];
-            for (const zonePlan of plan.zones) {
-                let zone = findFlowZoneForPlan(currentZones, zonePlan);
-                ensureFlowZonePlanTarget(zonePlan, zone);
-                const moveItems = flowZoneMoveDelta(zone, zonePlan.items);
-                const pruneItems = sync ? flowZonePruneItems(zone, plannedItemKeys) : [];
-                if (!zone) {
-                    zone = await c.flowZones.create({
-                        name: zonePlan.name,
-                        color: zonePlan.color,
-                        position: zonePlan.position,
-                        projectKey: pk,
+            const positionsNotApplied = [];
+            const checkPosition = (zone, requested) => {
+                if (requested && !flowZoneSamePosition(flowZoneCurrentPosition(zone), requested)) {
+                    positionsNotApplied.push({
+                        zoneId: zone.id,
+                        name: zone.name,
+                        requested,
+                        stored: zone.position,
                     });
-                    currentZones.push(zone);
-                    created.push(zone);
                 }
-                else {
-                    const patch = {
-                        ...(zonePlan.name && zonePlan.name !== zone.name ? { name: zonePlan.name, } : {}),
-                        ...(zonePlan.color && zonePlan.color !== zone.color ? { color: zonePlan.color, } : {}),
-                        ...(zonePlan.position !== undefined
-                            && !flowZoneSamePosition(flowZoneCurrentPosition(zone), zonePlan.position)
-                            ? { position: zonePlan.position, }
-                            : {}),
-                        projectKey: pk,
-                    };
-                    if (patch.name !== undefined || patch.color !== undefined || patch.position !== undefined) {
-                        zone = await c.flowZones.update(zone.id, patch);
-                        const index = currentZones.findIndex((candidate) => candidate.id === zone.id);
+            };
+            let failure;
+            if (suspendManualPositioning)
+                await setManualPositioning(c, pk, false);
+            try {
+                for (const zonePlan of plan.zones) {
+                    let zone = findFlowZoneForPlan(currentZones, zonePlan);
+                    ensureFlowZonePlanTarget(zonePlan, zone);
+                    const moveItems = flowZoneMoveDelta(zone, zonePlan.items);
+                    const pruneItems = sync ? flowZonePruneItems(zone, plannedItemKeys) : [];
+                    if (!zone) {
+                        zone = await c.flowZones.create({
+                            name: zonePlan.name,
+                            color: zonePlan.color,
+                            position: zonePlan.position,
+                            projectKey: pk,
+                        });
+                        currentZones.push(zone);
+                        created.push(zone);
+                        checkPosition(zone, zonePlan.position);
+                    }
+                    else {
+                        const name = zonePlan.name && zonePlan.name !== zone.name ? zonePlan.name : undefined;
+                        const color = zonePlan.color && zonePlan.color !== zone.color ? zonePlan.color : undefined;
+                        const replacedId = zone.id;
+                        const position = flowZoneRepositionTarget(zonePlan, zone);
+                        if (position) {
+                            const result = await c.flowZones.recreate(replacedId, {
+                                position,
+                                name,
+                                color,
+                                projectKey: pk,
+                            });
+                            zone = result.zone;
+                            recreated.push(result);
+                            checkPosition(zone, position);
+                        }
+                        else if (name !== undefined || color !== undefined) {
+                            zone = await c.flowZones.update(replacedId, { name, color, projectKey: pk, });
+                            updated.push(zone);
+                        }
+                        const index = currentZones.findIndex((candidate) => candidate.id === replacedId);
                         if (index !== -1)
                             currentZones[index] = zone;
-                        updated.push(zone);
+                    }
+                    if (moveItems.length > 0) {
+                        await c.flowZones.moveItems(zone.id, moveItems, pk);
+                        moved.push({ zoneId: zone.id, name: zone.name, items: moveItems, });
+                    }
+                    if (pruneItems.length > 0) {
+                        await c.flowZones.moveItems("default", pruneItems, pk);
+                        pruned.push({ zoneId: "default", fromZoneId: zone.id, name: zone.name, items: pruneItems, });
                     }
                 }
-                if (moveItems.length > 0) {
-                    await c.flowZones.moveItems(zone.id, moveItems, pk);
-                    moved.push({ zoneId: zone.id, name: zone.name, items: moveItems, });
+            }
+            catch (error) {
+                failure = error;
+            }
+            if (suspendManualPositioning) {
+                try {
+                    await setManualPositioning(c, pk, true);
                 }
-                if (pruneItems.length > 0) {
-                    await c.flowZones.moveItems("default", pruneItems, pk);
-                    pruned.push({ zoneId: "default", fromZoneId: zone.id, name: zone.name, items: pruneItems, });
+                catch (restoreError) {
+                    throw new ClientValidationError("Manual zone positioning was switched off to place zones and could not be switched back on.", "ambiguous_outcome", enableManualPositioningCommand(pk), failure instanceof Error ? { organizeError: failure.message, } : undefined, { cause: restoreError, });
                 }
             }
+            if (failure !== undefined)
+                throw failure;
             const topologyFingerprintAfter = await c.projects.topologyFingerprint(pk);
             if (topologyFingerprintAfter !== topologyFingerprint) {
                 throw new ClientValidationError("Visual flow-zone changes modified flow topology.", "assertion_failed", "Inspect the flow before applying any further organization changes.", { before: topologyFingerprint, after: topologyFingerprintAfter, });
             }
+            if (positionsNotApplied.length > 0) {
+                throw new ClientValidationError(`DSS did not store the requested position for ${positionsNotApplied.length} flow zone(s).`, "assertion_failed", "Items were organized; inspect the zones with dss flow-zone list.", {
+                    positionsNotApplied,
+                    created: created.map((zone) => zone.id),
+                    recreated: recreated.map(({ replacedZoneId, zone, }) => ({
+                        replacedZoneId,
+                        zoneId: zone.id,
+                    })),
+                });
+            }
             return {
                 organized: true,
                 action: "organize",
@@ -274,22 +458,33 @@ export const flowZoneCommands = withUsage("flow-zone", {
                 projectKey: pk,
                 sync,
                 validateObjects,
+                recreateOnMove,
                 topologyFingerprint,
                 topologyUnchanged: true,
                 zoneCount: plan.zones.length,
                 itemCount,
                 pruneItemCount,
+                ...positionReport,
                 created,
                 updated,
+                recreated,
                 moved,
                 pruned,
             };
         },
-        description: "Create/update flow zones and move objects from a declarative visual organization plan.",
+        description: "Create/update flow zones and move objects from a declarative plan. A recipe's outputs share its zone: listing either places both (impliedItems); splitting them is rejected. DSS stores a zone position only at creation: moving an existing zone needs --recreate-on-move (new id); manual zone positioning is switched off while zones are placed, then restored.",
         examples: [
             "dss flow-zone organize --file flow-zones.json --dry-run",
             `dss flow-zone organize --data '{"zones":[{"name":"Raw","color":"#64748b","datasets":["raw_orders"]}]}'`,
+            "dss flow-zone organize --file flow-zones.json --recreate-on-move --dry-run",
         ],
+        payloadSchema: {
+            stdin: true,
+            dataFlag: true,
+            dataFileFlag: true,
+            jsonShape: "object",
+            jsonSchema: FLOW_ZONE_ORGANIZE_PLAN_SCHEMA,
+        },
     },
     graph: {
         handler: (c, a, f) => {

package/dist/src/cli/commands/flow.d.ts

@@ -0,0 +1,5 @@
+import type { SchemaPropagationOptions } from "../../resources/flow.js";
+import type { CommandMeta } from "../types.js";
+/** Propagation options from flags; shared with the `--plan` builder. */
+export declare function schemaPropagationOptionsFromFlags(flags: Record<string, string | boolean>): SchemaPropagationOptions;
+export declare const flowCommands: Record<string, CommandMeta>;

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

@@ -0,0 +1,57 @@
+import { writeResponseToFile, } from "../../utils/response-file.js";
+import { splitCsvFlag, } from "../coerce.js";
+import { documentationTemplateFromFlags, runDocumentationCommand, taskWaitOptions, } from "../helpers/documentation.js";
+import { commandUsage, withUsage, } from "../syntax.js";
+import { requireArgs, } from "../usage.js";
+/** Propagation options from flags; shared with the `--plan` builder. */
+export function schemaPropagationOptionsFromFlags(flags) {
+    const excludedRecipes = splitCsvFlag(flags["stop-at"]);
+    const markAsOkRecipes = splitCsvFlag(flags["mark-ok"]);
+    return {
+        ...(flags["no-auto-rebuild"] === true ? { autoRebuild: false, } : {}),
+        ...(excludedRecipes.length > 0 ? { excludedRecipes, } : {}),
+        ...(markAsOkRecipes.length > 0 ? { markAsOkRecipes, } : {}),
+    };
+}
+export const flowCommands = withUsage("flow", {
+    "propagate-schema": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, commandUsage("flow", "propagate-schema"));
+            const opts = {
+                ...schemaPropagationOptionsFromFlags(f),
+                projectKey: f["project-key"],
+            };
+            if (f["wait"] === true) {
+                return c.flow.propagateSchemaAndWait(a[0], { ...opts, ...taskWaitOptions(f), });
+            }
+            return c.flow.propagateSchema(a[0], opts);
+        },
+        description: "Propagate a dataset's schema change through all downstream recipes and datasets (UI schema propagation). Rebuilds as needed unless --no-auto-rebuild; --stop-at / --mark-ok RECIPES limit it. Returns the DSS task; --wait waits. One recipe only: dss recipe update-schema.",
+        examples: [
+            "dss flow propagate-schema orders_raw --wait",
+            "dss flow propagate-schema orders_raw --stop-at compute_report --no-auto-rebuild --plan",
+        ],
+    },
+    "generate-documentation": {
+        handler: async (c, _a, f) => {
+            const pk = f["project-key"];
+            const task = await c.flow.generateDocumentation(documentationTemplateFromFlags(f), pk);
+            return runDocumentationCommand(c, f, task, (exportId) => c.flow.downloadDocumentation(exportId, pk));
+        },
+        description: "Generate the flow documentation (Word docx) from the DSS default template, an uploaded --template-file, or a template in a managed folder (--folder FOLDER_ID --path PATH). Returns the DSS future; --wait waits; --output PATH waits and downloads the document.",
+        examples: [
+            "dss flow generate-documentation --output flow.docx",
+            "dss flow generate-documentation --template-file template.docx --wait",
+        ],
+    },
+    "download-documentation": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, commandUsage("flow", "download-documentation"));
+            const output = f["output"];
+            const res = await c.flow.downloadDocumentation(a[0], f["project-key"]);
+            return { path: output, bytes: await writeResponseToFile(output, res), };
+        },
+        description: "Download a generated flow documentation by the exportId from a finished generate-documentation future.",
+        examples: ["dss flow download-documentation EXPORT_ID --output flow.docx",],
+    },
+});

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

@@ -4,6 +4,14 @@ import { planResult, } from "../output.js";
 import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
 export const futureCommands = withUsage("future", {
+    list: {
+        handler: (c, _a, f) => c.futures.list({
+            allUsers: f["all-users"] === true,
+            withScenarios: f["with-scenarios"] === true,
+        }),
+        description: "List long tasks in progress on the instance (DSS futures): your own, or every user's with --all-users; --with-scenarios adds running scenarios.",
+        examples: ["dss future list", "dss future list --all-users --with-scenarios",],
+    },
     get: {
         handler: (c, a) => {
             requireArgs(a, 1, commandUsage("future", "get"));

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

@@ -91,6 +91,12 @@ export const commands = {
     get "future"() {
         return require("./future.js").futureCommands;
     },
+    get "flow"() {
+        return require("./flow.js").flowCommands;
+    },
+    get "mlflow"() {
+        return require("./mlflow.js").mlflowCommands;
+    },
     get "flow-zone"() {
         return require("./flow-zone.js").flowZoneCommands;
     },

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

@@ -1,11 +1,43 @@
 import { mkdir, writeFile, } from "node:fs/promises";
 import { dirname, resolve, } from "node:path";
+import { ClientValidationError, DataikuError, } from "../../errors.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 { encodedProjectEndpoint, enqueueCliWarning, } from "../output.js";
 import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
+/**
+ * With an empty output schema DSS ends a dataset build DONE after writing no
+ * columns and no rows, without an error. Flag that after a successful build so
+ * it is not mistaken for real output.
+ */
+async function warnIfBuiltDatasetHasNoColumns(c, target, targetType, success, projectKey) {
+    if (!success || targetType !== "DATASET")
+        return;
+    let schema;
+    try {
+        schema = await c.datasets.schema(target, projectKey);
+    }
+    catch (error) {
+        if (!(error instanceof DataikuError || error instanceof ClientValidationError))
+            throw error;
+        enqueueCliWarning({
+            code: "built_dataset_schema_unchecked",
+            dataset: target,
+            error: error.message.split("\n")[0],
+            hint: "The build succeeded but the dataset schema could not be read to check it is not empty.",
+        });
+        return;
+    }
+    if (schema.columns.length > 0)
+        return;
+    enqueueCliWarning({
+        code: "built_dataset_has_no_columns",
+        dataset: target,
+        hint: "The build succeeded but the dataset schema is empty, so no data was written. For a visual or SQL query recipe, run dss recipe update-schema RECIPE (or rebuild with --auto-update-schema).",
+    });
+}
 // ---------------------------------------------------------------------------
 // Utility helpers
 // ---------------------------------------------------------------------------
@@ -236,7 +268,7 @@ export const jobCommands = withUsage("job", {
             await writeFile(outputPath, log.endsWith("\n") ? log : `${log}\n`, "utf-8");
             return outputPath;
         },
-        description: "Get public API job log output. Use --errors-only (or --log-filter errors) to surface just error/traceback lines, and --output PATH to write the log to a file (stdout returns the path). --log-id is accepted for UI parity but DSS API-key auth cannot select browser-only cat-activity-log files.",
+        description: "Get public API job log output; find why a job failed. Use --errors-only (or --log-filter errors) to surface just error/traceback lines, and --output PATH to write the log to a file (stdout returns the path). --log-id is accepted for UI parity but DSS API-key auth cannot select browser-only cat-activity-log files.",
         examples: [
             "dss job log JOB_ID",
             "dss job log JOB_ID --activity main --max-log-lines 200",
@@ -270,6 +302,7 @@ export const jobCommands = withUsage("job", {
             requireArgs(a, 1, commandUsage("job", "build"));
             const pk = f["project-key"];
             const options = {
+                autoUpdateSchema: f["auto-update-schema"] === true,
                 buildMode: f["build-mode"],
                 partition: f["partition"],
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
@@ -288,11 +321,13 @@ export const jobCommands = withUsage("job", {
                 };
             }
             if (f["wait"] === true) {
-                return c.jobs.buildAndWait(a[0], { ...options, projectKey: pk, });
+                const result = await c.jobs.buildAndWait(a[0], { ...options, projectKey: pk, });
+                await warnIfBuiltDatasetHasNoColumns(c, a[0], options.targetType, result.success, pk);
+                return result;
             }
             return c.jobs.build(a[0], { ...options, projectKey: pk, });
         },
-        description: "Start a dataset or managed-folder build, optionally waiting for completion.",
+        description: "Start a dataset or managed-folder build, optionally waiting for completion. --auto-update-schema lets DSS update each recipe's output schema before it runs.",
         examples: [
             "dss job build orders",
             "dss job build orders --build-mode RECURSIVE_BUILD --wait",
@@ -304,6 +339,7 @@ export const jobCommands = withUsage("job", {
             requireArgs(a, 1, commandUsage("job", "build-and-wait"));
             const pk = f["project-key"];
             const options = {
+                autoUpdateSchema: f["auto-update-schema"] === true,
                 buildMode: f["build-mode"],
                 includeLogs: f["include-logs"] === true,
                 logFilter: jobLogFilterFromFlag(f["log-filter"]),
@@ -325,9 +361,11 @@ export const jobCommands = withUsage("job", {
                     method: "POST",
                 };
             }
-            return c.jobs.buildAndWait(a[0], { ...options, projectKey: pk, });
+            const result = await c.jobs.buildAndWait(a[0], { ...options, projectKey: pk, });
+            await warnIfBuiltDatasetHasNoColumns(c, a[0], options.targetType, result.success, pk);
+            return result;
         },
-        description: "Build a dataset or managed folder and wait for completion.",
+        description: "Build a dataset or managed folder and wait for completion. --auto-update-schema lets DSS update each recipe's output schema before it runs; a successful dataset build that leaves an empty schema emits a built_dataset_has_no_columns warning. A managed dataset no recipe produces fails (exit 4).",
         examples: [
             "dss job build-and-wait orders",
             "dss job build-and-wait orders --include-logs --log-filter stdout --summary",

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

@@ -1,5 +1,6 @@
+import { unknownJsonInput, } from "../coerce.js";
 import { commandUsage, withUsage, } from "../syntax.js";
-import { requireArgs, } from "../usage.js";
+import { requireArgs, UsageError, } from "../usage.js";
 export const metricsCommands = withUsage("metrics", {
     "dataset-get": {
         handler: (c, a, f) => {
@@ -17,6 +18,25 @@ export const metricsCommands = withUsage("metrics", {
         description: "Compute the DSS-configured metrics for a dataset.",
         examples: ["dss metrics dataset-compute customers",],
     },
+    "dataset-run-checks": {
+        handler: (c, a, f) => {
+            const data = unknownJsonInput(f);
+            const checks = data && typeof data === "object" && "checks" in data ? data.checks : undefined;
+            if (data !== undefined && !Array.isArray(checks)) {
+                throw new UsageError('--data must be {"checks": [...]}.', "validation_failed");
+            }
+            return c.metrics.runDatasetChecks(a[0], {
+                projectKey: f["project-key"],
+                partitions: f["partitions"],
+                ...(Array.isArray(checks) ? { checks, } : {}),
+            });
+        },
+        description: 'Run the checks configured on a dataset, or the {"checks": [...]} definitions passed as JSON, and return their outcomes.',
+        examples: [
+            "dss metrics dataset-run-checks customers",
+            "dss metrics dataset-run-checks customers --data-file checks.json",
+        ],
+    },
     "dataset-history": {
         handler: (c, a, f) => {
             requireArgs(a, 2, commandUsage("metrics", "dataset-history"));

package/dist/src/cli/commands/ml-task.d.ts

@@ -1,2 +1,7 @@
+import type { MlTaskCreateFields, MlTaskReguessOptions } from "../../resources/ml-tasks.js";
 import type { CommandMeta } from "../types.js";
+/** Task definition flags shared by `create`, `create-for-dataset`, and their --plan. */
+export declare function mlTaskFieldsFromFlags(flags: Record<string, string | boolean>, usage: string): MlTaskCreateFields;
+/** `reguess` flags → SDK options (shared with --plan). */
+export declare function mlTaskReguessOptionsFromFlags(flags: Record<string, string | boolean>): MlTaskReguessOptions;
 export declare const mlTaskCommands: Record<string, CommandMeta>;