dataiku-sdk 0.12.7 → 1.1.0

package/dist/src/cli/contract.js

@@ -4,7 +4,7 @@ import { validateCredentials, } from "../auth.js";
 import { getCredentialsPath, saveCredentials, } from "../config.js";
 import { DataikuError, } from "../errors.js";
 import { APP_MANIFEST_CONCURRENCY_CONTROL, } from "../resources/applications.js";
-import { jobBuildTargetTypeFromFlags, json, jsonInput, num, parseBooleanOption, parseJsonObject, requiredJsonInput, rewritePairsFromFlags, schemaColumnsInput, stringField, textInput, } from "./coerce.js";
+import { jobBuildTargetTypeFromFlags, json, jsonInput, num, parseBooleanOption, parseJsonObject, recipeInputDatasetsFromFlags, requiredJsonInput, rewritePairsFromFlags, schemaColumnsInput, stringField, textInput, } from "./coerce.js";
 import { commands, } from "./commands/index.js";
 import { dataikuEnvironmentEnabled, } from "./env.js";
 import { BOOLEAN_FLAGS, FLAG_ALIASES, KNOWN_LONG_FLAGS, SHORT_FLAGS, } from "./flags.js";
@@ -151,7 +151,64 @@ const PROJECT_SCOPED_RESOURCES = new Set([
     "saved-model",
     "wiki",
 ]);
-const GLOBAL_AGENT_FLAGS = ["json", "verbose", "fields",];
+/**
+ * Project Git actions that only observe repository state. Everything else in the
+ * `project-git` resource is a mutation: the verb-shaped names (`fetch`, `pull`,
+ * `switch`, `commit`, `reset-*`, `revert-*`, `drop-and-rebuild`, `future-abort`)
+ * match none of the mutating-verb patterns and would otherwise fall through to
+ * the read default, advertising network and history writes as safe reads.
+ */
+const PROJECT_GIT_READ_ACTIONS = {
+    branches: true,
+    "current-branch": true,
+    diff: true,
+    "future-status": true,
+    "future-wait": true,
+    "get-remote": true,
+    "list-libraries": true,
+    log: true,
+    status: true,
+    tags: true,
+};
+/**
+ * Git mutations that destroy work rather than add to it: `drop-and-rebuild`
+ * discards the repository and rebuilds it from DSS, the resets and reverts throw
+ * away local commits or working state, `remove-library` can delete the checked
+ * out directory, and the branch/tag deletions can remove remote refs.
+ */
+const PROJECT_GIT_DESTRUCTIVE_ACTIONS = {
+    "delete-branch": true,
+    "delete-tag": true,
+    "drop-and-rebuild": true,
+    "future-abort": true,
+    "remove-library": true,
+    "reset-all-libraries": true,
+    "reset-library": true,
+    "reset-to-head": true,
+    "reset-to-upstream": true,
+    "revert-commit": true,
+    "revert-to-revision": true,
+};
+/** Project Git actions that hand back a DSS future (`{jobId}`) instead of a result. */
+const PROJECT_GIT_FUTURE_ACTIONS = {
+    "add-library": true,
+    "future-abort": true,
+    "future-status": true,
+    "future-wait": true,
+    "push-all-libraries": true,
+    "push-library": true,
+    "reset-all-libraries": true,
+    "reset-library": true,
+};
+/** Git mutations that converge: replaying them lands on the same repository state. */
+const PROJECT_GIT_CONVERGENT_ACTIONS = {
+    fetch: true,
+    "reset-all-libraries": true,
+    "reset-library": true,
+    "reset-to-head": true,
+    "reset-to-upstream": true,
+};
+const GLOBAL_AGENT_FLAGS = ["verbose", "fields",];
 const AUTHENTICATED_AGENT_FLAGS = [
     "url",
     "api-key",
@@ -160,22 +217,24 @@ const AUTHENTICATED_AGENT_FLAGS = [
     "insecure",
     "ca-cert",
 ];
-export const COMMANDS_USAGE = "dss commands run [--fields PATHS] [--json]";
-const COMMANDS_DESCRIPTION = "Print the machine-readable command registry for agent planning; scope it with --fields RESOURCE, RESOURCE.ACTION, or RESOURCE.ACTION.FIELD instead of reading the whole registry.";
+export const COMMANDS_USAGE = "dss commands run [--fields PATHS] [--output PATH]";
+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 --fields dataset --json",
-    "dss commands run --fields dataset.create --json",
-    "dss commands run --fields dataset.create.usage,dataset.create.description,dataset.create.flags,dataset.create.examples --json",
+    "dss commands run",
+    "dss commands run --fields dataset",
+    "dss commands run --fields dataset.create",
+    "dss commands run --fields dataset.create.usage,dataset.create.description,dataset.create.flags,dataset.create.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] [--json]";
+export const AGENT_CONTRACT_USAGE = "dss agent contract [--fields PATHS]";
 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 --json",
-    "dss agent contract --fields commands.actions --json",
+    "dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility",
+    "dss agent contract --fields commands.actions",
 ];
 const VERSION_USAGE = "dss version";
-const VERSION_DESCRIPTION = "Print the CLI version and git revision as JSON.";
+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_DESCRIPTION = "Install the dataiku-dss agent skill for detected coding agents.";
@@ -189,11 +248,11 @@ const CLEANUP_EXAMPLES = [
     "dss cleanup --file cleanup.jsonl",
     "dss cleanup --file cleanup.jsonl --apply",
 ];
-const FIXTURES_USAGE = "dss fixtures [--json] [--project-key KEY] [--allow-types CSV]";
+const FIXTURES_USAGE = "dss fixtures [--project-key KEY] [--allow-types CSV]";
 const FIXTURES_DESCRIPTION = "Discover safe live-test fixtures for agent workflows.";
 const FIXTURES_EXAMPLES = [
-    "dss fixtures --json",
-    "dss fixtures --json --allow-types Filesystem,Inline",
+    "dss fixtures",
+    "dss fixtures --allow-types Filesystem,Inline",
 ];
 const ALLOWED_CLEANUP_ACTIONS = new Set([
     // Must mirror every cleanup.argv shape emitted by cleanupLedgerEntry().
@@ -211,6 +270,7 @@ const ALLOWED_CLEANUP_ACTIONS = new Set([
     "code-env delete",
     "folder delete",
     "folder delete-file",
+    "project delete",
     "app delete-instance",
 ]);
 export function isAllowedCleanupAction(resource, action) {
@@ -395,7 +455,7 @@ function shortFlagPattern(flags) {
  * between `dss` and the first positional. Synthetic single-action commands
  * whose usage omits their action token (e.g. `dss batch ...`, `dss version`)
  * use an actionless prefix, while real command paths that spell `run` in their
- * usage (e.g. `dss commands run [--json]`) keep the action token.
+ * 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);
@@ -481,18 +541,8 @@ function argvJsonSchema(resource, action, flags, usage, requiredFlags, requiredO
         },
     };
 }
-function unsafeOutputs(resource, action, flags, producesLocalFile) {
+function unsafeOutputs(resource, action, producesLocalFile) {
     const outputs = [];
-    if (flags.some((flag) => flag.name === "raw")) {
-        outputs.push({
-            condition: "--raw without --output",
-            kind: "raw-stdout",
-            detail: `${resource} ${action} can intentionally write raw payload bytes/text instead of JSON.`,
-            safeAlternative: flags.some((flag) => flag.name === "output")
-                ? "Pass --output PATH so stdout remains a JSON string containing the path."
-                : "Omit --raw when a JSON stdout value is required.",
-        });
-    }
     if (producesLocalFile) {
         const sensitivePermissions = resource === "app" && action === "permissions-snapshot";
         outputs.push({
@@ -589,6 +639,13 @@ function inferSideEffect(resource, action) {
         return "read";
     if (resource === "data-quality" && action === "compute")
         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.
+    if (resource === "project-git") {
+        return PROJECT_GIT_READ_ACTIONS[action] === true ? "read" : "write";
+    }
     if (READ_ACTIONS.has(action))
         return "read";
     if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout|add|remove|publish|activate|deploy|import|export|preload|upgrade|start|stop|restart|duplicate|put|rename|reply|compute|organize)/
@@ -606,18 +663,21 @@ function inferRequiresAuth(resource) {
         && resource !== "install-skill"
         && resource !== "version";
 }
-export function inferRequiresProject(resource, _action, usage) {
+export function inferRequiresProject(resource, action, usage) {
     if (resource === "agent" || resource === "auth" || resource === "doctor" || resource === "commands"
         || resource === "install-skill" || resource === "version") {
         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",
+    "files",
     "infer",
     "last-results",
     "list",
@@ -639,6 +699,13 @@ const STRING_OUTPUT_ACTIONS = new Set([
     "log-url",
 ]);
 function inferOutputShape(resource, action) {
+    if (resource === "project-git") {
+        if (action === "branches" || action === "tags" || action === "list-libraries")
+            return "array";
+        if (action === "set-library")
+            return "string";
+        return "object";
+    }
     if (resource === "agent" || resource === "auth" || resource === "commands"
         || resource === "install-skill"
         || resource === "version") {
@@ -796,6 +863,9 @@ function inferPayloadSchema(inputContract) {
 function inferExitCodes(resource, action, asyncKind) {
     const longRunning = asyncKind !== "none" || `${resource}.${action}` === "batch.run";
     const assertion = `${resource}.${action}` === "recipe.assert-unchanged"
+        || `${resource}.${action}` === "dataset.assert-count"
+        || `${resource}.${action}` === "dataset.assert-schema"
+        || `${resource}.${action}` === "data-quality.assert-results"
         || `${resource}.${action}` === "batch.run";
     return {
         ok: 0,
@@ -807,6 +877,9 @@ function inferExitCodes(resource, action, asyncKind) {
     };
 }
 function cleanupCommandFromDeleteUsage(resource, action) {
+    if (`${resource}.${action}` === "project.import") {
+        return "dss project delete <used-project-key> --if-exists --expect-project-incarnation <hash>";
+    }
     if (resource === "project" && (action === "create" || action === "duplicate")) {
         return undefined;
     }
@@ -830,9 +903,23 @@ export function supportsCleanupLedger(resource, action) {
     return cleanupCommandFromDeleteUsage(resource, action) !== undefined
         || `${resource}.${action}` === "folder.upload";
 }
-function inferDestructiveLevel(sideEffect, action) {
+/**
+ * Write actions that no public DSS route can undo. `dataset upload-file` adds a
+ * file to the dataset's uploaded-files set, and DSS exposes no endpoint to
+ * replace or delete an individual uploaded file, so the write is permanent and
+ * no cleanup-ledger entry can recover the previous file set.
+ */
+const EXPLICIT_DESTRUCTIVE_KEYS = {
+    "dataset.upload-file": true,
+};
+function inferDestructiveLevel(resource, sideEffect, action) {
     if (sideEffect !== "write")
         return "none";
+    if (EXPLICIT_DESTRUCTIVE_KEYS[`${resource}.${action}`] === true)
+        return "destructive";
+    if (resource === "project-git") {
+        return PROJECT_GIT_DESTRUCTIVE_ACTIONS[action] === true ? "destructive" : "reversible";
+    }
     if (/^(delete|abort|clear|unload|logout)/.test(action))
         return "destructive";
     return "reversible";
@@ -850,6 +937,10 @@ function inferAsyncKind(resource, action) {
     }
     if (resource === "data-quality" && action === "compute")
         return "future";
+    // Project Git mutation results carry a future job id only for the library
+    // calls and the future lifecycle itself; plain Git actions settle inline.
+    if (resource === "project-git" && PROJECT_GIT_FUTURE_ACTIONS[action] === true)
+        return "future";
     if (resource === "code" && action === "run")
         return "future";
     if (resource === "app"
@@ -872,6 +963,11 @@ function inferIdempotency(resource, sideEffect, action, usage) {
     // error, so replaying the delete cannot fail on absence alone.
     if (`${resource}.${action}` === "app.delete-instance")
         return "convergent";
+    // Git fetch and the repository resets converge: replaying them lands on the
+    // same repository state instead of failing on an already-applied change.
+    if (resource === "project-git" && PROJECT_GIT_CONVERGENT_ACTIONS[action] === true) {
+        return "convergent";
+    }
     if (/^(clear|refresh|set|save)/.test(action))
         return "convergent";
     return "none";
@@ -890,6 +986,10 @@ const LEDGER_ONLY_CLEANUP_KEYS = {
 };
 const LEDGER_ONLY_CLEANUP_HINT = "Pass `--record-cleanup PATH` when creating, then recover with `dss cleanup --file PATH --apply`. Do not issue direct instance deletion as cleanup: it bypasses the creation-future gate and can delete the project while DSS is still creating it.";
 export function inferCleanupHint(resource, action) {
+    // Git mutations are not cleanup-ledger operations: no project-git branch or
+    // tag create has a generic `delete` command to close it out.
+    if (resource === "project-git")
+        return undefined;
     if (!(action.startsWith("create") || action === "clone"))
         return undefined;
     if (LEDGER_ONLY_CLEANUP_KEYS[`${resource}.${action}`] === true) {
@@ -911,10 +1011,10 @@ export function inferCleanupHint(resource, action) {
     return `Delete with \`dss ${resource} delete <id>${ifExists}\` when the created object is disposable.`;
 }
 function buildRegistryEntry(resource, action, meta) {
-    const requiresAuth = inferRequiresAuth(resource);
+    const requiresAuth = meta.localHandler === undefined && inferRequiresAuth(resource);
     const requiresProject = inferRequiresProject(resource, action, meta.usage);
     const sideEffect = inferSideEffect(resource, action);
-    const destructive = inferDestructiveLevel(sideEffect, 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";
@@ -980,7 +1080,7 @@ function buildRegistryEntry(resource, action, meta) {
         || meta.usage.includes("--output-file PATH");
     const uniqueRequiredFlags = uniqueStrings(requiredFlags);
     const uniqueOptionalFlags = uniqueStrings(optionalFlags);
-    const unsafe = unsafeOutputs(resource, action, flagMetadata, producesLocalFile);
+    const unsafe = unsafeOutputs(resource, action, producesLocalFile);
     return {
         resource,
         action,
@@ -1229,7 +1329,7 @@ export function agentContractJsonSchema() {
         },
     };
 }
-function commandActionSummary(registry) {
+export function commandActionSummary(registry) {
     const summary = {};
     for (const [resource, actions,] of Object.entries(registry)) {
         summary[resource] = Object.keys(actions).sort();
@@ -1244,15 +1344,14 @@ export function buildAgentContract() {
         cli: cliVersionResult(),
         commands: {
             discoveryCommand: "dss commands run",
-            scopedDiscoveryCommand: "dss commands run --fields RESOURCE[.ACTION[.FIELD...]] --json",
-            actionIndexCommand: "dss agent contract --fields commands.actions --json",
-            compactOutputFlag: "--json",
-            compactOutputHint: "Pass --json to emit compact single-line JSON and reduce agent context usage.",
+            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 --json",
-                "dss commands run --fields dataset.create --json",
+                "dss commands run --fields dataset",
+                "dss commands run --fields dataset.create",
             ],
-            scopedDiscoveryHint: "--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.",
+            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),
         },
         schemas: {
@@ -1265,28 +1364,22 @@ export function buildAgentContract() {
         },
         stdio: {
             stdout: {
+                format: "compact-json",
                 success: "single-json-value",
-                rawEscapeHatches: [
-                    "recipe get-payload --raw without --output",
-                    "recipe cat --raw without --output",
-                ],
+                failure: "structured-error-object",
+                richFailureResults: "doctor/batch/cleanup nonzero outcomes are their own compact result on stdout ({ok:false,...}) with the command's exit code; not re-wrapped.",
             },
             stderr: {
                 format: "jsonl",
-                events: ["warning", "trace", "error",],
-                error: "single-final-error-event-on-nonzero-exit",
-                failureRouting: {
-                    commandFailure: "doctor/batch/cleanup failures: single JSON stdout; empty stderr",
-                    dispatchFailure: "usage/unknown/transport/internal failures: empty stdout; single JSON error stderr",
-                },
+                events: ["warning", "trace",],
             },
         },
         planning: {
             discoveryCommand: "dss commands run",
             contractCommand: AGENT_CONTRACT_COMMAND,
-            bootstrapCommand: "dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility --json",
-            preferredDiscoveryCommand: "dss commands run --fields RESOURCE.ACTION --json",
-            actionIndexCommand: "dss agent contract --fields commands.actions --json",
+            bootstrapCommand: "dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility",
+            preferredDiscoveryCommand: "dss commands run --fields RESOURCE.ACTION",
+            actionIndexCommand: "dss agent contract --fields commands.actions",
             mutatingCommandsAdvertisePlan: true,
         },
         compatibility: {
@@ -1375,6 +1468,67 @@ function querySuffix(params) {
     const raw = search.toString();
     return raw ? `?${raw}` : "";
 }
+/**
+ * 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
+ * normalize them to the repo-wide `/public/api`.
+ */
+const PROJECT_GIT_API_ROOT = "/dip/publicapi";
+function projectGitEndpoint(projectKey, suffix) {
+    if (!projectKey)
+        throw new UsageError("--project-key is required for project-git mutations.");
+    return `${PROJECT_GIT_API_ROOT}/projects/${encodeURIComponent(projectKey)}/git${suffix}`;
+}
+function projectGitFutureEndpoint(jobId) {
+    return `${PROJECT_GIT_API_ROOT}/futures/${encodeURIComponent(jobId)}`;
+}
+/** Encode a library reference path per segment, mirroring the resource helper. */
+function encodeGitReferencePath(pathValue) {
+    const normalized = pathValue.replace(/^\/+/, "").replace(/\/+$/, "");
+    return normalized.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+}
+/**
+ * `--plan` bypasses the SDK boundary guard, so HTTP(S) URLs with embedded
+ * userinfo are rejected here before any plan is printed. SSH/scp-style URLs
+ * (`git@host:org/repo.git`, `ssh://...`) remain valid.
+ */
+function validatedPlanRepositoryUrl(url, flag, usage) {
+    const candidate = url.trim();
+    if (/[\u0000-\u001f\u007f]/u.test(candidate)) {
+        throw new UsageError(`--${flag} must not contain control characters. Usage: ${usage}`);
+    }
+    if (/^https?:/i.test(candidate)) {
+        if (candidate.includes("\\")) {
+            throw new UsageError(`--${flag} must be a valid HTTP(S) URL. Usage: ${usage}`);
+        }
+        if (!/^https?:\/\//i.test(candidate)) {
+            throw new UsageError(`--${flag} must be a valid HTTP(S) URL. Usage: ${usage}`);
+        }
+        let parsed;
+        try {
+            parsed = new URL(candidate);
+        }
+        catch {
+            throw new UsageError(`--${flag} must be a valid HTTP(S) URL. Usage: ${usage}`);
+        }
+        if (parsed.username !== "" || parsed.password !== "") {
+            throw new UsageError(`--${flag} must not contain embedded credentials (userinfo). Usage: ${usage}`);
+        }
+    }
+    return candidate;
+}
+function requiredPlanRepositoryUrl(flags, flag, usage) {
+    const url = requiredPlanFlag(flags, flag, usage);
+    return validatedPlanRepositoryUrl(url, flag, usage);
+}
+/** Wait procedure advertised for the library calls that return a job id. */
+function projectGitFutureWait() {
+    return {
+        when: "after-dispatch",
+        endpoint: `${PROJECT_GIT_API_ROOT}/futures/{jobId}?peek=false`,
+        description: "Poll the returned job id until the future reports a result; never abort it.",
+    };
+}
 function jobBuildPayload(target, projectKey, flags) {
     const targetType = jobBuildTargetTypeFromFlags(flags);
     const partition = flags["partition"];
@@ -1609,8 +1763,11 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         case "dataset.create": {
             const name = requiredPlanFlag(flags, "name", entry.usage);
-            const connection = requiredPlanFlag(flags, "connection", entry.usage);
+            const connection = flags["connection"];
             const dsType = requiredPlanFlag(flags, "type", entry.usage);
+            if (!connection && dsType.toLowerCase() !== "uploadedfiles") {
+                throw new UsageError("--connection is required unless --type is UploadedFiles.");
+            }
             return {
                 method: "POST",
                 endpoint: projectEndpoint("/datasets/"),
@@ -1643,6 +1800,38 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: { oldName: args[0], newName: args[1], },
                 payload: { oldName: args[0], newName: args[1], },
             };
+        case "dataset.upload-file": {
+            const fileName = requiredPlanFlag(flags, "file-name", entry.usage);
+            const datasetEndpoint = projectEndpoint(`/datasets/${encodeURIComponent(args[0])}`);
+            const filesEndpoint = `${datasetEndpoint}/uploaded/files`;
+            const upload = {
+                method: "POST",
+                endpoint: filesEndpoint,
+                payload: { ...uploadPayload(args[1]), fileName, },
+            };
+            return {
+                ...upload,
+                identifiers: {
+                    datasetName: args[0],
+                    localPath: args[1],
+                    fileName,
+                },
+                requests: [
+                    { sequence: 1, method: "GET", endpoint: datasetEndpoint, },
+                    { sequence: 2, method: "GET", endpoint: filesEndpoint, },
+                    { sequence: 3, ...upload, },
+                    {
+                        sequence: 4,
+                        method: "GET",
+                        endpoint: filesEndpoint,
+                        assert: {
+                            filename: fileName,
+                            length: "local file byte length",
+                        },
+                    },
+                ],
+            };
+        }
         case "dataset.delete":
             return {
                 method: "DELETE",
@@ -1740,7 +1929,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 payload: {
                     type,
                     name: flags["name"],
-                    inputDatasets: flags["input"] ? [flags["input"],] : undefined,
+                    inputDatasets: recipeInputDatasetsFromFlags(flags),
                     outputDataset,
                     outputFolder,
                     outputConnection: flags["output-connection"],
@@ -1840,8 +2029,8 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         case "folder.create": {
             const name = requiredPlanFlag(flags, "name", entry.usage);
-            const type = requiredPlanFlag(flags, "type", entry.usage);
-            const connection = requiredPlanFlag(flags, "connection", entry.usage);
+            const type = flags["type"];
+            const connection = flags["connection"];
             return {
                 method: "POST",
                 endpoint: projectEndpoint("/managedfolders/"),
@@ -2655,7 +2844,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 method: "PUT",
                 endpoint: projectEndpoint(`/sql-notebooks/${encodeURIComponent(id)}/history`),
                 identifiers: { id, cellId: flags["cell-id"], },
-                payload: { retain: num(flags["retain"]), },
+                payload: { retain: num(flags["retain"], "--retain"), },
             };
         case "project.create": {
             const settings = jsonInput(flags) ?? null;
@@ -2674,17 +2863,74 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 },
             };
         }
-        case "project.delete":
+        case "project.delete": {
+            const expectedProjectIncarnation = flags["expect-project-incarnation"] === undefined
+                ? undefined
+                : requiredPlanFlag(flags, "expect-project-incarnation", entry.usage);
+            if (expectedProjectIncarnation !== undefined
+                && !/^[0-9a-f]{64}$/.test(expectedProjectIncarnation)) {
+                throw new UsageError("--expect-project-incarnation must be a 64-character lowercase SHA-256 hash.", "validation_failed");
+            }
+            const endpoint = `/public/api/projects/${encodeURIComponent(id)}${querySuffix({
+                clearManagedDatasets: flags["drop-data"] === true,
+                clearOutputManagedFolders: false,
+                clearJobAndScenarioLogs: true,
+                wait: true,
+            })}`;
+            const guarded = flags["if-exists"] === true
+                || flags["dry-run"] === true
+                || expectedProjectIncarnation !== undefined;
+            if (!guarded) {
+                return {
+                    method: "DELETE",
+                    endpoint,
+                    identifiers: { projectKey: id, },
+                };
+            }
+            const projectProbe = `/public/api/projects/${encodeURIComponent(id)}/`;
+            const incarnationGate = expectedProjectIncarnation === undefined
+                ? { required: false, provided: false, }
+                : {
+                    required: true,
+                    provided: true,
+                    expectedHash: expectedProjectIncarnation,
+                };
+            if (flags["dry-run"] === true) {
+                return {
+                    method: "GET",
+                    endpoint: projectProbe,
+                    identifiers: {
+                        projectKey: id,
+                        dryRun: true,
+                        ifExists: flags["if-exists"] === true,
+                        projectIncarnationGate: incarnationGate,
+                        note: "Read-only guarded-delete preflight. No DELETE is issued; a supplied creationTag hash must match.",
+                    },
+                };
+            }
             return {
                 method: "DELETE",
-                endpoint: `/public/api/projects/${encodeURIComponent(id)}${querySuffix({
-                    clearManagedDatasets: flags["drop-data"] === true,
-                    clearOutputManagedFolders: false,
-                    clearJobAndScenarioLogs: true,
-                    wait: true,
-                })}`,
-                identifiers: { projectKey: id, },
+                endpoint,
+                identifiers: {
+                    projectKey: id,
+                    ifExists: flags["if-exists"] === true,
+                    projectIncarnationGate: incarnationGate,
+                    incarnationControl: expectedProjectIncarnation === undefined
+                        ? "none"
+                        : "client-side-non-atomic-stale-identity-check",
+                    preflightRequests: [{
+                            method: "GET",
+                            endpoint: projectProbe,
+                            intent: expectedProjectIncarnation === undefined
+                                ? "Confirm existence before a convergent delete."
+                                : "Recompute the current project-incarnation hash from creationTag before DELETE.",
+                        },],
+                    note: expectedProjectIncarnation === undefined
+                        ? "Convergent delete: a 404 preflight is an already-absent success only with --if-exists."
+                        : "Incarnation-bound delete: the GET must match the expected creationTag hash before an unconditional DELETE. DSS exposes no conditional project DELETE, so the client-side gate cannot serialize against key reuse after the GET.",
+                },
             };
+        }
         case "project.duplicate": {
             const options = jsonInput(flags);
             return {
@@ -2706,11 +2952,32 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 },
             };
         }
-        case "project.import":
-            return {
+        case "project.import": {
+            const settings = jsonInput(flags) ?? {};
+            const rawTarget = flags["target-project-key"];
+            const targetProjectKey = rawTarget?.trim();
+            if (rawTarget !== undefined && targetProjectKey === "") {
+                throw new UsageError(`--target-project-key must not be empty. Usage: ${entry.usage}`);
+            }
+            const settingsTarget = settings.targetProjectKey;
+            if (settingsTarget !== undefined
+                && (typeof settingsTarget !== "string" || settingsTarget.trim() === "")) {
+                throw new UsageError(`targetProjectKey in import settings must be a non-empty string. Usage: ${entry.usage}`);
+            }
+            if (targetProjectKey !== undefined
+                && settingsTarget !== undefined
+                && targetProjectKey !== settingsTarget.trim()) {
+                throw new UsageError(`--target-project-key conflicts with targetProjectKey in import settings. Usage: ${entry.usage}`);
+            }
+            const processPayload = targetProjectKey === undefined
+                ? settings
+                : { ...settings, targetProjectKey, };
+            const finalizedPayload = Object.keys(processPayload).length === 0
+                ? { _: "_", }
+                : processPayload;
+            const upload = {
                 method: "POST",
                 endpoint: "/public/api/projects/import/upload",
-                identifiers: { filePath: id, },
                 payload: {
                     contentType: "multipart/form-data",
                     fileField: "file",
@@ -2718,6 +2985,46 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                     fileName: "tmp-import.zip",
                 },
             };
+            return {
+                ...upload,
+                identifiers: {
+                    filePath: id,
+                    ...(targetProjectKey ? { targetProjectKey, } : {}),
+                    archivePreflight: {
+                        local: true,
+                        required: true,
+                        checks: [
+                            "zip-integrity",
+                            "safe-unique-members",
+                            "manifest",
+                            "flow-references",
+                            "orphan-members",
+                        ],
+                    },
+                    successVerification: {
+                        usedProjectKeyRequired: true,
+                        projectReadRequired: true,
+                        projectIncarnationRequired: true,
+                        remappingReported: true,
+                    },
+                    ...(flags["record-cleanup"] === undefined
+                        ? {}
+                        : {
+                            cleanupBinding: "actual used project key plus verified creationTag incarnation hash",
+                        }),
+                },
+                requests: [
+                    { sequence: 1, ...upload, },
+                    {
+                        sequence: 2,
+                        method: "POST",
+                        endpoint: "/public/api/projects/import/{importId}/process",
+                        pathBindings: { importId: "requests[0].response.id", },
+                        payload: finalizedPayload,
+                    },
+                ],
+            };
+        }
         case "project.settings-set":
             return {
                 method: "PUT",
@@ -2755,6 +3062,226 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 endpoint: projectEndpoint("/flow/zones"),
                 payload: jsonInput(flags),
             };
+        /* ---- project-git: mutations only; reads are never planned ---- */
+        case "project-git.set-remote": {
+            const remote = flags["name"] ?? "origin";
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, `/remotes/${encodeURIComponent(remote)}`),
+                identifiers: { remote, },
+                payload: { url: requiredPlanRepositoryUrl(flags, "repository", entry.usage), },
+            };
+        }
+        case "project-git.remove-remote": {
+            const remote = flags["name"] ?? "origin";
+            return {
+                method: "DELETE",
+                endpoint: projectGitEndpoint(projectKey, `/remotes/${encodeURIComponent(remote)}`),
+                identifiers: { remote, },
+            };
+        }
+        case "project-git.create-branch":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/branches/"),
+                identifiers: { name: id, },
+                payload: {
+                    name: id,
+                    commit: flags["commit"] ?? null,
+                    duplicateProject: parseBooleanOption(flags["duplicate-project"], "--duplicate-project") ?? false,
+                    targetProjectKey: flags["target-project-key"] ?? null,
+                    targetProjectFolderId: flags["target-project-folder-id"] ?? null,
+                },
+            };
+        case "project-git.delete-branch": {
+            const remote = parseBooleanOption(flags["remote"], "--remote") ?? false;
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/actions/deleteBranch"),
+                identifiers: { name: id, remote, },
+                payload: {
+                    name: id,
+                    remote,
+                    deleteRemotely: parseBooleanOption(flags["delete-remotely"], "--delete-remotely") ?? false,
+                    forceDelete: parseBooleanOption(flags["force-delete"], "--force-delete") ?? false,
+                },
+            };
+        }
+        case "project-git.switch":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, `/actions/switchBranch${querySuffix({ branchName: id, })}`),
+                identifiers: { branch: id, },
+            };
+        case "project-git.create-tag":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/tags/"),
+                identifiers: { name: id, },
+                payload: {
+                    name: id,
+                    reference: flags["reference"] ?? "HEAD",
+                    message: flags["message"] ?? "",
+                },
+            };
+        case "project-git.delete-tag":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/actions/deleteTag"),
+                identifiers: { name: id, },
+                payload: { name: id, },
+            };
+        case "project-git.fetch":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/actions/fetch"),
+            };
+        case "project-git.pull":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, `/actions/pullRebase${querySuffix({
+                    branchName: flags["branch"],
+                })}`),
+                ...(flags["branch"] !== undefined
+                    ? { identifiers: { branch: flags["branch"], }, }
+                    : {}),
+            };
+        case "project-git.push":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, `/actions/push${querySuffix({
+                    branchName: flags["branch"],
+                })}`),
+                ...(flags["branch"] !== undefined
+                    ? { identifiers: { branch: flags["branch"], }, }
+                    : {}),
+            };
+        case "project-git.commit": {
+            const message = requiredPlanFlag(flags, "message", entry.usage);
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/actions/commit"),
+                identifiers: { message, },
+                payload: { message, },
+            };
+        }
+        case "project-git.revert-to-revision":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, `/actions/revertToRevision${querySuffix({ commit: id, })}`),
+                identifiers: { commit: id, },
+            };
+        case "project-git.revert-commit":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, `/actions/revertCommit${querySuffix({ commit: id, })}`),
+                identifiers: { commit: id, },
+            };
+        case "project-git.reset-to-head":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/actions/resetToLocalHeadState"),
+            };
+        case "project-git.reset-to-upstream":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/actions/resetToRemoteHeadState"),
+            };
+        case "project-git.drop-and-rebuild": {
+            if (parseBooleanOption(flags["i-know-what-i-am-doing"], "--i-know-what-i-am-doing") !== true) {
+                throw new UsageError(`--i-know-what-i-am-doing is required to acknowledge the irreversible Git history loss. Usage: ${entry.usage}`);
+            }
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, `/actions/dropAndRebuild${querySuffix({ iKnowWhatIAmDoing: true, })}`),
+            };
+        }
+        case "project-git.add-library": {
+            const targetPath = id;
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/lib-git-refs/"),
+                identifiers: { localTargetPath: targetPath, },
+                payload: {
+                    repository: requiredPlanRepositoryUrl(flags, "repository", entry.usage),
+                    login: flags["login"] ?? null,
+                    password: flags["password-env"] !== undefined ? "***" : null,
+                    pathInGitRepository: flags["path-in-repository"] ?? "",
+                    localTargetPath: targetPath,
+                    checkout: requiredPlanFlag(flags, "checkout", entry.usage),
+                    addToPythonPath: parseBooleanOption(flags["no-add-to-python-path"], "--no-add-to-python-path") !== true,
+                },
+                wait: projectGitFutureWait(),
+            };
+        }
+        case "project-git.set-library": {
+            const targetPath = id;
+            return {
+                method: "PUT",
+                endpoint: projectGitEndpoint(projectKey, `/lib-git-refs/${encodeGitReferencePath(targetPath)}`),
+                identifiers: { library: targetPath, },
+                payload: {
+                    repository: requiredPlanRepositoryUrl(flags, "repository", entry.usage),
+                    login: flags["login"] ?? null,
+                    password: flags["password-env"] !== undefined ? "***" : null,
+                    pathInGitRepository: flags["path-in-repository"] ?? "",
+                    checkout: requiredPlanFlag(flags, "checkout", entry.usage),
+                },
+            };
+        }
+        case "project-git.remove-library": {
+            const targetPath = id;
+            return {
+                method: "DELETE",
+                endpoint: projectGitEndpoint(projectKey, `/lib-git-refs/${encodeGitReferencePath(targetPath)}${querySuffix({
+                    deleteDirectory: parseBooleanOption(flags["delete-directory"], "--delete-directory") ?? false,
+                })}`),
+                identifiers: { library: targetPath, },
+            };
+        }
+        case "project-git.reset-library": {
+            const targetPath = id;
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/lib-git-refs/action/reset"),
+                identifiers: { library: targetPath, },
+                payload: { gitRef: targetPath, },
+                wait: projectGitFutureWait(),
+            };
+        }
+        case "project-git.push-library": {
+            const targetPath = id;
+            const message = requiredPlanFlag(flags, "message", entry.usage);
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/lib-git-refs/action/push"),
+                identifiers: { library: targetPath, message, },
+                payload: { gitRef: targetPath, commitMessage: message, },
+                wait: projectGitFutureWait(),
+            };
+        }
+        case "project-git.push-all-libraries": {
+            const message = requiredPlanFlag(flags, "message", entry.usage);
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/actions/git-refs/push-all"),
+                identifiers: { message, },
+                payload: { commitMessage: message, },
+                wait: projectGitFutureWait(),
+            };
+        }
+        case "project-git.reset-all-libraries":
+            return {
+                method: "POST",
+                endpoint: projectGitEndpoint(projectKey, "/actions/git-refs/reset-all"),
+                wait: projectGitFutureWait(),
+            };
+        case "project-git.future-abort":
+            return {
+                method: "DELETE",
+                endpoint: projectGitFutureEndpoint(id),
+                identifiers: { jobId: id, },
+            };
         default:
             return {
                 method: action.startsWith("delete") || action === "abort" ? "DELETE" : "POST",