dataiku-sdk 3.4.0 → 3.6.0

package/dist/src/cli/contract.js

@@ -6,19 +6,24 @@ import { DataikuError, } from "../errors.js";
 import actionOutputSchemasMetadata from "../generated/action-output-schemas.json" with { type: "json"
 };
 import { APP_MANIFEST_CONCURRENCY_CONTROL, } from "../resources/applications.js";
+import { buildDatasetCreateBody, } from "../resources/datasets.js";
+import { validatePluginDestinationPath, validatePluginPath, } from "../resources/plugins.js";
 import { encodeLibraryPath, PROJECT_LIBRARY_CONCURRENCY_CONTROL, validateLibraryDestinationPath, validateLibraryName, validateLibraryPath, } from "../resources/project-library.js";
+import { buildRecipeCreateRequest, } from "../resources/recipes.js";
 import { encodeGitReferencePath, validateGitReferencePath, } from "../utils/git-reference.js";
-import { jobBuildTargetTypeFromFlags, json, jsonInput, num, parseBooleanOption, parseJsonObject, recipeInputDatasetsFromFlags, requiredJsonInput, rewritePairsFromFlags, schemaColumnsInput, sha256Hex, stableHash, stringField, textInput, } from "./coerce.js";
+import { jobBuildTargetTypeFromFlags, json, jsonInput, num, parseBooleanOption, parseJsonObject, requiredJsonInput, rewritePairsFromFlags, schemaColumnsInput, sha256Hex, stableHash, stringField, textInput, } from "./coerce.js";
 import { parseCodeRunIntegerFlag, resolveCodeInputWithSource, } from "./commands/code.js";
 import { commands, } from "./commands/index.js";
 import { projectLibraryPutPayload, } from "./commands/project-library.js";
+import { recipeCreateOptionsFromFlags, } from "./commands/recipe.js";
 import { resolveSqlQueryInvocation, } from "./commands/sql.js";
-import { dataikuEnvironmentEnabled, } from "./env.js";
-import { BOOLEAN_FLAGS, executionMode, FLAG_ALIASES, KNOWN_LONG_FLAGS, SHORT_FLAGS, } from "./flags.js";
+import { ambientProjectKey, } from "./env.js";
+import { BOOLEAN_FLAGS, executionMode, FLAG_ALIASES, SHORT_FLAGS, } from "./flags.js";
 import { flowZoneColor, flowZoneMoveItems, flowZoneName, } from "./helpers/flow-zone.js";
 import { recipeBackupPath, recipeRunShouldWait, } from "./helpers/recipe.js";
 import { encodedProjectEndpointForPlan, planResult, } from "./output.js";
 import { resolveLoginCredentials, } from "./runtime.js";
+import { commandSyntax, commandSyntaxTree, commandUsage, renderNodes, syntaxCommandWords, syntaxHasFlag, } from "./syntax.js";
 import { inferRequiresProject, requireArgs, UsageError, } from "./usage.js";
 import { AGENT_CONTRACT_SCHEMA_ID, AGENT_CONTRACT_VERSION, cliVersionResult, JSON_SCHEMA_DRAFT, } from "./version.js";
 function codeEnvWait(flags) {
@@ -81,7 +86,6 @@ export const AUTH_ACTIONS = {
             saveCredentials({ url, apiKey, projectKey, ...tlsSettings, });
             return { saved: true, path: credentialsPath, };
         },
-        usage: "dss auth login --url URL --api-key KEY [--project-key KEY] [--insecure] [--ca-cert PATH]",
         description: "Validate and save DSS credentials from flags or environment variables.",
         examples: [
             "dss auth login --url https://dss.example.com --api-key YOUR_KEY",
@@ -238,7 +242,7 @@ const AUTHENTICATED_AGENT_FLAGS = [
     "insecure",
     "ca-cert",
 ];
-export const COMMANDS_USAGE = "dss commands run [--fields PATHS] [--output PATH]";
+export const COMMANDS_USAGE = commandUsage("commands", "run");
 const COMMANDS_DESCRIPTION = "Print a compact resource/action summary by default; use --fields for scoped command metadata or --output PATH to export the full registry without sending it through stdout.";
 const COMMANDS_EXAMPLES = [
     "dss commands run",
@@ -248,28 +252,28 @@ const COMMANDS_EXAMPLES = [
     "dss commands run --output commands.json",
 ];
 export const AGENT_CONTRACT_COMMAND = "dss agent contract";
-export const AGENT_CONTRACT_USAGE = "dss agent contract [--fields PATHS]";
+export const AGENT_CONTRACT_USAGE = commandUsage("agent", "contract");
 const AGENT_CONTRACT_DESCRIPTION = "Print the versioned JSON agent contract; scope bootstrap fields, use commands.actions to enumerate the surface, and read schemas only when needed.";
 const AGENT_CONTRACT_EXAMPLES = [
     "dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility",
     "dss agent contract --fields commands.actions",
 ];
-const VERSION_USAGE = "dss version";
+const VERSION_USAGE = commandUsage("version", "run");
 const VERSION_DESCRIPTION = "Print the CLI version, checkout/build revisions, load source, runtime, and stale-build status as JSON.";
 const VERSION_EXAMPLES = ["dss version", "dss --version",];
-const INSTALL_SKILL_USAGE = "dss install-skill [--global] [--agent NAME] [--target PATH] [--list-agents] [--dry-run] [--plan]";
+const INSTALL_SKILL_USAGE = commandUsage("install-skill", "run");
 const INSTALL_SKILL_DESCRIPTION = "Report missing/stale/current skill status and atomically install changed dataiku-dss agent skills.";
 const INSTALL_SKILL_EXAMPLES = [
     "dss install-skill --list-agents",
     "dss install-skill --agent omp --dry-run",
 ];
-export const CLEANUP_USAGE = "dss cleanup --file PATH [--dry-run|--apply] [--continue-on-error]";
+export const CLEANUP_USAGE = commandUsage("cleanup", "run");
 const CLEANUP_DESCRIPTION = "Replay cleanup entries in reverse order; failures include structured code/category/exitCode/retryability summaries.";
 const CLEANUP_EXAMPLES = [
     "dss cleanup --file cleanup.jsonl",
     "dss cleanup --file cleanup.jsonl --apply",
 ];
-const FIXTURES_USAGE = "dss fixtures [--project-key KEY] [--allow-types CSV]";
+const FIXTURES_USAGE = commandUsage("fixtures", "run");
 const FIXTURES_DESCRIPTION = "Discover safe live-test fixtures for agent workflows.";
 const FIXTURES_EXAMPLES = [
     "dss fixtures",
@@ -500,10 +504,9 @@ function shortFlagPattern(flags) {
  * use an actionless prefix, while real command paths that spell `run` in their
  * usage (e.g. `dss commands run`) keep the action token.
  */
-function argvPrefix(resource, action, usage) {
-    const usageTokens = usage.split(/\s+/).filter((token) => token.length > 0);
-    const head = usageTokens.slice(1);
-    return head[0] === resource && head[1] === action ? [resource, action,] : [resource,];
+function argvPrefix(resource, action) {
+    const words = syntaxCommandWords(commandSyntaxTree(resource, action) ?? []);
+    return words[0] === resource && words[1] === action ? [resource, action,] : [resource,];
 }
 /**
  * Describe one invocation as a canonical argv token array. Agents emit the
@@ -520,7 +523,7 @@ function argvPrefix(resource, action, usage) {
  * negative-number and `--` separator rules.
  */
 function argvJsonSchema(resource, action, flags, usage, requiredFlags, requiredOneOf) {
-    const prefix = argvPrefix(resource, action, usage);
+    const prefix = argvPrefix(resource, action);
     const aliases = {};
     for (const flag of flags) {
         aliases[flag.name] = flag.aliases ?? [];
@@ -528,7 +531,8 @@ function argvJsonSchema(resource, action, flags, usage, requiredFlags, requiredO
     const booleanNames = flags.filter((flag) => flag.kind === "boolean")
         .flatMap((flag) => [flag.name, ...(flag.aliases ?? []),]);
     const valueFlags = flags.filter((flag) => flag.kind === "value");
-    const requiredPositionals = requiredPlanPositionals(usage);
+    const requiredPositionals = commandSyntax(resource, action).positionalArguments
+        .filter((positional) => positional.required).map((positional) => positional.name);
     const itemSchemas = [
         { not: { pattern: "^-", }, },
         { const: "-", },
@@ -659,45 +663,6 @@ const EXPLICIT_REGISTRY_OVERRIDES = {
         examplePayload: { article: { name: "Updated article", }, },
     },
 };
-function extractUsageFlags(usage) {
-    const flags = [];
-    for (const match of usage.matchAll(/--([a-z0-9-]+)/g)) {
-        flags.push(FLAG_ALIASES[match[1]] ?? match[1]);
-    }
-    return uniqueStrings(flags).filter((flag) => KNOWN_LONG_FLAGS.has(flag));
-}
-function extractPositionalArguments(usage) {
-    const positionals = [];
-    const add = (name, required) => {
-        const existing = positionals.find((positional) => positional.name === name);
-        if (existing)
-            existing.required ||= required;
-        else
-            positionals.push({ name, required, });
-    };
-    for (const match of usage.matchAll(/<([^>]+)>/g)) {
-        const before = usage.slice(0, match.index);
-        const openParen = before.lastIndexOf("(");
-        const insideParen = openParen > before.lastIndexOf(")");
-        const closeParen = insideParen ? usage.indexOf(")", match.index) : -1;
-        const group = closeParen >= 0 ? usage.slice(openParen + 1, closeParen) : "";
-        const hasFlagAlternative = group.split("|").some((alternative) => alternative.includes("--"));
-        const required = before.lastIndexOf("[") <= before.lastIndexOf("]")
-            && !hasFlagAlternative;
-        add(match[1], required);
-    }
-    for (const suffix of usage.split("[").slice(1)) {
-        const candidate = suffix.split("]", 1)[0];
-        if (candidate && /^[A-Za-z][A-Za-z0-9_-]*$/.test(candidate))
-            add(candidate, false);
-    }
-    for (const group of topLevelParenGroups(usage)) {
-        const candidate = group.split("|", 1)[0]?.trim();
-        if (candidate && /^[A-Z][A-Z0-9_-]*$/.test(candidate))
-            add(candidate, false);
-    }
-    return positionals;
-}
 const COMMAND_REQUIRED_INPUT_GROUPS = {
     "notebook.unload-jupyter": [
         {
@@ -769,7 +734,7 @@ function inferSideEffect(resource, action) {
     // LLM Mesh completions/embeddings invoke the LLM provider (cost-bearing,
     // arbitrary-prompt execution); the verb shapes match no mutating pattern
     // and would fall through to read, wrongly rejecting --plan. Knowledge-bank
-    // search stays a READ per Main's preservation directive.
+    // search stays read: it only queries an existing index.
     if (resource === "llm" && (action === "completions" || action === "embeddings")) {
         return "write";
     }
@@ -856,102 +821,6 @@ function inferOutputShape(resource, action) {
         return "string";
     return "object";
 }
-export function inferInputContract(usage) {
-    return {
-        ...(usage.includes("--stdin") ? { stdin: true, } : {}),
-        ...(usage.includes("--data ") || usage.includes("--data JSON") ? { dataFlag: true, } : {}),
-        ...(usage.includes("--data-file") ? { dataFileFlag: true, } : {}),
-    };
-}
-function stripOptionalUsageGroups(usage) {
-    return usage.replace(/\[[^\]]*\]/g, " ");
-}
-function stripAllUsageGroups(usage) {
-    return usage.replace(/\[[^\]]*\]/g, " ").replace(/\([^)]*\)/g, " ");
-}
-function topLevelParenGroups(usage) {
-    const groups = [];
-    let depth = 0;
-    let current = "";
-    for (const char of usage) {
-        if (char === "(") {
-            if (depth > 0)
-                current += char;
-            else
-                current = "";
-            depth++;
-        }
-        else if (char === ")") {
-            depth--;
-            if (depth === 0)
-                groups.push(current);
-            else
-                current += char;
-        }
-        else if (depth > 0) {
-            current += char;
-        }
-    }
-    return groups;
-}
-function splitTopLevelChoices(group) {
-    const parts = [];
-    let depth = 0;
-    let current = "";
-    for (let index = 0; index < group.length; index++) {
-        const char = group[index];
-        if (char === "[" || char === "(")
-            depth++;
-        else if (char === "]" || char === ")")
-            depth--;
-        const nextAlternative = group.slice(index + 1).trimStart();
-        if (char === "|" && depth === 0 && nextAlternative.startsWith("--")) {
-            parts.push(current);
-            current = "";
-        }
-        else {
-            current += char;
-        }
-    }
-    parts.push(current);
-    return parts;
-}
-function flagsInUsageFragment(fragment) {
-    return extractUsageFlags(fragment.replace(/\[[^\]]*\]/g, " "));
-}
-/**
- * Split required usage flags into unconditional flags and required choice
- * groups. A required `(--a X | --b Y)` group becomes a requiredOneOf entry
- * (at least one alternative; an alternative listing several flags must be
- * supplied together) instead of marking every flag as unconditionally required.
- */
-function deriveRequiredUsage(usage) {
-    const requiredFlags = extractUsageFlags(stripAllUsageGroups(usage));
-    const requiredOneOf = [];
-    for (const group of topLevelParenGroups(usage)) {
-        const alternatives = splitTopLevelChoices(group);
-        if (alternatives.length <= 1) {
-            requiredFlags.push(...flagsInUsageFragment(group));
-            continue;
-        }
-        const oneOf = alternatives
-            .map((alternative) => flagsInUsageFragment(alternative))
-            .filter((alternativeFlags) => alternativeFlags.length > 0);
-        // A group mixing a positional alternative with flags (e.g. sql query's
-        // `(SQL | --sql QUERY | --sql-file PATH | --sql - | --stdin)`) cannot be
-        // expressed as a flag-only choice: filtering out the flagless alternative
-        // would falsely require one of the flags. Omit the group from the flag
-        // contract entirely; the handler stays the runtime authority.
-        if (alternatives.some((alternative) => flagsInUsageFragment(alternative).length === 0)) {
-            continue;
-        }
-        if (oneOf.length > 1)
-            requiredOneOf.push({ oneOf, });
-        else if (oneOf.length === 1)
-            requiredFlags.push(...oneOf[0]);
-    }
-    return { requiredFlags: uniqueStrings(requiredFlags), requiredOneOf, };
-}
 const GLOBAL_FLAG_VALUE_HINTS = {
     url: { valueType: "URL", },
     fields: { valueType: "CSV", },
@@ -967,22 +836,6 @@ const GLOBAL_FLAG_VALUE_HINTS = {
     standard: { valueType: "JSON", },
     until: { valueType: "STATE", },
 };
-/** Derive a value placeholder (and enum members) for each value flag from its usage token. */
-function extractFlagValueHints(usage) {
-    const hints = new Map();
-    for (const match of usage.matchAll(/--([a-z0-9-]+)\s+([A-Za-z][A-Za-z0-9_-]*(?:\|[A-Za-z][A-Za-z0-9_-]*)+)(?![A-Za-z0-9_=-])/g)) {
-        const flag = FLAG_ALIASES[match[1]] ?? match[1];
-        if (!hints.has(flag)) {
-            hints.set(flag, { valueType: "enum", enumValues: match[2].split("|"), });
-        }
-    }
-    for (const match of usage.matchAll(/--([a-z0-9-]+)\s+(<[^>]+>|[A-Z][A-Za-z0-9_]*)/g)) {
-        const flag = FLAG_ALIASES[match[1]] ?? match[1];
-        if (!hints.has(flag))
-            hints.set(flag, { valueType: match[2], });
-    }
-    return hints;
-}
 function inferPayloadSchema(inputContract) {
     if (!inputContract.stdin && !inputContract.dataFlag && !inputContract.dataFileFlag) {
         return undefined;
@@ -1036,11 +889,11 @@ function cleanupCommandFromDeleteUsage(resource, action) {
         : action === "create-instance" || action === "create-successor-instance"
             ? "delete-instance"
             : "delete";
-    const deleteUsage = commands[resource]?.[deleteAction]?.usage;
-    if (!deleteUsage)
+    const deleteSyntax = commandSyntaxTree(resource, deleteAction);
+    if (!deleteSyntax)
         return undefined;
-    const base = stripOptionalUsageGroups(deleteUsage).replace(/\s+/g, " ").trim();
-    if (deleteUsage.includes("--if-exists"))
+    const base = renderNodes(deleteSyntax, true);
+    if (syntaxHasFlag(deleteSyntax, "if-exists"))
         return `${base} --if-exists`;
     return base;
 }
@@ -1123,14 +976,15 @@ function inferAsyncKind(resource, action) {
     }
     return "none";
 }
-function inferIdempotency(resource, sideEffect, action, usage) {
+function inferIdempotency(resource, sideEffect, action, syntax) {
     if (sideEffect === "read")
         return "safe";
     if (`${resource}.${action}` === "install-skill.run")
         return "convergent";
-    if (action.startsWith("create") && usage.includes("--if-not-exists"))
+    if (action.startsWith("create") && syntaxHasFlag(syntax, "if-not-exists")) {
         return "if-not-exists";
-    if (action.startsWith("delete") && usage.includes("--if-exists"))
+    }
+    if (action.startsWith("delete") && syntaxHasFlag(syntax, "if-exists"))
         return "if-exists";
     if (`${resource}.${action}` === "app.set-manifest-version")
         return "none";
@@ -1182,10 +1036,10 @@ export function inferCleanupHint(resource, action) {
         : action === "create-instance" || action === "create-successor-instance"
             ? "delete-instance"
             : "delete";
-    const deleteUsage = commands[resource]?.[deleteAction]?.usage;
-    if (!deleteUsage)
+    const deleteSyntax = commandSyntaxTree(resource, deleteAction);
+    if (!deleteSyntax)
         return undefined;
-    const ifExists = deleteUsage.includes("--if-exists") ? " --if-exists" : "";
+    const ifExists = syntaxHasFlag(deleteSyntax, "if-exists") ? " --if-exists" : "";
     if (resource === "code-env") {
         return `Delete with \`dss code-env delete <lang> <name>${ifExists}\`.`;
     }
@@ -1196,14 +1050,16 @@ export function inferCleanupHint(resource, action) {
 }
 function buildRegistryEntry(resource, action, meta) {
     const requiresAuth = meta.localHandler === undefined && inferRequiresAuth(resource);
-    const requiresProject = inferRequiresProject(resource, action, meta.usage);
+    const requiresProject = inferRequiresProject(resource, action);
     const sideEffect = inferSideEffect(resource, action);
     const destructive = inferDestructiveLevel(resource, sideEffect, action);
     const asyncKind = inferAsyncKind(resource, action);
     const mutatesDss = sideEffect === "write" && resource !== "auth" && resource !== "install-skill";
-    const supportsPlan = mutatesDss || sideEffect === "write";
+    // auth login writes local credentials only; its --plan previews that write.
+    const supportsPlan = sideEffect === "write" || resource === "auth";
     const supportsCleanup = supportsCleanupLedger(resource, action);
-    const usageFlags = extractUsageFlags(meta.usage);
+    const syntax = commandSyntax(resource, action);
+    const usageFlags = syntax.flags;
     const flags = uniqueStrings([
         ...usageFlags,
         ...(supportsPlan ? ["plan",] : []),
@@ -1212,7 +1068,7 @@ function buildRegistryEntry(resource, action, meta) {
         ...(requiresAuth ? AUTHENTICATED_AGENT_FLAGS : []),
         ...(requiresProject ? ["project-key",] : []),
     ]);
-    const derivedRequired = deriveRequiredUsage(meta.usage);
+    const derivedRequired = syntax;
     const requiredFlags = meta.requiredFlags
         ?? EXPLICIT_REGISTRY_OVERRIDES[registryKey(resource, action)]?.requiredFlags
         ?? derivedRequired.requiredFlags;
@@ -1223,8 +1079,8 @@ function buildRegistryEntry(resource, action, meta) {
     const optionalFlags = meta.optionalFlags
         ?? EXPLICIT_REGISTRY_OVERRIDES[registryKey(resource, action)]?.optionalFlags
         ?? flags.filter((flag) => !requiredFlags.includes(flag) && !oneOfFlags.has(flag));
-    const valueHints = extractFlagValueHints(meta.usage);
-    const inputContract = inferInputContract(meta.usage);
+    const valueHints = syntax.valueHints;
+    const inputContract = syntax.inputContract;
     const cleanupHint = inferCleanupHint(resource, action);
     const payloadSchema = meta.payloadSchema
         ?? EXPLICIT_REGISTRY_OVERRIDES[registryKey(resource, action)]?.payloadSchema
@@ -1238,15 +1094,13 @@ function buildRegistryEntry(resource, action, meta) {
         ? undefined
         : inferredCleanupCommand;
     const flagMetadata = flags.map((name) => {
-        const aliases = Object.entries(FLAG_ALIASES)
-            .filter(([raw, canonical,]) => canonical === name && new RegExp(`--${raw}(?![a-z0-9-])`).test(meta.usage))
-            .map(([raw,]) => raw);
+        const aliases = syntax.aliases[name] ?? [];
         const aliasPart = aliases.length > 0 ? { aliases, } : {};
         const kind = flagKind(name);
         if (kind === "boolean")
             return { name, kind, ...aliasPart, };
         const allowEmptyPart = ALLOW_EMPTY_VALUE_FLAGS[name] === true ? { allowEmptyValue: true, } : {};
-        const hint = valueHints.get(name) ?? GLOBAL_FLAG_VALUE_HINTS[name];
+        const hint = valueHints[name] ?? GLOBAL_FLAG_VALUE_HINTS[name];
         if (!hint)
             return { name, kind, ...aliasPart, ...allowEmptyPart, };
         return {
@@ -1258,12 +1112,11 @@ function buildRegistryEntry(resource, action, meta) {
             ...allowEmptyPart,
         };
     });
-    const positionalArguments = extractPositionalArguments(meta.usage);
+    const positionalArguments = syntax.positionalArguments;
     const positionals = positionalArguments.map((positional) => positional.name);
     const inputGroups = requiredInputGroups(resource, action);
     const outputShape = inferOutputShape(resource, action);
-    const producesLocalFile = meta.usage.includes("--output PATH")
-        || meta.usage.includes("--output-file PATH");
+    const producesLocalFile = syntax.producesLocalFile;
     const uniqueRequiredFlags = uniqueStrings(requiredFlags);
     const uniqueOptionalFlags = uniqueStrings(optionalFlags);
     const unsafe = unsafeOutputs(resource, action, producesLocalFile);
@@ -1287,8 +1140,8 @@ function buildRegistryEntry(resource, action, meta) {
         producesLocalFile,
         mutatesDss,
         async: asyncKind,
-        idempotency: inferIdempotency(resource, sideEffect, action, meta.usage),
-        dryRun: meta.usage.includes("--dry-run"),
+        idempotency: inferIdempotency(resource, sideEffect, action, commandSyntaxTree(resource, action) ?? []),
+        dryRun: syntax.dryRun,
         requiredFlags: uniqueRequiredFlags,
         optionalFlags: uniqueOptionalFlags,
         ...(requiredOneOf.length > 0 ? { requiredOneOf, } : {}),
@@ -1389,7 +1242,7 @@ function commandDefinitions(resourceFilter) {
         for (const [action, meta,] of Object.entries(AUTH_ACTIONS)) {
             registry.auth[action] = {
                 handler: async () => undefined,
-                usage: meta.usage,
+                usage: commandUsage("auth", action),
                 description: meta.description,
                 examples: meta.examples,
                 requiredFlags: meta.requiredFlags,
@@ -1656,9 +1509,7 @@ function planProjectKeyFromArgs(flags) {
     const fromFlag = flags["project-key"];
     if (typeof fromFlag === "string" && fromFlag.trim().length > 0)
         return fromFlag.trim();
-    if (!dataikuEnvironmentEnabled())
-        return undefined;
-    const fromEnv = process.env.DATAIKU_PROJECT_KEY;
+    const fromEnv = ambientProjectKey();
     return fromEnv !== undefined && fromEnv.trim().length > 0 ? fromEnv.trim() : undefined;
 }
 /**
@@ -1710,11 +1561,6 @@ function optionalJsonFlag(flags, name) {
 function requiredPlanJsonInput(flags, usage) {
     return requiredJsonInput(flags, `--data, --data-file, or --stdin is required. Usage: ${usage}`);
 }
-function requiredPlanPositionals(usage) {
-    return extractPositionalArguments(usage)
-        .filter((positional) => positional.required)
-        .map((positional) => positional.name);
-}
 function dataQualityEndpoint(projectKey, datasetName, suffix) {
     return encodedProjectEndpointForPlan(projectKey, `/datasets/${encodeURIComponent(datasetName)}/data-quality${suffix}`);
 }
@@ -1797,15 +1643,12 @@ function encodePluginSegmentsForPlan(contentPath) {
  */
 function pluginGitPlanPayload(flags) {
     const repository = requiredPlanFlag(flags, "repository", "dss plugin install-from-git --repository URL");
-    const payload = {
+    // Mirrors PluginsResource install/update bodies: absent options are sent as null.
+    return {
         gitRepositoryUrl: validatedPlanRepositoryUrl(repository, "repository", "--repository URL"),
+        gitCheckout: typeof flags["checkout"] === "string" ? flags["checkout"] : null,
+        gitSubpath: typeof flags["path-in-repository"] === "string" ? flags["path-in-repository"] : null,
     };
-    if (typeof flags["checkout"] === "string")
-        payload.gitCheckout = flags["checkout"];
-    if (typeof flags["path-in-repository"] === "string") {
-        payload.gitSubpath = flags["path-in-repository"];
-    }
-    return payload;
 }
 function optionalPlanProjectScope(flags) {
     const projectKey = flags["project-key"];
@@ -1938,16 +1781,28 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         case "wiki.create": {
             const name = requiredPlanFlag(flags, "name", entry.usage);
-            return {
+            const content = textInput(flags);
+            const create = {
                 method: "POST",
                 endpoint: projectEndpoint("/wiki/"),
+                payload: { projectKey, name, parent: flags["parent"] ?? null, },
+            };
+            return {
+                ...create,
                 identifiers: { name, },
-                payload: {
-                    projectKey,
-                    name,
-                    parent: flags["parent"] ?? null,
-                    content: textInput(flags),
-                },
+                // Content is not accepted by the create endpoint; it lands in a follow-up update.
+                ...(content === undefined ? {} : {
+                    requests: [
+                        { sequence: 1, ...create, },
+                        { sequence: 2, method: "GET", endpoint: projectEndpoint("/wiki/{createdArticleId}"), },
+                        {
+                            sequence: 3,
+                            method: "PUT",
+                            endpoint: projectEndpoint("/wiki/{createdArticleId}"),
+                            payload: { payload: content, },
+                        },
+                    ],
+                }),
             };
         }
         case "wiki.update":
@@ -1973,7 +1828,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             const dataName = data?.["name"];
             const name = flagName ?? (typeof dataName === "string" ? dataName : undefined);
             if (!name) {
-                throw new UsageError("--name or dashboard settings containing a string name are required. Usage: dss dashboard create --name NAME");
+                throw new UsageError(`--name or dashboard settings containing a string name are required. Usage: ${commandUsage("dashboard", "create")}`);
             }
             const listed = parseBooleanOption(flags["listed"], "--listed");
             const payload = { ...(data ?? { pages: [], }), name, };
@@ -2011,7 +1866,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             const name = flags["name"];
             const type = flags["type"];
             if (!data && (!name || !type)) {
-                throw new UsageError("--data or both --name and --type are required. Usage: dss insight create --name NAME --type TYPE");
+                throw new UsageError(`--data or both --name and --type are required. Usage: ${commandUsage("insight", "create")}`);
             }
             const prototype = { ...data, };
             if (name !== undefined)
@@ -2095,7 +1950,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         case "flow-zone.create": {
             const name = flowZoneName(flags["name"]);
-            const payload = { name, color: flowZoneColor(flags["color"]), projectKey, };
+            const payload = { name, color: flowZoneColor(flags["color"]) ?? "#2ab1ac", };
             return {
                 method: "POST",
                 endpoint: projectEndpoint("/flow/zones"),
@@ -2134,17 +1989,25 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             if (!connection && dsType.toLowerCase() !== "uploadedfiles") {
                 throw new UsageError("--connection is required unless --type is UploadedFiles.");
             }
+            const endpoint = projectEndpoint("/datasets/"); // throws without a project key
             return {
                 method: "POST",
-                endpoint: projectEndpoint("/datasets/"),
+                endpoint,
                 identifiers: { name, },
-                payload: { datasetName: name, connection, dsType, projectKey, },
+                payload: buildDatasetCreateBody({
+                    projectKey: projectKey,
+                    datasetName: name,
+                    connection,
+                    dsType,
+                }),
             };
         }
         case "dataset.clone": {
             const source = args[0];
             const target = args[1];
             return {
+                exact: false,
+                reason: "Apply GETs the source dataset and copies its current connection, format, and schema into the new dataset body.",
                 method: "POST",
                 endpoint: projectEndpoint("/datasets/"),
                 identifiers: { source, target, },
@@ -2306,7 +2169,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: { name: id, },
             };
         case "recipe.create": {
-            const type = requiredPlanFlag(flags, "type", entry.usage);
+            requiredPlanFlag(flags, "type", entry.usage);
             const outputDataset = flags["output"];
             const outputFolder = flags["output-folder"];
             if (outputDataset && outputFolder) {
@@ -2318,19 +2181,14 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             if (outputFolder && !flags["output-connection"]) {
                 throw new UsageError("--output-connection is required when using --output-folder.");
             }
+            const endpoint = projectEndpoint("/recipes/"); // throws without a project key
+            // Same flag mapping and body construction as the handler and RecipesResource.create.
+            const { recipePrototype, creationSettings, } = buildRecipeCreateRequest(recipeCreateOptionsFromFlags(flags), projectKey);
             return {
                 method: "POST",
-                endpoint: projectEndpoint("/recipes/"),
-                identifiers: { name: flags["name"], },
-                payload: {
-                    type,
-                    name: flags["name"],
-                    inputDatasets: recipeInputDatasetsFromFlags(flags),
-                    outputDataset,
-                    outputFolder,
-                    outputConnection: flags["output-connection"],
-                    projectKey,
-                },
+                endpoint,
+                identifiers: { name: recipePrototype.name, },
+                payload: { recipePrototype, creationSettings, },
             };
         }
         case "recipe.run":
@@ -2456,22 +2314,54 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             if (activeRaw !== "true" && activeRaw !== "false") {
                 throw new UsageError(`Usage: ${entry.usage}`);
             }
+            const lightEndpoint = projectEndpoint(`/scenarios/${encodeURIComponent(id)}/light`);
+            const active = activeRaw === "true";
+            // DSS parses the light PUT as a full Scenario, so the command echoes the
+            // current light status with `active` overridden (see ScenariosResource.setActive).
             return {
                 method: "PUT",
-                endpoint: projectEndpoint(`/scenarios/${encodeURIComponent(id)}/light`),
+                endpoint: lightEndpoint,
                 identifiers: { id, },
-                payload: { id, active: activeRaw === "true", },
+                payload: { active, },
+                requests: [
+                    { sequence: 1, method: "GET", endpoint: lightEndpoint, },
+                    {
+                        sequence: 2,
+                        method: "PUT",
+                        endpoint: lightEndpoint,
+                        payload: { "...current": true, active, },
+                    },
+                    { sequence: 3, method: "GET", endpoint: lightEndpoint, },
+                ],
             };
         }
         case "folder.create": {
             const name = requiredPlanFlag(flags, "name", entry.usage);
             const type = flags["type"];
             const connection = flags["connection"];
+            const pathFlag = flags["path"];
+            const body = {
+                name,
+                projectKey,
+                type: type ?? null,
+                params: { connection, path: pathFlag?.trim() || "/${projectKey}/${odbId}", },
+            };
+            // Mirrors FoldersResource.create.
+            if (connection === undefined) {
+                return {
+                    exact: false,
+                    reason: "Without --connection, apply reads DSS admin settings to pick the managed-folder connection (falling back to filesystem_folders); params.connection is set then.",
+                    method: "POST",
+                    endpoint: projectEndpoint("/managedfolders/"),
+                    identifiers: { name, },
+                    payload: body,
+                };
+            }
             return {
                 method: "POST",
                 endpoint: projectEndpoint("/managedfolders/"),
                 identifiers: { name, },
-                payload: { name, type, connection, path: flags["path"], projectKey, },
+                payload: body,
             };
         }
         case "job.abort":
@@ -2495,18 +2385,22 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 endpoint: projectEndpoint(`/scenarios/${encodeURIComponent(id)}/`),
                 identifiers: { id, },
             };
-        case "scenario.create":
+        case "scenario.create": {
+            const type = flags["type"] ?? "step_based";
             return {
                 method: "POST",
                 endpoint: projectEndpoint("/scenarios/"),
                 identifiers: { id: args[0], name: args[1], },
+                // Mirrors ScenariosResource.create's default params for step-based scenarios.
                 payload: {
                     id: args[0],
                     name: args[1],
                     projectKey,
-                    type: flags["type"] ?? "step_based",
+                    type,
+                    params: type === "step_based" ? { steps: [], triggers: [], reporters: [], } : {},
                 },
             };
+        }
         case "scenario.update":
             return {
                 method: "PUT",
@@ -2541,6 +2435,8 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         case "variable.set":
             return {
+                exact: false,
+                reason: "The payload lists the requested changes; apply PUTs the full {standard, local} object (merged with the current variables unless --replace).",
                 method: "PUT",
                 endpoint: projectEndpoint("/variables/"),
                 payload: {
@@ -2968,6 +2864,8 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         case "saved-model.import-mlflow-version-from-folder":
             return {
+                exact: false,
+                reason: "Apply sends these values as query parameters (with codeEnvName and binaryClassificationThreshold defaults) on an empty multipart body; the payload shows them structured.",
                 method: "POST",
                 endpoint: projectEndpoint(`/savedmodels/${encodeURIComponent(id)}/versions/${encodeURIComponent(args[1] ?? "")}`),
                 identifiers: { savedModelId: id, versionId: args[1], },
@@ -3018,7 +2916,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             }
             return {
                 method: "POST",
-                endpoint: projectEndpoint(`/savedmodels/${encodeURIComponent(id)}/versions/${encodeURIComponent(args[1] ?? "")}/external-ml/actions/evaluate`),
+                endpoint: `${projectEndpoint(`/savedmodels/${encodeURIComponent(id)}/versions/${encodeURIComponent(args[1] ?? "")}/external-ml/actions/evaluate`)}?useOptimalThreshold=${parseBooleanOption(flags["use-optimal-threshold"], "--use-optimal-threshold") ?? true}&skipExpensiveReports=${parseBooleanOption(flags["skip-expensive-reports"], "--skip-expensive-reports") ?? true}`,
                 identifiers: { savedModelId: id, versionId: args[1], },
                 payload,
             };
@@ -3217,17 +3115,19 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         case "plugin.create-dev": {
             const creationMode = requiredPlanFlag(flags, "creation-mode", entry.usage);
+            const needsGit = creationMode !== "EMPTY";
+            // Mirrors PluginsResource.createDev: git fields are always present, null when unused.
             const payload = {
                 pluginId: id,
                 creationMode,
+                gitRepository: needsGit && typeof flags["repository"] === "string"
+                    ? validatedPlanRepositoryUrl(flags["repository"], "repository", "--repository URL")
+                    : null,
+                gitCheckout: needsGit && typeof flags["checkout"] === "string" ? flags["checkout"] : null,
+                gitSubpath: creationMode === "GIT_EXPORT" && typeof flags["path-in-repository"] === "string"
+                    ? flags["path-in-repository"]
+                    : null,
             };
-            if (typeof flags["repository"] === "string")
-                payload.gitRepository = flags["repository"];
-            if (typeof flags["checkout"] === "string")
-                payload.gitCheckout = flags["checkout"];
-            if (typeof flags["path-in-repository"] === "string") {
-                payload.gitSubpath = flags["path-in-repository"];
-            }
             return {
                 method: "POST",
                 endpoint: "/public/api/plugins/actions/createDev",
@@ -3288,14 +3188,13 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: { pluginId: id, path: args[1], },
             };
         case "plugin.rename": {
-            const newName = requiredPlanPositionals(entry.usage)[2];
-            if (!newName)
+            if (!args[2])
                 throw new UsageError(`Usage: ${entry.usage}`);
             return {
                 method: "POST",
                 endpoint: `${pluginRootEndpoint(id, "/contents-actions/rename")}`,
                 identifiers: { pluginId: id, path: args[1], },
-                payload: { oldPath: args[1], newName: args[2], },
+                payload: { oldPath: `/${validatePluginPath(args[1] ?? "")}`, newName: args[2], },
             };
         }
         case "plugin.move": {
@@ -3306,7 +3205,10 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 method: "POST",
                 endpoint: `${pluginRootEndpoint(id, "/contents-actions/move")}`,
                 identifiers: { pluginId: id, path: args[1], },
-                payload: { oldPath: args[1], newPath: destination, },
+                payload: {
+                    oldPath: `/${validatePluginPath(args[1] ?? "")}`,
+                    newPath: validatePluginDestinationPath(destination),
+                },
             };
         }
         case "business-app.save-settings":
@@ -3356,6 +3258,8 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 // plan carries no preflight requests and no fake concrete GET
                 // path: `{targetProjectKey}` resolves at apply time.
                 return {
+                    exact: false,
+                    reason: "targetProjectKey (and targetProjectName when omitted) are generated during apply; the sent body adds them.",
                     method: "POST",
                     endpoint: `/public/api/apps/${encodeURIComponent(id)}/instances`,
                     identifiers: {
@@ -4037,7 +3941,6 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                     evaluateProjectStandardsChecks,
                 }),
                 identifiers: { bundleId: id, },
-                payload: {},
             };
         }
         case "bundle.publish":
@@ -4255,7 +4158,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
         case "code-env.set-jupyter": {
             const active = parseBooleanOption(flags["active"], "--active");
             if (active === undefined) {
-                throw new UsageError("--active is required. Usage: dss code-env set-jupyter <lang> <name> --active true|false");
+                throw new UsageError(`--active is required. Usage: ${commandUsage("code-env", "set-jupyter")}`);
             }
             const wait = codeEnvWait(flags);
             return {
@@ -4890,7 +4793,7 @@ export function buildMutationPlan(resource, action, meta, args, flags) {
     if (!entry.mutatesDss && entry.sideEffect !== "write") {
         throw new UsageError(`--plan is only supported for mutating commands. Usage: ${meta.usage}`);
     }
-    const requiredPositionals = requiredPlanPositionals(meta.usage);
+    const requiredPositionals = entry.positionalArguments.filter((positional) => positional.required);
     requireArgs(args, requiredPositionals.length, meta.usage);
     const projectKey = projectKeyForPlan(entry, flags);
     const shape = commandPlanShape(resource, action, args, flags, entry, projectKey);
@@ -4914,7 +4817,7 @@ export const BATCH_PLAN_EXIT_CODES = {
     longRunningFailure: 4,
     assertionFailure: 4,
 };
-export const BATCH_USAGE = "dss batch (--data JSON|--data-file PATH|--stdin) [--continue-on-error] [--dry-run]";
+export const BATCH_USAGE = commandUsage("batch", "run");
 const BATCH_DESCRIPTION = "Run dss argv arrays fail-fast by default. The result aggregates failed/retryable/failureCodes; process exit remains the first failed step's exit code.";
 export const BATCH_HINT = 'Pass a JSON array of argv arrays, e.g. [["dataset","list"],["recipe","update","r","--data-file","p.json"]].';
 export const BATCH_EXAMPLE_PAYLOAD = [