dataiku-sdk 3.1.0 → 3.3.0

package/dist/src/cli/contract.js

@@ -13,12 +13,12 @@ import { commands, } from "./commands/index.js";
 import { projectLibraryPutPayload, } from "./commands/project-library.js";
 import { resolveSqlQueryInvocation, } from "./commands/sql.js";
 import { dataikuEnvironmentEnabled, } from "./env.js";
-import { BOOLEAN_FLAGS, FLAG_ALIASES, KNOWN_LONG_FLAGS, SHORT_FLAGS, } from "./flags.js";
+import { BOOLEAN_FLAGS, executionMode, FLAG_ALIASES, KNOWN_LONG_FLAGS, 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 { requireArgs, UsageError, } from "./usage.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) {
     return flags["no-wait"] !== true;
@@ -39,19 +39,27 @@ function codeEnvParams(flags) {
 function splitPackageSpec(raw) {
     return raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
 }
+/**
+ * Resolve requested package specs from --file/--packages/--package. An
+ * explicit source that resolves to zero specs is a legitimate clear
+ * (set-packages replaces specPackageList wholesale); only a call with no
+ * package source flag at all is a usage error.
+ */
 function codeEnvPackageList(flags) {
-    const packages = [];
-    if (typeof flags["file"] === "string") {
-        packages.push(...splitPackageSpec(fs.readFileSync(flags["file"], "utf-8")));
-    }
+    const file = flags["file"];
+    const packages = typeof file === "string"
+        ? splitPackageSpec(fs.readFileSync(file, "utf-8"))
+        : [];
     if (typeof flags["packages"] === "string") {
         packages.push(...splitPackageSpec(flags["packages"]));
     }
     if (typeof flags["package"] === "string") {
         packages.push(...splitPackageSpec(flags["package"]));
     }
-    if (packages.length === 0) {
-        throw new UsageError("--packages, --package, or --file is required. Use newline-separated package specs for version constraints.");
+    if (typeof file !== "string"
+        && typeof flags["packages"] !== "string"
+        && typeof flags["package"] !== "string") {
+        throw new UsageError("--packages, --package, or --file is required. Use newline-separated package specs for version constraints; an explicitly empty value (or empty file) clears the requested package list.");
     }
     return packages;
 }
@@ -127,26 +135,31 @@ const READ_ACTIONS = new Set([
     "usages",
     "verify-instance",
 ]);
-const PROJECT_SCOPED_RESOURCES = new Set([
-    "analysis",
-    "data-quality",
-    "dashboard",
-    "dataset",
-    "flow-zone",
-    "insight",
-    "folder",
-    "fixtures",
-    "job",
-    "notebook",
-    "ml-task",
-    "model-evaluation-store",
-    "recipe",
-    "scenario",
-    "sql",
-    "variable",
-    "saved-model",
-    "wiki",
-]);
+/**
+ * Security admin actions that hand back a DSS future instead of settling
+ * inline: resyncs mint sync jobs, external-user/group fetches mint a
+ * supplier-enumeration job, and provision runs a supplier import. Without
+ * this table they fall through to the read default and `--plan` rejects
+ * them as non-mutating.
+ */
+const ADMIN_SECURITY_FUTURE_ACTIONS = {
+    "external-groups": true,
+    "external-users": true,
+    provision: true,
+    resync: true,
+    "resync-multi": true,
+};
+/** Connection tables-import actions return a DSS future reference. */
+const CONNECTION_FUTURE_ACTIONS = {
+    "execute-import": true,
+    "prepare-import": true,
+};
+/** Plugin actions that only observe state despite POST shape (documented). */
+const PLUGIN_GIT_OBSERVER_ACTIONS = {
+    "git-branches": true,
+    list: true,
+    usages: true,
+};
 /**
  * Project Git actions that only observe repository state. Everything else in the
  * `project-git` resource is a mutation: the verb-shaped names (`fetch`, `pull`,
@@ -185,6 +198,17 @@ const PROJECT_GIT_DESTRUCTIVE_ACTIONS = {
     "revert-commit": true,
     "revert-to-revision": true,
 };
+/** Plugin actions that discard work or publish it beyond the instance. */
+const PLUGIN_DESTRUCTIVE_ACTIONS = {
+    "contents-delete": true,
+    delete: true,
+    "delete-git-remote": true,
+    fetch: true,
+    pull: true,
+    push: true,
+    "reset-local": true,
+    "reset-remote": true,
+};
 /** Project Git actions that hand back a DSS future (`{jobId}`) instead of a result. */
 const PROJECT_GIT_FUTURE_ACTIONS = {
     "add-library": true,
@@ -434,6 +458,18 @@ const NOTEBOOK_SAVE_OUTPUT_SCHEMA = {
         hash: { type: "string", pattern: "^[a-f0-9]{64}$", },
     },
 };
+/**
+ * `notebook.save-sql` adds `requested`: on create DSS allocates the persisted
+ * id (`saved`), while the requested handle only becomes the display name.
+ */
+const NOTEBOOK_SAVE_SQL_OUTPUT_SCHEMA = {
+    ...NOTEBOOK_SAVE_OUTPUT_SCHEMA,
+    required: ["saved", "requested", "resource", "created", "hash",],
+    properties: {
+        ...NOTEBOOK_SAVE_OUTPUT_SCHEMA["properties"],
+        requested: { type: "string", },
+    },
+};
 const COMMAND_OUTPUT_SCHEMAS = {
     "code-env.list": CodeEnvSummaryArraySchema,
     "code-env.get": CodeEnvDetailsSchema,
@@ -514,7 +550,7 @@ const COMMAND_OUTPUT_SCHEMAS = {
     "notebook.get-sql": SqlNotebookContentSchema,
     "notebook.history-sql": SqlNotebookHistorySchema,
     "notebook.save-jupyter": NOTEBOOK_SAVE_OUTPUT_SCHEMA,
-    "notebook.save-sql": NOTEBOOK_SAVE_OUTPUT_SCHEMA,
+    "notebook.save-sql": NOTEBOOK_SAVE_SQL_OUTPUT_SCHEMA,
     "project-library.list": { type: "array", items: PROJECT_LIBRARY_ITEM_OUTPUT_SCHEMA, },
     "project-library.get-bytes": {
         type: "object",
@@ -749,11 +785,11 @@ function unsafeOutputs(resource, action, producesLocalFile) {
             condition: "--output or --output-file",
             kind: "local-file",
             detail: sensitivePermissions
-                ? "Command writes access-control identities and permissions to an owner-only local file."
-                : "Command writes bytes to a local path and returns JSON metadata on stdout.",
+                ? "Writes access-control identities and permissions to an owner-only local file."
+                : "Writes a local file; stdout contains JSON metadata.",
             ...(sensitivePermissions
                 ? {
-                    safeAlternative: "Keep the file owner-only and outside version control unless repository policy explicitly permits committing access-control data.",
+                    safeAlternative: "Keep owner-only and outside version control unless repository policy explicitly permits committing access-control data.",
                 }
                 : {}),
         });
@@ -916,10 +952,33 @@ function inferSideEffect(resource, action) {
         return "read";
     if (resource === "data-quality" && action === "compute")
         return "write";
+    if (resource === "user" && ADMIN_SECURITY_FUTURE_ACTIONS[action] === true)
+        return "write";
+    if (resource === "connection" && CONNECTION_FUTURE_ACTIONS[action] === true)
+        return "write";
+    // Saved-model evaluation triggers scoring work on DSS side (cost-bearing).
+    if (resource === "saved-model" && action === "evaluate-version")
+        return "write";
+    // 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.
+    if (resource === "llm" && (action === "completions" || action === "embeddings")) {
+        return "write";
+    }
     // Project Git is classified from the explicit read table, not by verb shape:
     // `switch`, `fetch`, `pull`, `push`, `commit`, the `reset-*`/`revert-*`
     // families, `drop-and-rebuild`, and `future-abort` all mutate repository or
     // future state yet match none of the mutating-verb patterns.
+    // Plugin dev-Git actions mutate repository/plugin state like project-git:
+    // `fetch`/`pull`/`push`/`reset-*` never match the generic mutating-verb
+    // regex, so they are classified explicitly as write (destructive level
+    // from the explicit table below). `git-branches` is a state observer
+    // (observed GET on DSS 15; the upstream docs' POST is wrong) and stays
+    // read.
+    if (resource === "plugin") {
+        return PLUGIN_GIT_OBSERVER_ACTIONS[action] === true ? "read" : "write";
+    }
     if (resource === "project-git") {
         return PROJECT_GIT_READ_ACTIONS[action] === true ? "read" : "write";
     }
@@ -927,8 +986,9 @@ function inferSideEffect(resource, 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)/
         .test(action)
-        // Compound actions whose mutating verb is a suffix (e.g. permissions-set, dataset-compute).
-        || /-(set|compute|restore)$/.test(action)) {
+        // Compound actions whose mutating verb is a suffix (e.g. permissions-set,
+        // dataset-compute, saved-model external-metadata-put).
+        || /-(set|compute|restore|put)$/.test(action)) {
         return "write";
     }
     return "read";
@@ -940,19 +1000,6 @@ function inferRequiresAuth(resource) {
         && resource !== "install-skill"
         && resource !== "version";
 }
-export function inferRequiresProject(resource, action, usage) {
-    if (resource === "agent" || resource === "auth" || resource === "doctor" || resource === "commands"
-        || resource === "install-skill" || resource === "version") {
-        return false;
-    }
-    if (resource === "sql" && action === "query")
-        return false;
-    if (PROJECT_SCOPED_RESOURCES.has(resource))
-        return true;
-    if (resource === "project-git")
-        return !action.startsWith("future-");
-    return usage.includes("--project-key");
-}
 const ARRAY_OUTPUT_ACTIONS = new Set([
     "history",
     "find",
@@ -1166,7 +1213,7 @@ function cleanupCommandFromDeleteUsage(resource, action) {
         return "dss notebook delete-jupyter <name> --if-exists";
     }
     if (`${resource}.${action}` === "notebook.save-sql") {
-        return "dss notebook delete-sql <id> --if-exists";
+        return "dss notebook delete-sql <the returned `saved` id> --if-exists";
     }
     if (`${resource}.${action}` === "project.import") {
         return "dss project delete <used-project-key> --if-exists --expect-project-incarnation <hash>";
@@ -1203,12 +1250,29 @@ export function supportsCleanupLedger(resource, action) {
 const EXPLICIT_DESTRUCTIVE_KEYS = {
     "dataset.upload-file": true,
     "sql.query": true,
+    // Plugin dev-Git and content deletions discard work with no undo route.
+    "plugin.delete": true,
+    "plugin.delete-git-remote": true,
+    "plugin.push": true,
+    "plugin.pull": true,
+    "plugin.fetch": true,
+    "plugin.reset-local": true,
+    "plugin.reset-remote": true,
+    "plugin.contents-delete": true,
+    // Macro runs execute arbitrary plugin code.
+    "macro.run": true,
+    "macro.run-and-wait": true,
+    // Saved-model version deletion removes model versions permanently.
+    "saved-model.delete-versions": true,
 };
 function inferDestructiveLevel(resource, sideEffect, action) {
     if (sideEffect !== "write")
         return "none";
     if (EXPLICIT_DESTRUCTIVE_KEYS[`${resource}.${action}`] === true)
         return "destructive";
+    if (resource === "plugin") {
+        return PLUGIN_DESTRUCTIVE_ACTIONS[action] === true ? "destructive" : "reversible";
+    }
     if (resource === "project-git") {
         return PROJECT_GIT_DESTRUCTIVE_ACTIONS[action] === true ? "destructive" : "reversible";
     }
@@ -1229,6 +1293,10 @@ function inferAsyncKind(resource, action) {
     if (resource === "scenario" && ["run", "run-and-wait", "status",].includes(action)) {
         return "future";
     }
+    if (resource === "user" && ADMIN_SECURITY_FUTURE_ACTIONS[action] === true)
+        return "future";
+    if (resource === "connection" && CONNECTION_FUTURE_ACTIONS[action] === true)
+        return "future";
     if (resource === "data-quality" && action === "compute")
         return "future";
     // Project Git mutation results carry a future job id only for the library
@@ -1293,10 +1361,10 @@ export function inferCleanupHint(resource, action) {
         return undefined;
     const key = `${resource}.${action}`;
     if (key === "notebook.save-jupyter") {
-        return "When the save reports created:true, delete with `dss notebook delete-jupyter <name> --if-exists`.";
+        return "If created:true, delete with `dss notebook delete-jupyter <name> --if-exists`.";
     }
     if (key === "notebook.save-sql") {
-        return "When the save reports created:true, delete with `dss notebook delete-sql <id> --if-exists`.";
+        return "If created:true, the persisted id is in `saved`; delete with `dss notebook delete-sql <saved> --if-exists`.";
     }
     if (!(action.startsWith("create") || action === "clone"))
         return undefined;
@@ -1317,7 +1385,7 @@ export function inferCleanupHint(resource, action) {
     if (resource === "data-quality") {
         return `Delete with \`dss data-quality delete-rule <dataset> <rule-id>${ifExists}\`.`;
     }
-    return `Delete with \`dss ${resource} delete <id>${ifExists}\` when the created object is disposable.`;
+    return `For disposable creates: \`dss ${resource} delete <id>${ifExists}\`.`;
 }
 function buildRegistryEntry(resource, action, meta) {
     const requiresAuth = meta.localHandler === undefined && inferRequiresAuth(resource);
@@ -1427,82 +1495,107 @@ function buildRegistryEntry(resource, action, meta) {
         agentContractVersion: AGENT_CONTRACT_VERSION,
     };
 }
-export function buildCommandRegistry() {
+function commandDefinitions(resourceFilter) {
+    const registry = {};
+    for (const resource of Object.keys(commands)) {
+        if (resourceFilter !== undefined && resource !== resourceFilter)
+            continue;
+        registry[resource] = commands[resource];
+    }
+    if (resourceFilter === undefined || resourceFilter === "commands") {
+        registry.commands = {
+            run: {
+                handler: async () => undefined,
+                usage: COMMANDS_USAGE,
+                description: COMMANDS_DESCRIPTION,
+                examples: COMMANDS_EXAMPLES,
+            },
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "agent") {
+        registry.agent = {
+            contract: {
+                handler: async () => undefined,
+                usage: AGENT_CONTRACT_USAGE,
+                description: AGENT_CONTRACT_DESCRIPTION,
+                examples: AGENT_CONTRACT_EXAMPLES,
+            },
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "version") {
+        registry.version = {
+            run: {
+                handler: async () => undefined,
+                usage: VERSION_USAGE,
+                description: VERSION_DESCRIPTION,
+                examples: VERSION_EXAMPLES,
+            },
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "install-skill") {
+        registry["install-skill"] = {
+            run: {
+                handler: async () => undefined,
+                usage: INSTALL_SKILL_USAGE,
+                description: INSTALL_SKILL_DESCRIPTION,
+                examples: INSTALL_SKILL_EXAMPLES,
+            },
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "cleanup") {
+        registry.cleanup = {
+            run: {
+                handler: async () => undefined,
+                usage: CLEANUP_USAGE,
+                description: CLEANUP_DESCRIPTION,
+                examples: CLEANUP_EXAMPLES,
+            },
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "fixtures") {
+        registry.fixtures = {
+            run: {
+                handler: async () => undefined,
+                usage: FIXTURES_USAGE,
+                description: FIXTURES_DESCRIPTION,
+                examples: FIXTURES_EXAMPLES,
+            },
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "batch") {
+        registry.batch = {
+            run: {
+                handler: async () => undefined,
+                usage: BATCH_USAGE,
+                description: BATCH_DESCRIPTION,
+                examples: BATCH_EXAMPLES,
+                examplePayload: BATCH_EXAMPLE_PAYLOAD,
+                payloadSchema: { stdin: true, dataFlag: true, dataFileFlag: true, jsonShape: "array", },
+            },
+        };
+    }
+    if (resourceFilter === undefined || resourceFilter === "auth") {
+        registry.auth = {};
+        for (const [action, meta,] of Object.entries(AUTH_ACTIONS)) {
+            registry.auth[action] = {
+                handler: async () => undefined,
+                usage: meta.usage,
+                description: meta.description,
+                examples: meta.examples,
+                requiredFlags: meta.requiredFlags,
+            };
+        }
+    }
+    return registry;
+}
+export function buildCommandRegistry(resourceFilter) {
     const registry = {};
-    for (const [resource, actions,] of Object.entries(commands)) {
+    for (const [resource, actions,] of Object.entries(commandDefinitions(resourceFilter))) {
         registry[resource] = {};
         for (const [action, meta,] of Object.entries(actions)) {
             registry[resource][action] = buildRegistryEntry(resource, action, meta);
         }
     }
-    registry.commands = {
-        run: buildRegistryEntry("commands", "run", {
-            handler: async () => undefined,
-            usage: COMMANDS_USAGE,
-            description: COMMANDS_DESCRIPTION,
-            examples: COMMANDS_EXAMPLES,
-        }),
-    };
-    registry.agent = {
-        contract: buildRegistryEntry("agent", "contract", {
-            handler: async () => undefined,
-            usage: AGENT_CONTRACT_USAGE,
-            description: AGENT_CONTRACT_DESCRIPTION,
-            examples: AGENT_CONTRACT_EXAMPLES,
-        }),
-    };
-    registry.version = {
-        run: buildRegistryEntry("version", "run", {
-            handler: async () => undefined,
-            usage: VERSION_USAGE,
-            description: VERSION_DESCRIPTION,
-            examples: VERSION_EXAMPLES,
-        }),
-    };
-    registry["install-skill"] = {
-        run: buildRegistryEntry("install-skill", "run", {
-            handler: async () => undefined,
-            usage: INSTALL_SKILL_USAGE,
-            description: INSTALL_SKILL_DESCRIPTION,
-            examples: INSTALL_SKILL_EXAMPLES,
-        }),
-    };
-    registry.cleanup = {
-        run: buildRegistryEntry("cleanup", "run", {
-            handler: async () => undefined,
-            usage: CLEANUP_USAGE,
-            description: CLEANUP_DESCRIPTION,
-            examples: CLEANUP_EXAMPLES,
-        }),
-    };
-    registry.fixtures = {
-        run: buildRegistryEntry("fixtures", "run", {
-            handler: async () => undefined,
-            usage: FIXTURES_USAGE,
-            description: FIXTURES_DESCRIPTION,
-            examples: FIXTURES_EXAMPLES,
-        }),
-    };
-    registry.batch = {
-        run: buildRegistryEntry("batch", "run", {
-            handler: async () => undefined,
-            usage: BATCH_USAGE,
-            description: BATCH_DESCRIPTION,
-            examples: BATCH_EXAMPLES,
-            examplePayload: BATCH_EXAMPLE_PAYLOAD,
-            payloadSchema: { stdin: true, dataFlag: true, dataFileFlag: true, jsonShape: "array", },
-        }),
-    };
-    registry.auth = {};
-    for (const [action, meta,] of Object.entries(AUTH_ACTIONS)) {
-        registry.auth[action] = buildRegistryEntry("auth", action, {
-            handler: async () => undefined,
-            usage: meta.usage,
-            description: meta.description,
-            examples: meta.examples,
-            requiredFlags: meta.requiredFlags,
-        });
-    }
     return registry;
 }
 function commandFlagJsonSchema() {
@@ -1658,38 +1751,43 @@ export function agentContractJsonSchema() {
         },
     };
 }
-export function commandActionSummary(registry) {
+export function commandActionSummary() {
     const summary = {};
-    for (const [resource, actions,] of Object.entries(registry)) {
+    for (const [resource, actions,] of Object.entries(commandDefinitions())) {
         summary[resource] = Object.keys(actions).sort();
     }
     return summary;
 }
 export function buildAgentContract() {
-    const registry = buildCommandRegistry();
+    let commandSection;
+    let schemaSection;
     return {
         protocol: "dataiku-sdk-agent",
         agentContractVersion: AGENT_CONTRACT_VERSION,
         cli: cliVersionResult(),
-        commands: {
-            discoveryCommand: "dss commands run",
-            fullRegistryExportCommand: "dss commands run --output PATH",
-            scopedDiscoveryCommand: "dss commands run --fields RESOURCE[.ACTION[.FIELD...]]",
-            actionIndexCommand: "dss agent contract --fields commands.actions",
-            scopedDiscoveryExamples: [
-                "dss commands run --fields dataset",
-                "dss commands run --fields dataset.create",
-            ],
-            scopedDiscoveryHint: "`dss commands run` returns the resource/action summary. --fields RESOURCE returns every action of one resource; --fields RESOURCE.ACTION returns a single registry entry keyed by the dotted path; append .FIELD paths to project nested metadata. Comma-separate paths to select several. Use --output PATH to export the full registry.",
-            actions: commandActionSummary(registry),
+        get commands() {
+            return commandSection ??= {
+                discoveryCommand: "dss commands run",
+                fullRegistryExportCommand: "dss commands run --output PATH",
+                scopedDiscoveryCommand: "dss commands run --fields RESOURCE[.ACTION[.FIELD...]]",
+                actionIndexCommand: "dss agent contract --fields commands.actions",
+                scopedDiscoveryExamples: [
+                    "dss commands run --fields dataset",
+                    "dss commands run --fields dataset.create",
+                ],
+                scopedDiscoveryHint: "Default: resource/action summary. --fields RESOURCE: all resource entries; RESOURCE.ACTION: one entry keyed by that path; append .FIELD for nested metadata. Comma-separate paths. --output PATH exports the full registry.",
+                actions: commandActionSummary(),
+            };
         },
-        schemas: {
-            agentContract: agentContractJsonSchema(),
-            commandRegistry: commandRegistryJsonSchema(),
-            commandRegistryEntry: commandRegistryEntryJsonSchema(),
-            errorEnvelope: errorEnvelopeJsonSchema(),
-            warningEvent: warningEventJsonSchema(),
-            traceEvent: traceEventJsonSchema(),
+        get schemas() {
+            return schemaSection ??= {
+                agentContract: agentContractJsonSchema(),
+                commandRegistry: commandRegistryJsonSchema(),
+                commandRegistryEntry: commandRegistryEntryJsonSchema(),
+                errorEnvelope: errorEnvelopeJsonSchema(),
+                warningEvent: warningEventJsonSchema(),
+                traceEvent: traceEventJsonSchema(),
+            };
         },
         stdio: {
             stdout: {
@@ -1697,8 +1795,8 @@ export function buildAgentContract() {
                 success: "single-json-value",
                 failure: "structured-error-object",
                 failureResultDetailLimitBytes: 65_536,
-                fieldProjection: "Missing --fields paths stay null on stdout and emit field_projection_missing on stderr.",
-                richFailureResults: "doctor/batch/cleanup nonzero outcomes are their own compact result on stdout ({ok:false,...}) with the command's exit code; not re-wrapped.",
+                fieldProjection: "Missing --fields paths: null on stdout; field_projection_missing on stderr.",
+                richFailureResults: "doctor/batch/cleanup failures: own compact {ok:false,...} result on stdout and command exit code; no wrapper.",
             },
             stderr: {
                 format: "jsonl",
@@ -1715,7 +1813,7 @@ export function buildAgentContract() {
         },
         compatibility: {
             fieldsAreAdditiveWithinMajor: true,
-            failFastWhenUnsupported: "Check agentContractVersion before planning commands.",
+            failFastWhenUnsupported: "Check agentContractVersion before planning.",
         },
     };
 }
@@ -1777,6 +1875,19 @@ function requiredPlanFlag(flags, name, usage) {
         return value.trim();
     throw new UsageError(`--${name} is required. Usage: ${usage}`);
 }
+/**
+ * Optional caller-chosen identifier. Absent selects the command's generated
+ * mode; a present-but-empty value is an input error, never a silent omission.
+ */
+function optionalPlanFlag(flags, name, usage) {
+    const value = flags[name];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new UsageError(`--${name} must not be empty when supplied; omit --${name} entirely to generate the successor key during apply. Usage: ${usage}`, "validation_failed");
+    }
+    return value.trim();
+}
 function optionalJsonFlag(flags, name) {
     const value = flags[name];
     return typeof value === "string" ? parseJsonObject(value, `--${name}`) : undefined;
@@ -1801,6 +1912,9 @@ function querySuffix(params) {
     const raw = search.toString();
     return raw ? `?${raw}` : "";
 }
+function projectFolderEndpoint(folderId) {
+    return `/public/api/project-folders/${encodeURIComponent(folderId)}`;
+}
 /**
  * Git and future API mount. The official Python client mounts these routes on
  * `/dip/publicapi`, which is also what the project-git resource uses; do not
@@ -1845,6 +1959,92 @@ function validatedPlanRepositoryUrl(url, flag, usage) {
     }
     return candidate;
 }
+function pluginRootEndpoint(pluginId, suffix) {
+    return `/public/api/plugins/${encodeURIComponent(pluginId)}${suffix}`;
+}
+function pluginActionEndpoint(pluginId, action) {
+    return pluginRootEndpoint(pluginId, `/actions/${action}`);
+}
+function pluginContentsEndpoint(pluginId, contentPath) {
+    return `${pluginRootEndpoint(pluginId, "/contents/")}${encodePluginSegmentsForPlan(contentPath)}`;
+}
+function pluginFoldersEndpoint(pluginId, contentPath) {
+    return `${pluginRootEndpoint(pluginId, "/folders/")}${encodePluginSegmentsForPlan(contentPath)}`;
+}
+/** Encodes a plugin content path per segment for plan-time endpoints. */
+function encodePluginSegmentsForPlan(contentPath) {
+    return contentPath.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+}
+/**
+ * Plan payload for plugin git install/update bodies. The repository URL is
+ * validated (embedded userinfo rejected) and secrets are never echoed: the
+ * plan carries the URL only, never embedded credentials.
+ */
+function pluginGitPlanPayload(flags) {
+    const repository = requiredPlanFlag(flags, "repository", "dss plugin install-from-git --repository URL");
+    const payload = {
+        gitRepositoryUrl: validatedPlanRepositoryUrl(repository, "repository", "--repository URL"),
+    };
+    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"];
+    if (typeof projectKey !== "string" || projectKey.trim() === "")
+        return "";
+    return `?projectKey=${encodeURIComponent(projectKey.trim())}`;
+}
+function settingsConfigKeys(flags) {
+    const content = flags["content"];
+    if (typeof content !== "string")
+        return [];
+    try {
+        const parsed = JSON.parse(content);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return [];
+        return Object.keys(parsed);
+    }
+    catch {
+        return [];
+    }
+}
+function contentSourceKind(flags) {
+    if (flags["stdin"] === true)
+        return "stdin";
+    if (typeof flags["file"] === "string")
+        return "file";
+    if (typeof flags["content"] === "string")
+        return "content";
+    return "unknown";
+}
+/**
+ * Plan-safe view of a user create/update body: password values are replaced by
+ * a fixed marker so secrets never appear in --plan output.
+ */
+function redactedUserPayload(payload) {
+    if (payload["password"] === undefined)
+        return payload;
+    return { ...payload, password: "<omitted>", };
+}
+/**
+ * Plan-safe view of a connection create/update body: the connection-type
+ * specific `params` object may carry credentials (passwords, keys, tokens), so
+ * the plan carries only the marker, never the raw params.
+ */
+function redactedConnectionPayload(payload) {
+    if (payload["params"] === undefined)
+        return payload;
+    return { ...payload, params: "<omitted; may include credentials>", };
+}
+/** Required CSV flag for plans (comma-separated logins list). */
+function requiredPlanCsv(flags, name, usage) {
+    const raw = requiredPlanFlag(flags, name, usage);
+    return raw.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
 function requiredPlanRepositoryUrl(flags, flag, usage) {
     const url = requiredPlanFlag(flags, flag, usage);
     return validatedPlanRepositoryUrl(url, flag, usage);
@@ -2074,8 +2274,8 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         case "future.abort":
             return {
-                method: "POST",
-                endpoint: `/public/api/futures/${encodeURIComponent(id)}/abort`,
+                method: "DELETE",
+                endpoint: `/public/api/futures/${encodeURIComponent(id)}`,
                 identifiers: { id, },
             };
         case "flow-zone.create": {
@@ -2203,8 +2403,38 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 method: "PUT",
                 endpoint: projectEndpoint(`/datasets/${encodeURIComponent(id)}`),
                 identifiers: { name: id, },
+            };
+        case "dataset.metadata-set":
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint(`/datasets/${encodeURIComponent(id)}/metadata`),
+                identifiers: { name: id, },
                 payload: requiredPlanJsonInput(flags, entry.usage),
             };
+        case "dataset.create-managed": {
+            const name = requiredPlanFlag(flags, "name", entry.usage);
+            const connection = requiredPlanFlag(flags, "connection", entry.usage);
+            const creationSettings = { connectionId: connection, };
+            const specificSettings = {};
+            if (typeof flags["type-option-id"] === "string") {
+                creationSettings.typeOptionId = flags["type-option-id"];
+            }
+            if (typeof flags["format-option-id"] === "string") {
+                specificSettings.formatOptionId = flags["format-option-id"];
+            }
+            if (typeof flags["copy-partitioning-from"] === "string") {
+                specificSettings.partitioningOptionId = `copy:${flags["partitioning-folder"] === true ? "folder" : "dataset"}:${flags["copy-partitioning-from"]}`;
+            }
+            if (Object.keys(specificSettings).length > 0) {
+                creationSettings.specificSettings = specificSettings;
+            }
+            return {
+                method: "POST",
+                endpoint: projectEndpoint("/datasets/managed"),
+                identifiers: { name, },
+                payload: { name, creationSettings, },
+            };
+        }
         case "recipe.add-input":
         case "recipe.remove-input": {
             const role = flags["role"] ?? "main";
@@ -2393,6 +2623,42 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 payload: jobBuildPayload(id, projectKey, flags),
                 wait: action === "build-and-wait" || flags["wait"] === true,
             };
+        case "scenario.abort":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/scenarios/${encodeURIComponent(id)}/abort`),
+                identifiers: { id, },
+            };
+        case "scenario.payload-set":
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint(`/scenarios/${encodeURIComponent(id)}/payload`),
+                identifiers: { id, },
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "scenario.active-set": {
+            const activeRaw = args[1];
+            if (activeRaw !== "true" && activeRaw !== "false") {
+                throw new UsageError(`Usage: ${entry.usage}`);
+            }
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint(`/scenarios/${encodeURIComponent(id)}/light`),
+                identifiers: { id, },
+                payload: { id, active: activeRaw === "true", },
+            };
+        }
+        case "folder.create": {
+            const name = requiredPlanFlag(flags, "name", entry.usage);
+            const type = flags["type"];
+            const connection = flags["connection"];
+            return {
+                method: "POST",
+                endpoint: projectEndpoint("/managedfolders/"),
+                identifiers: { name, },
+                payload: { name, type, connection, path: flags["path"], projectKey, },
+            };
+        }
         case "job.abort":
             return {
                 method: "POST",
@@ -2433,17 +2699,6 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: { id, },
                 payload: requiredPlanJsonInput(flags, entry.usage),
             };
-        case "folder.create": {
-            const name = requiredPlanFlag(flags, "name", entry.usage);
-            const type = flags["type"];
-            const connection = flags["connection"];
-            return {
-                method: "POST",
-                endpoint: projectEndpoint("/managedfolders/"),
-                identifiers: { name, },
-                payload: { name, type, connection, path: flags["path"], projectKey, },
-            };
-        }
         case "folder.update":
             return {
                 method: "PUT",
@@ -2668,6 +2923,577 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 endpoint: `/public/api/meanings/${encodeURIComponent(id)}`,
                 identifiers: { id, },
             };
+        case "llm.list": {
+            const params = new URLSearchParams();
+            const purpose = flags["purpose"];
+            if (typeof purpose === "string" && purpose.trim() !== "") {
+                params.set("purpose", purpose.trim());
+            }
+            const query = params.size > 0 ? `?${params.toString()}` : "";
+            return {
+                method: "GET",
+                endpoint: projectEndpoint(`/llms/${query}`),
+            };
+        }
+        case "llm.completions":
+        case "llm.embeddings": {
+            const payload = requiredPlanJsonInput(flags, entry.usage);
+            const llmId = stringField(payload, ["llmId",]);
+            if (llmId === undefined || llmId.trim() === "") {
+                throw new UsageError(`llmId is required and must be a non-empty string (e.g. "openai:openai1:gpt-4").\nUsage: ${entry.usage}`, "invalid_flag_value");
+            }
+            const queries = payload["queries"];
+            if (!Array.isArray(queries) || queries.length === 0) {
+                throw new UsageError(`queries is required and must be a non-empty array of query objects.\nUsage: ${entry.usage}`, "invalid_flag_value");
+            }
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(action === "completions" ? "/llms/completions" : "/llms/embeddings"),
+                identifiers: { llmId, },
+                payload,
+            };
+        }
+        case "knowledge-bank.search": {
+            if (typeof id !== "string" || id.trim() === "") {
+                throw new UsageError(`knowledgeBankId must be a non-empty string.\nUsage: ${entry.usage}`, "invalid_flag_value");
+            }
+            const payload = requiredPlanJsonInput(flags, entry.usage);
+            const query = stringField(payload, ["query",]);
+            if (query === undefined || query.trim() === "") {
+                throw new UsageError(`query is required and must be a non-empty string.\nUsage: ${entry.usage}`, "invalid_flag_value");
+            }
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/knowledge-banks/${encodeURIComponent(id)}/search`),
+                identifiers: { knowledgeBankId: id, },
+                payload,
+            };
+        }
+        case "knowledge-bank.clear":
+            if (typeof id !== "string" || id.trim() === "") {
+                throw new UsageError(`knowledgeBankId must be a non-empty string.\nUsage: ${entry.usage}`, "invalid_flag_value");
+            }
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/knowledge-banks/${encodeURIComponent(id)}/clear`),
+                identifiers: { knowledgeBankId: id, },
+            };
+        case "data-collection.create":
+            return {
+                method: "POST",
+                endpoint: "/public/api/data-collections/",
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "data-collection.settings-set":
+            return {
+                method: "PUT",
+                endpoint: `/public/api/data-collections/${encodeURIComponent(id)}`,
+                identifiers: { dataCollectionId: id, },
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "data-collection.delete":
+            return {
+                method: "DELETE",
+                endpoint: `/public/api/data-collections/${encodeURIComponent(id)}`,
+                identifiers: { dataCollectionId: id, },
+            };
+        case "data-collection.add-object": {
+            const payload = requiredPlanJsonInput(flags, entry.usage);
+            const cid = id
+                ?? (typeof payload["dataCollectionId"] === "string"
+                    ? payload["dataCollectionId"]
+                    : undefined);
+            if (!cid)
+                throw new UsageError(`Usage: ${entry.usage}`);
+            const reference = { ...payload, };
+            delete reference["dataCollectionId"];
+            return {
+                method: "POST",
+                endpoint: `/public/api/data-collections/${encodeURIComponent(cid)}/objects`,
+                identifiers: { dataCollectionId: cid, },
+                payload: reference,
+            };
+        }
+        case "data-collection.remove-dataset": {
+            const projectKeyArg = args[1];
+            const datasetName = args[2];
+            if (!projectKeyArg || !datasetName) {
+                throw new UsageError(`Usage: ${entry.usage}`);
+            }
+            return {
+                method: "DELETE",
+                endpoint: `/public/api/data-collections/${encodeURIComponent(id)}/objects/dataset/${encodeURIComponent(projectKeyArg)}/${encodeURIComponent(datasetName)}`,
+                identifiers: { dataCollectionId: id, projectKey: projectKeyArg, datasetName, },
+            };
+        }
+        case "project.tags-set":
+            return {
+                method: "PUT",
+                endpoint: encodedProjectEndpointForPlan(projectKey ?? requiredPlanProjectKey(flags, entry.usage), "/tags"),
+                identifiers: { projectKey: projectKey ?? requiredPlanProjectKey(flags, entry.usage), },
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "project.metadata-set":
+            return {
+                method: "PUT",
+                endpoint: encodedProjectEndpointForPlan(projectKey ?? requiredPlanProjectKey(flags, entry.usage), "/metadata"),
+                identifiers: { projectKey: projectKey ?? requiredPlanProjectKey(flags, entry.usage), },
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "macro.run":
+        case "macro.run-and-wait": {
+            // The plan payload mirrors the live POST body exactly: params and
+            // adminParams when provided via --data, {} otherwise. Validation is
+            // identical to the live path (JSON object shape), zero network.
+            const data = optionalJsonFlag(flags, "data");
+            const runPayload = {};
+            if (data && typeof data === "object" && !Array.isArray(data)) {
+                if (data["params"] !== undefined)
+                    runPayload["params"] = data["params"];
+                if (data["adminParams"] !== undefined)
+                    runPayload["adminParams"] = data["adminParams"];
+            }
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/runnables/${encodeURIComponent(id)}?wait=false`),
+                identifiers: { id, },
+                payload: runPayload,
+                wait: action === "macro.run-and-wait" || flags["wait"] === true,
+            };
+        }
+        case "macro.abort": {
+            const runId = args[1];
+            if (!runId)
+                throw new UsageError(`Usage: ${entry.usage}`);
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/runnables/${encodeURIComponent(id)}/abort/${encodeURIComponent(runId)}`),
+                identifiers: { id, runId, },
+            };
+        }
+        case "recipe.metadata-set":
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint(`/recipes/${encodeURIComponent(id)}/metadata`),
+                identifiers: { recipeName: id, },
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "user.create":
+            return {
+                method: "POST",
+                endpoint: "/public/api/admin/users",
+                payload: redactedUserPayload(requiredPlanJsonInput(flags, entry.usage)),
+            };
+        case "group.create":
+            return {
+                method: "POST",
+                endpoint: "/public/api/admin/groups",
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "saved-model.create-external": {
+            const config = optionalJsonFlag(flags, "configuration") ?? optionalJsonFlag(flags, "data");
+            return {
+                method: "POST",
+                endpoint: projectEndpoint("/savedmodels/"),
+                identifiers: { name: id, },
+                payload: {
+                    savedModelType: requiredPlanFlag(flags, "type", entry.usage),
+                    name: id,
+                    ...(typeof flags["prediction-type"] === "string"
+                        ? { predictionType: flags["prediction-type"], }
+                        : {}),
+                    ...(config ? { proxyModelConfiguration: config, } : {}),
+                },
+            };
+        }
+        case "saved-model.update-settings":
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint(`/savedmodels/${encodeURIComponent(id)}`),
+                identifiers: { savedModelId: id, },
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "saved-model.delete-versions": {
+            const versionsRaw = args[1];
+            if (typeof versionsRaw !== "string" || versionsRaw.trim() === "") {
+                throw new UsageError(`Usage: ${entry.usage}`);
+            }
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/savedmodels/${encodeURIComponent(id)}/actions/delete-versions`),
+                identifiers: { savedModelId: id, },
+                payload: {
+                    versions: versionsRaw.split(",").map((v) => v.trim()).filter((v) => v.length > 0),
+                    removeIntermediate: parseBooleanOption(flags["remove-intermediate"], "--remove-intermediate") ?? true,
+                },
+            };
+        }
+        case "saved-model.import-mlflow-version":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/savedmodels/${encodeURIComponent(id)}/versions/${encodeURIComponent(args[1] ?? "")}`),
+                identifiers: { savedModelId: id, versionId: args[1], },
+                payload: {
+                    source: { kind: "local-archive", archive: requiredPlanFlag(flags, "archive", entry.usage), },
+                    ...(typeof flags["code-env"] === "string"
+                        ? { codeEnvName: flags["code-env"], }
+                        : {}),
+                    // Execute always sends the query parameter with the
+                    // external-caller default NONE; the plan mirrors it.
+                    containerExecConfigName: typeof flags["container-exec-config"] === "string"
+                        ? flags["container-exec-config"]
+                        : "NONE",
+                    setActive: parseBooleanOption(flags["set-active"], "--set-active") ?? true,
+                    ...(flags["binary-classification-threshold"] !== undefined
+                        ? {
+                            binaryClassificationThreshold: num(flags["binary-classification-threshold"], "--binary-classification-threshold"),
+                        }
+                        : {}),
+                },
+            };
+        case "saved-model.import-mlflow-version-from-folder":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/savedmodels/${encodeURIComponent(id)}/versions/${encodeURIComponent(args[1] ?? "")}`),
+                identifiers: { savedModelId: id, versionId: args[1], },
+                payload: {
+                    source: {
+                        kind: "managed-folder",
+                        folderRef: requiredPlanFlag(flags, "folder", entry.usage),
+                        path: flags["path"],
+                    },
+                    ...(typeof flags["code-env"] === "string" ? { codeEnvName: flags["code-env"], } : {}),
+                    // Execute always sends the query parameter with the
+                    // external-caller default NONE; the plan mirrors it.
+                    containerExecConfigName: typeof flags["container-exec-config"] === "string"
+                        ? flags["container-exec-config"]
+                        : "NONE",
+                    setActive: parseBooleanOption(flags["set-active"], "--set-active") ?? true,
+                },
+            };
+        case "saved-model.external-metadata-put": {
+            // DSS requires containerExecConfigName on this endpoint; for an
+            // external API caller it resolves as LOCAL-CONFIG -> NONE, so the
+            // plan mirrors the NONE default unless --container-exec-config
+            // overrides it. Same contract as execute.
+            const containerExecConfigName = typeof flags["container-exec-config"] === "string"
+                ? flags["container-exec-config"]
+                : "NONE";
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint(`/savedmodels/${encodeURIComponent(id)}/versions/${encodeURIComponent(args[1] ?? "")}/external-ml/metadata?containerExecConfigName=${encodeURIComponent(containerExecConfigName)}`),
+                identifiers: { savedModelId: id, versionId: args[1], },
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        }
+        case "saved-model.evaluate-version": {
+            const payload = {
+                datasetRef: requiredPlanFlag(flags, "dataset", entry.usage),
+                // Execute always sends an explicit containerExecConfigName
+                // (official external-caller semantics: LOCAL-CONFIG -> NONE);
+                // the plan mirrors that default and any explicit override.
+                containerExecConfigName: typeof flags["container-exec-config"] === "string"
+                    ? flags["container-exec-config"]
+                    : "NONE",
+            };
+            // --sampling is a JSON flag value; the plan carries the parsed
+            // object under the same key as the execute body (samplingParam).
+            if (flags["sampling"] !== undefined) {
+                payload.samplingParam = json(flags["sampling"], "--sampling");
+            }
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/savedmodels/${encodeURIComponent(id)}/versions/${encodeURIComponent(args[1] ?? "")}/external-ml/actions/evaluate`),
+                identifiers: { savedModelId: id, versionId: args[1], },
+                payload,
+            };
+        }
+        case "saved-model.set-user-meta":
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint(`/savedmodels/${encodeURIComponent(id)}/versions/${encodeURIComponent(args[1] ?? "")}/user-meta`),
+                identifiers: { savedModelId: id, versionId: args[1], },
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "user.update":
+            return {
+                method: "PUT",
+                endpoint: `/public/api/admin/users/${encodeURIComponent(id)}`,
+                identifiers: { login: id, },
+                payload: redactedUserPayload(requiredPlanJsonInput(flags, entry.usage)),
+            };
+        case "user.delete":
+        case "group.delete":
+            return {
+                method: "DELETE",
+                endpoint: resource === "user"
+                    ? `/public/api/admin/users/${encodeURIComponent(id)}`
+                    : `/public/api/admin/groups/${encodeURIComponent(id)}`,
+                identifiers: resource === "user" ? { login: id, } : { name: id, },
+            };
+        case "user.resync":
+            return {
+                method: "POST",
+                endpoint: `/public/api/admin/users/${encodeURIComponent(id)}/actions/resync`,
+                identifiers: { login: id, },
+            };
+        case "user.resync-multi": {
+            const logins = requiredPlanCsv(flags, "logins", entry.usage);
+            return {
+                method: "POST",
+                endpoint: "/public/api/admin/users/actions/resync-multi",
+                identifiers: { count: logins.length, },
+                payload: logins,
+            };
+        }
+        case "user.external-users":
+            return {
+                method: "GET",
+                endpoint: "/public/api/admin/users/actions/external-users",
+            };
+        case "user.external-groups":
+            return {
+                method: "GET",
+                endpoint: "/public/api/admin/users/actions/external-groups",
+            };
+        case "connection.test":
+            return {
+                method: "GET",
+                endpoint: `/public/api/connections/${encodeURIComponent(id)}/test`,
+                identifiers: { connectionName: id, },
+            };
+        case "user.provision":
+            return {
+                method: "POST",
+                endpoint: "/public/api/admin/users/actions/provision",
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "group.update":
+            return {
+                method: "PUT",
+                endpoint: `/public/api/admin/groups/${encodeURIComponent(id)}`,
+                identifiers: { name: id, },
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "connection.create":
+            return {
+                method: "POST",
+                endpoint: "/public/api/admin/connections",
+                payload: redactedConnectionPayload(requiredPlanJsonInput(flags, entry.usage)),
+            };
+        case "connection.update":
+            return {
+                method: "PUT",
+                endpoint: `/public/api/admin/connections/${encodeURIComponent(id)}`,
+                identifiers: { connectionName: id, },
+                payload: redactedConnectionPayload(requiredPlanJsonInput(flags, entry.usage)),
+            };
+        case "connection.delete":
+            return {
+                method: "DELETE",
+                endpoint: `/public/api/admin/connections/${encodeURIComponent(id)}`,
+                identifiers: { connectionName: id, },
+            };
+        case "connection.prepare-import": {
+            const payload = requiredPlanJsonInput(flags, entry.usage);
+            if (!projectKey)
+                throw new UsageError(`Missing project key for ${resource} ${action}.`);
+            return {
+                method: "POST",
+                endpoint: encodedProjectEndpointForPlan(projectKey, "/datasets/tables-import/actions/prepare-from-keys"),
+                identifiers: { projectKey, },
+                payload,
+            };
+        }
+        case "connection.execute-import": {
+            const payload = requiredPlanJsonInput(flags, entry.usage);
+            if (!projectKey)
+                throw new UsageError(`Missing project key for ${resource} ${action}.`);
+            return {
+                method: "POST",
+                endpoint: encodedProjectEndpointForPlan(projectKey, "/datasets/tables-import/actions/execute-from-candidates"),
+                identifiers: { projectKey, },
+                payload,
+            };
+        }
+        case "plugin.install-from-zip":
+            return {
+                method: "POST",
+                endpoint: "/public/api/plugins/actions/installFromZip",
+                payload: { file: requiredPlanFlag(flags, "file", entry.usage), upload: "multipart", },
+            };
+        case "plugin.install-from-store":
+            return {
+                method: "POST",
+                endpoint: "/public/api/plugins/actions/installFromStore",
+                identifiers: { pluginId: id, },
+                payload: { pluginId: id, },
+            };
+        case "plugin.install-from-git": {
+            const payload = pluginGitPlanPayload(flags);
+            return {
+                method: "POST",
+                endpoint: "/public/api/plugins/actions/installFromGit",
+                payload,
+            };
+        }
+        case "plugin.update-from-zip":
+            return {
+                method: "POST",
+                endpoint: pluginActionEndpoint(id, "updateFromZip"),
+                identifiers: { pluginId: id, },
+                payload: { file: requiredPlanFlag(flags, "file", entry.usage), upload: "multipart", },
+            };
+        case "plugin.update-from-store":
+            return {
+                method: "POST",
+                endpoint: pluginActionEndpoint(id, "updateFromStore"),
+                identifiers: { pluginId: id, },
+            };
+        case "plugin.update-from-git":
+            return {
+                method: "POST",
+                endpoint: pluginActionEndpoint(id, "updateFromGit"),
+                identifiers: { pluginId: id, },
+                payload: pluginGitPlanPayload(flags),
+            };
+        case "plugin.settings-set": {
+            const scope = optionalPlanProjectScope(flags);
+            return {
+                method: "POST",
+                endpoint: `${pluginRootEndpoint(id, "/settings")}${scope}`,
+                identifiers: { pluginId: id, },
+                payload: { configKeys: settingsConfigKeys(flags), },
+            };
+        }
+        case "plugin.code-env-create": {
+            const conda = parseBooleanOption(flags["conda"], "--conda") ?? false;
+            return {
+                method: "POST",
+                endpoint: `${pluginRootEndpoint(id, "/code-env/actions/create")}`,
+                identifiers: { pluginId: id, },
+                payload: {
+                    deploymentMode: "PLUGIN_MANAGED",
+                    conda,
+                    pythonInterpreter: flags["python-interpreter"] ?? null,
+                },
+                wait: flags["wait"] === true,
+            };
+        }
+        case "plugin.code-env-update":
+            return {
+                method: "POST",
+                endpoint: `${pluginRootEndpoint(id, "/code-env/actions/update")}`,
+                identifiers: { pluginId: id, },
+                wait: flags["wait"] === true,
+            };
+        case "plugin.move-to-dev":
+            return {
+                method: "POST",
+                endpoint: pluginActionEndpoint(id, "moveToDev"),
+                identifiers: { pluginId: id, },
+            };
+        case "plugin.delete":
+            return {
+                method: "POST",
+                endpoint: pluginActionEndpoint(id, "delete"),
+                identifiers: { pluginId: id, },
+                payload: { force: parseBooleanOption(flags["force"], "--force") ?? false, },
+            };
+        case "plugin.create-dev": {
+            const creationMode = requiredPlanFlag(flags, "creation-mode", entry.usage);
+            const payload = {
+                pluginId: id,
+                creationMode,
+            };
+            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",
+                identifiers: { pluginId: id, creationMode, },
+                payload,
+            };
+        }
+        case "plugin.set-git-remote": {
+            const repository = requiredPlanFlag(flags, "repository", entry.usage);
+            return {
+                method: "POST",
+                endpoint: `${pluginRootEndpoint(id, "/gitRemote")}`,
+                identifiers: { pluginId: id, },
+                payload: { repositoryUrl: validatedPlanRepositoryUrl(repository, "repository", entry.usage), },
+            };
+        }
+        case "plugin.delete-git-remote":
+            return {
+                method: "DELETE",
+                endpoint: pluginRootEndpoint(id, "/gitRemote"),
+                identifiers: { pluginId: id, },
+            };
+        case "plugin.push":
+        case "plugin.pull":
+        case "plugin.fetch":
+        case "plugin.reset-local":
+        case "plugin.reset-remote": {
+            const actionMap = {
+                "plugin.push": "push",
+                "plugin.pull": "pullRebase",
+                "plugin.fetch": "fetch",
+                "plugin.reset-local": "resetToLocalHeadState",
+                "plugin.reset-remote": "resetToRemoteHeadState",
+            };
+            return {
+                method: "POST",
+                endpoint: pluginActionEndpoint(id, actionMap[`${resource}.${action}`]),
+                identifiers: { pluginId: id, },
+            };
+        }
+        case "plugin.contents-put":
+            return {
+                method: "POST",
+                endpoint: pluginContentsEndpoint(id, args[1] ?? ""),
+                identifiers: { pluginId: id, path: args[1], },
+                payload: { contentSource: contentSourceKind(flags), },
+            };
+        case "plugin.contents-delete":
+            return {
+                method: "DELETE",
+                endpoint: pluginContentsEndpoint(id, args[1] ?? ""),
+                identifiers: { pluginId: id, path: args[1], },
+            };
+        case "plugin.folder-add":
+            return {
+                method: "POST",
+                endpoint: pluginFoldersEndpoint(id, args[1] ?? ""),
+                identifiers: { pluginId: id, path: args[1], },
+            };
+        case "plugin.rename": {
+            const newName = requiredPlanPositionals(entry.usage)[2];
+            if (!newName)
+                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], },
+            };
+        }
+        case "plugin.move": {
+            const destination = args[2];
+            if (!destination)
+                throw new UsageError(`Usage: ${entry.usage}`);
+            return {
+                method: "POST",
+                endpoint: `${pluginRootEndpoint(id, "/contents-actions/move")}`,
+                identifiers: { pluginId: id, path: args[1], },
+                payload: { oldPath: args[1], newPath: destination, },
+            };
+        }
         case "business-app.save-settings":
             return {
                 method: "PUT",
@@ -2707,6 +3533,42 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
         }
         case "app.create-instance": {
             const payload = requiredPlanJsonInput(flags, entry.usage);
+            if (payload["targetProjectKey"] === undefined) {
+                // Generated-at-apply mode: --plan never allocates or reserves a
+                // random key. The payload stays exactly as supplied, the runtime
+                // generates the key (and defaults the display name to it) during
+                // apply, and no absence probe runs for a generated key, so the
+                // plan carries no preflight requests and no fake concrete GET
+                // path: `{targetProjectKey}` resolves at apply time.
+                return {
+                    method: "POST",
+                    endpoint: `/public/api/apps/${encodeURIComponent(id)}/instances`,
+                    identifiers: {
+                        appId: id,
+                        targetProjectKeyGeneratedDuringApply: true,
+                        ...(payload["targetProjectName"] === undefined
+                            ? { targetProjectNameGeneratedDuringApply: true, }
+                            : {}),
+                        preflightExecuted: false,
+                        preflightWillRunDuringApply: false,
+                        preflightRequests: [],
+                        incarnationControl: "client-side-non-atomic-future-target-and-creation-tag-join",
+                        incarnationObservationRequests: [
+                            {
+                                method: "GET",
+                                endpointTemplate: "/public/api/projects/{targetProjectKey}/",
+                                when: flags["wait"] === true
+                                    ? "after-terminal-future-target"
+                                    : "conditional-inline-hasResult-target",
+                                intent: "After DSS reports inline or terminal creation success for the generated key, observe creationTag for later cleanup binding.",
+                            },
+                        ],
+                        note: "Generated-at-apply: a random APP_ targetProjectKey is generated client-side during apply (never at plan time); targetProjectName defaults to it when omitted. No absent-project preflight runs for a generated key.",
+                    },
+                    payload,
+                    wait: flags["wait"] === true,
+                };
+            }
             const rawTargetProjectKey = stringField(payload, ["targetProjectKey",]);
             if (!rawTargetProjectKey || rawTargetProjectKey.trim() === "") {
                 throw new UsageError("Instance creation payload must include a non-empty targetProjectKey.", "validation_failed", `Usage: ${entry.usage}`);
@@ -2799,13 +3661,110 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
         }
         case "app.create-successor-instance": {
             const sourceProjectKey = requiredPlanFlag(flags, "from", entry.usage);
-            const targetProjectKey = requiredPlanFlag(flags, "to", entry.usage);
-            if (sourceProjectKey === targetProjectKey) {
+            const targetProjectKey = optionalPlanFlag(flags, "to", entry.usage);
+            if (targetProjectKey !== undefined && sourceProjectKey === targetProjectKey) {
                 throw new UsageError("--from and --to must be different project keys.", "validation_failed", `Usage: ${entry.usage}`);
             }
             const targetProjectName = flags["name"];
             const copyPermissions = parseBooleanOption(flags["copy-permissions"], "--copy-permissions")
                 ?? false;
+            if (targetProjectKey === undefined) {
+                // Generated-at-apply mode: --plan never allocates a key and no
+                // target exists yet, so the plan makes no target-absence claim
+                // and advertises no target probe. The key is generated once
+                // during apply, immediately before the single instance POST;
+                // `{targetProjectKey}` resolves only after the terminal future
+                // names it. Source and template gates still run before the POST.
+                return {
+                    method: "POST",
+                    endpoint: `/public/api/apps/${encodeURIComponent(id)}/instances`,
+                    identifiers: {
+                        appId: id,
+                        sourceProjectKey,
+                        targetProjectKeyGeneratedDuringApply: true,
+                        targetPreflight: "not-applicable-generated-key",
+                        preflightExecuted: false,
+                        preflightWillRunDuringApply: true,
+                        ...(targetProjectName !== undefined
+                            ? { targetProjectName, }
+                            : { targetProjectNameGeneratedDuringApply: true, }),
+                        copyPermissions,
+                        incarnationControl: "client-side-non-atomic-future-target-and-creation-tag-join",
+                        incarnationObservationRequests: [
+                            {
+                                method: "GET",
+                                endpointTemplate: "/public/api/projects/{targetProjectKey}/",
+                                when: "after-terminal-future-target",
+                                intent: "After the terminal future names the generated successor key, observe creationTag and bind later target checks and cleanup to that hash.",
+                            },
+                        ],
+                        preflightRequests: [
+                            {
+                                method: "GET",
+                                endpoint: `/public/api/apps/${encodeURIComponent(id)}/instances/`,
+                                when: "before-create",
+                                intent: "Verify the --from project is a registered instance of the app.",
+                            },
+                            {
+                                method: "GET",
+                                endpoint: `/public/api/projects/${encodeURIComponent(sourceProjectKey)}/app-manifest`,
+                                when: "before-create",
+                                intent: "Verify the --from project is an APP_INSTANCE project.",
+                            },
+                        ],
+                        ...(copyPermissions
+                            ? {
+                                permissionConcurrencyControl: "client-side-non-atomic-stale-identity-and-hash-checks",
+                                permissionRequests: [
+                                    {
+                                        method: "GET",
+                                        endpoint: `/public/api/projects/${encodeURIComponent(sourceProjectKey)}/permissions`,
+                                        intent: "Snapshot the predecessor instance ACL before creation.",
+                                    },
+                                    {
+                                        method: "GET",
+                                        endpointTemplate: "/public/api/projects/{targetProjectKey}/permissions",
+                                        intent: "Read the generated successor ACL to decide whether the copy is a no-op.",
+                                    },
+                                    {
+                                        method: "GET",
+                                        endpointTemplate: "/public/api/projects/{targetProjectKey}/",
+                                        intent: "Recheck generated successor creationTag after reading its ACL; stop if the project key was reused.",
+                                    },
+                                    {
+                                        method: "GET",
+                                        endpoint: `/public/api/projects/${encodeURIComponent(sourceProjectKey)}/permissions`,
+                                        intent: "Recheck the predecessor ACL immediately before the write and stop if its hash drifted.",
+                                    },
+                                    {
+                                        method: "GET",
+                                        endpointTemplate: "/public/api/projects/{targetProjectKey}/",
+                                        intent: "Recheck generated successor creationTag immediately before the unconditional permission PUT.",
+                                    },
+                                    {
+                                        method: "PUT",
+                                        endpointTemplate: "/public/api/projects/{targetProjectKey}/permissions",
+                                        intent: "Apply the predecessor ACL snapshot to the generated successor instance.",
+                                    },
+                                    {
+                                        method: "GET",
+                                        endpointTemplate: "/public/api/projects/{targetProjectKey}/permissions",
+                                        intent: "Verify the generated successor ACL hash equals the predecessor snapshot hash.",
+                                    },
+                                    {
+                                        method: "GET",
+                                        endpointTemplate: "/public/api/projects/{targetProjectKey}/",
+                                        intent: "Detect generated successor project-key reuse across the permission write and verification read.",
+                                    },
+                                ],
+                            }
+                            : {}),
+                        note: "Generated-at-apply: the successor key is generated once during apply (never at plan time) and no absent-project preflight runs for a generated key, so the plan claims no target absence. Source and template gates run before the single instance POST, then the terminal future's own result names the successor key. The predecessor is never modified or deleted; cleanup targets the generated successor key only.",
+                    },
+                    payload: targetProjectName !== undefined ? { targetProjectName, } : {},
+                    wait: true,
+                };
+            }
             return {
                 method: "POST",
                 endpoint: `/public/api/apps/${encodeURIComponent(id)}/instances`,
@@ -3654,7 +4613,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 wait: true,
             })}`;
             const guarded = flags["if-exists"] === true
-                || flags["dry-run"] === true
+                || executionMode(flags).dryRun
                 || expectedProjectIncarnation !== undefined;
             if (!guarded) {
                 return {
@@ -3671,7 +4630,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                     provided: true,
                     expectedHash: expectedProjectIncarnation,
                 };
-            if (flags["dry-run"] === true) {
+            if (executionMode(flags).dryRun) {
                 return {
                     method: "GET",
                     endpoint: projectProbe,
@@ -4058,6 +5017,51 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 endpoint: projectGitFutureEndpoint(id),
                 identifiers: { jobId: id, },
             };
+        case "project-folder.settings-set": {
+            const payload = requiredPlanJsonInput(flags, `--data, --data-file, or --stdin is required. Usage: ${entry.usage}`);
+            return {
+                method: "PUT",
+                endpoint: `${projectFolderEndpoint(id)}/settings`,
+                identifiers: { folderId: id, },
+                payload,
+            };
+        }
+        case "project-folder.move": {
+            const destination = args[1];
+            if (!destination)
+                throw new UsageError(`Usage: ${entry.usage}`);
+            return {
+                method: "POST",
+                endpoint: `${projectFolderEndpoint(id)}/move${querySuffix({ destination, })}`,
+                identifiers: { folderId: id, destination, },
+            };
+        }
+        case "project-folder.delete":
+            return {
+                method: "DELETE",
+                endpoint: projectFolderEndpoint(id),
+                identifiers: { folderId: id, },
+            };
+        case "project-folder.create-child": {
+            const name = requiredPlanFlag(flags, "name", entry.usage);
+            return {
+                method: "POST",
+                endpoint: `${projectFolderEndpoint(id)}/children${querySuffix({ name, })}`,
+                identifiers: { parentFolderId: id, name, },
+            };
+        }
+        case "project-folder.move-project": {
+            const projectKeyArg = args[1];
+            const destination = args[2];
+            if (!projectKeyArg || !destination) {
+                throw new UsageError(`Usage: ${entry.usage}`);
+            }
+            return {
+                method: "POST",
+                endpoint: `${projectFolderEndpoint(id)}/projects/${encodeURIComponent(projectKeyArg)}/move${querySuffix({ destination, })}`,
+                identifiers: { folderId: id, projectKey: projectKeyArg, destination, },
+            };
+        }
         default:
             return {
                 exact: false,
@@ -4080,7 +5084,7 @@ export function buildMutationPlan(resource, action, meta, args, flags) {
         asyncKind: entry.async,
         exitCodesOnFailure: exitCodesOnFailure(entry),
         idempotency: entry.idempotency,
-        plannedAndDryRun: flags["dry-run"] === true,
+        plannedAndDryRun: executionMode(flags).dryRun,
     });
 }
 /**