dataiku-sdk 3.7.0 → 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/job.js

@@ -1,5 +1,6 @@
 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";
@@ -14,8 +15,22 @@ import { requireArgs, UsageError, } from "../usage.js";
 async function warnIfBuiltDatasetHasNoColumns(c, target, targetType, success, projectKey) {
     if (!success || targetType !== "DATASET")
         return;
-    const schema = await c.datasets.schema(target, projectKey).catch(() => undefined);
-    if (!schema || schema.columns.length > 0)
+    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",
@@ -350,7 +365,7 @@ export const jobCommands = withUsage("job", {
             await warnIfBuiltDatasetHasNoColumns(c, a[0], options.targetType, result.success, pk);
             return result;
         },
-        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.",
+        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/recipe.d.ts

@@ -1,4 +1,7 @@
+import { recipeCreateWarnings } from "../../resources/recipe-create.js";
 import type { CommandMeta } from "../types.js";
+/** Queue the stderr warnings for `recipe create` options (also used by `--plan` and `--dry-run`). */
+export declare function enqueueRecipeCreateWarnings(options: Parameters<typeof recipeCreateWarnings>[0]): void;
 /** Maps `recipe create` flags to SDK options; shared by the handler and `--plan`. */
 export declare function recipeCreateOptionsFromFlags(f: Record<string, string | boolean>): {
     type: string;
@@ -16,6 +19,7 @@ export declare function recipeCreateOptionsFromFlags(f: Record<string, string |
     orderBy?: string | undefined;
     formula?: string | undefined;
     filter?: string | undefined;
+    stepOrder?: string[] | undefined;
     projectKey: string | undefined;
     aggregate?: string[] | undefined;
     dropColumns?: string[] | undefined;

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

@@ -2,7 +2,7 @@ import { readFileSync, } from "node:fs";
 import { writeFile, } from "node:fs/promises";
 import { join, } from "node:path";
 import { ClientValidationError, DataikuError, } from "../../errors.js";
-import { recipeOutputSchemaIsComputable, schemaUpdateComputableId, schemaUpdateIsPending, } from "../../resources/recipe-create.js";
+import { recipeCreateWarnings, recipeOutputSchemaIsComputable, schemaUpdateComputableId, schemaUpdateIsPending, } from "../../resources/recipe-create.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { jobLogFilterFromFlag, jsonInput, maxLogLinesFromFlags, normalizeLineEndings, num, recipeInputDatasetsFromFlags, requiredJsonInput, requiredStringFlag, rewritePairsFromFlags, sha256Hex, splitCsvFlag, stableHash, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
@@ -107,6 +107,19 @@ function formatLineDiff(remoteName, localPath, remoteContent, localContent) {
     }
     return lines.join("\n");
 }
+const PREPARE_STEP_FLAGS = {
+    "rename": "rename",
+    "fill-empty": "fillEmpty",
+    "formula": "formula",
+    "filter": "filter",
+    "drop-columns": "dropColumns",
+    "keep-columns": "keepColumns",
+};
+/** Queue the stderr warnings for `recipe create` options (also used by `--plan` and `--dry-run`). */
+export function enqueueRecipeCreateWarnings(options) {
+    for (const warning of recipeCreateWarnings(options))
+        enqueueCliWarning(warning);
+}
 /** Maps `recipe create` flags to SDK options; shared by the handler and `--plan`. */
 export function recipeCreateOptionsFromFlags(f) {
     const type = f["type"];
@@ -145,6 +158,11 @@ export function recipeCreateOptionsFromFlags(f) {
         fuzzyDistance = normalized;
     }
     const fuzzyThreshold = num(f["fuzzy-threshold"], "--fuzzy-threshold");
+    // Prepare option groups run in the order their flags were typed (object keys keep first-use order).
+    const stepOrder = Object.keys(f).flatMap((flag) => {
+        const kind = Object.hasOwn(PREPARE_STEP_FLAGS, flag) ? PREPARE_STEP_FLAGS[flag] : undefined;
+        return kind ? [kind,] : [];
+    });
     const payload = {
         type,
         name,
@@ -167,6 +185,7 @@ export function recipeCreateOptionsFromFlags(f) {
         ...(typeof f["filter"] === "string" ? { filter: f["filter"], } : {}),
         ...csvOption("dropColumns", f["drop-columns"]),
         ...csvOption("keepColumns", f["keep-columns"]),
+        ...(stepOrder.length > 0 ? { stepOrder, } : {}),
         projectKey: pk,
     };
     return payload;
@@ -330,6 +349,7 @@ export const recipeCommands = withUsage("recipe", {
     create: {
         handler: async (c, _a, f) => {
             const payload = recipeCreateOptionsFromFlags(f);
+            enqueueRecipeCreateWarnings(payload);
             const name = payload.name;
             const pk = payload.projectKey;
             const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
@@ -369,6 +389,23 @@ export const recipeCommands = withUsage("recipe", {
                     objectId: createdName,
                     objectType: "RECIPE",
                 },], pk);
+            if (created.requestedName) {
+                // DSS appends _N when the requested name is taken; any other difference is DSS naming
+                // the recipe itself. The public API has no recipe rename.
+                const suffix = createdName.startsWith(`${created.requestedName}_`)
+                    ? createdName.slice(created.requestedName.length + 1)
+                    : "";
+                const nameTaken = /^\d+$/.test(suffix);
+                enqueueCliWarning({
+                    code: "recipe_renamed",
+                    requestedName: created.requestedName,
+                    recipe: createdName,
+                    reason: nameTaken ? "name_taken" : "dss_chose_name",
+                    hint: nameTaken
+                        ? `A recipe named ${created.requestedName} already exists; use ${createdName} in follow-up commands.`
+                        : `DSS ignored the requested name; use ${createdName} in follow-up commands.`,
+                });
+            }
             if (created.outputSchemaUpdateError) {
                 enqueueCliWarning({
                     code: "recipe_output_schema_not_computed",

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

@@ -1,3 +1,4 @@
+import { findWikiAttachment, statWikiAttachmentFile, wikiAttachmentNotFound, wikiAttachments, } from "../../resources/wiki.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
 import { jsonInput, textInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
@@ -117,6 +118,61 @@ export const wikiCommands = withUsage("wiki", {
         description: "Delete a wiki article.",
         examples: ["dss wiki delete ARTICLE_ID --dry-run",],
     },
+    attach: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 2, commandUsage("wiki", "attach"));
+            const pk = f["project-key"];
+            const file = await statWikiAttachmentFile(a[1]);
+            if (executionMode(f).dryRun) {
+                const current = await c.wiki.get(a[0], pk);
+                return {
+                    dryRun: true,
+                    action: "attach",
+                    resource: "wiki",
+                    article: a[0],
+                    file,
+                    current: wikiAttachments(current),
+                };
+            }
+            const result = await c.wiki.attach(a[0], a[1], pk);
+            return { attached: result.attachment.smartId, resource: "wiki", ...result, };
+        },
+        description: "Upload a local file and attach it to a wiki article; returns its smartId.",
+        examples: ["dss wiki attach ARTICLE_ID ./diagram.png --dry-run",],
+    },
+    detach: {
+        handler: async (c, a, f) => {
+            requireArgs(a, 2, commandUsage("wiki", "detach"));
+            const pk = f["project-key"];
+            const ifExists = f["if-exists"] === true;
+            const dryRun = executionMode(f).dryRun;
+            if (dryRun || ifExists) {
+                const current = ifExists
+                    ? await readIfExists(() => c.wiki.get(a[0], pk))
+                    : await c.wiki.get(a[0], pk);
+                const attachment = current && findWikiAttachment(current, a[1]);
+                if (!current || !attachment) {
+                    if (!ifExists && current)
+                        throw wikiAttachmentNotFound(current, a[1]);
+                    return skipResult("wiki", a[1], "missing", { article: a[0], });
+                }
+                if (dryRun) {
+                    return {
+                        dryRun: true,
+                        action: "detach",
+                        resource: "wiki",
+                        article: a[0],
+                        smartId: a[1],
+                        current: attachment,
+                    };
+                }
+            }
+            const result = await c.wiki.detach(a[0], a[1], pk);
+            return { resource: "wiki", ...result, };
+        },
+        description: "Remove one attachment from a wiki article by smartId.",
+        examples: ["dss wiki detach ARTICLE_ID SMART_ID --if-exists",],
+    },
     "update-settings": {
         handler: async (c, _a, f) => {
             const pk = f["project-key"];

package/dist/src/cli/contract.js

@@ -411,6 +411,8 @@ function payloadJsonSchema(payloadSchema) {
     if (payloadSchema.contentType === "text/plain") {
         return { type: "string", contentMediaType: "text/plain", };
     }
+    if (payloadSchema.jsonSchema)
+        return payloadSchema.jsonSchema;
     return payloadSchema.jsonShape === "array"
         ? { type: "array", items: true, }
         : { type: "object", additionalProperties: true, };
@@ -722,7 +724,7 @@ function inferSideEffect(resource, action) {
     }
     if (READ_ACTIONS.has(action))
         return "read";
-    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout|add|remove|publish|activate|deploy|import|export|preload|upgrade|start|stop|restart|duplicate|put|rename|reply|compute|organize)/
+    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout|add|remove|publish|activate|deploy|import|export|preload|upgrade|start|stop|restart|duplicate|put|rename|reply|compute|organize|attach|detach)/
         .test(action)
         // Compound actions whose mutating verb is a suffix (e.g. permissions-set,
         // dataset-compute, saved-model external-metadata-put).
@@ -876,6 +878,8 @@ export function supportsCleanupLedger(resource, action) {
 const EXPLICIT_DESTRUCTIVE_KEYS = {
     "dataset.upload-file": true,
     "sql.query": true,
+    // Detaching drops the attachment from the article; no public route restores it.
+    "wiki.detach": true,
     // Plugin dev-Git and content deletions discard work with no undo route.
     "plugin.delete": true,
     "plugin.delete-git-remote": true,
@@ -961,8 +965,10 @@ function inferIdempotency(resource, sideEffect, action, syntax) {
     if (action.startsWith("create") && syntaxHasFlag(syntax, "if-not-exists")) {
         return "if-not-exists";
     }
-    if (action.startsWith("delete") && syntaxHasFlag(syntax, "if-exists"))
+    if ((action.startsWith("delete") || `${resource}.${action}` === "wiki.detach")
+        && syntaxHasFlag(syntax, "if-exists")) {
         return "if-exists";
+    }
     if (`${resource}.${action}` === "app.set-manifest-version")
         return "none";
     // `app delete-instance` converges without an `--if-exists` flag: an absent
@@ -1062,6 +1068,8 @@ export function buildRegistryEntry(resource, action, meta) {
     const payloadSchema = meta.payloadSchema
         ?? EXPLICIT_REGISTRY_OVERRIDES[registryKey(resource, action)]?.payloadSchema
         ?? inferPayloadSchema(inputContract);
+    // The precise JSON Schema is published once, as `schemas.input`.
+    const { jsonSchema: _jsonSchema, ...payloadSummary } = payloadSchema ?? {};
     const examplePayload = meta.examplePayload
         ?? EXPLICIT_REGISTRY_OVERRIDES[registryKey(resource, action)]?.examplePayload;
     const inferredCleanupCommand = meta.cleanupCommand
@@ -1126,7 +1134,7 @@ export function buildRegistryEntry(resource, action, meta) {
         optionalFlags: uniqueOptionalFlags,
         ...(requiredOneOf.length > 0 ? { requiredOneOf, } : {}),
         ...(inputGroups.length > 0 ? { requiredInputGroups: inputGroups, } : {}),
-        ...(payloadSchema ? { payloadSchema, } : {}),
+        ...(payloadSchema ? { payloadSchema: payloadSummary, } : {}),
         get schemas() {
             return schemas ??= buildCommandSchemas(resource, action, flagMetadata, uniqueRequiredFlags, requiredOneOf, payloadSchema, outputShape, meta.usage);
         },

package/dist/src/cli/doctor.js

@@ -11,6 +11,8 @@ export function errorDetails(error) {
             retryable: error.retryable,
             status: error.status,
             statusText: error.statusText,
+            message: error.message,
+            retryHint: error.retryHint,
         };
     }
     return { message: error instanceof Error ? error.message : String(error), };