dataiku-sdk 0.12.6 → 1.0.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,19 +217,21 @@ 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.";
@@ -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().
@@ -395,7 +454,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 +540,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({
@@ -519,7 +568,7 @@ export function buildCommandSchemas(resource, action, flags, requiredFlags, requ
 }
 const EXPLICIT_REGISTRY_OVERRIDES = {
     "dashboard.create": {
-        examplePayload: { pages: [], },
+        examplePayload: { name: "Agent dashboard", pages: [], },
     },
     "dashboard.update": {
         examplePayload: { name: "Updated dashboard", },
@@ -583,13 +632,19 @@ function inferSideEffect(resource, action) {
     }
     if (resource === "install-skill")
         return "write";
-    // `project export` streams an archive over the API and writes it to a local
-    // path; the DSS-side project is untouched, so it reads remotely and only
-    // mutates the local filesystem.
-    if (resource === "project" && action === "export")
+    // Project and dashboard exports stream a rendered/archive artifact and write it
+    // locally; the DSS-side resource is untouched.
+    if ((resource === "project" || resource === "dashboard") && action === "export")
         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)/
@@ -607,13 +662,15 @@ 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([
@@ -640,6 +697,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") {
@@ -831,9 +895,12 @@ export function supportsCleanupLedger(resource, action) {
     return cleanupCommandFromDeleteUsage(resource, action) !== undefined
         || `${resource}.${action}` === "folder.upload";
 }
-function inferDestructiveLevel(sideEffect, action) {
+function inferDestructiveLevel(resource, sideEffect, action) {
     if (sideEffect !== "write")
         return "none";
+    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";
@@ -851,6 +918,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"
@@ -873,6 +944,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";
@@ -891,6 +967,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) {
@@ -915,7 +995,7 @@ function buildRegistryEntry(resource, action, meta) {
     const requiresAuth = 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";
@@ -981,7 +1061,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,
@@ -1230,7 +1310,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();
@@ -1245,15 +1325,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: {
@@ -1266,28 +1345,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: {
@@ -1376,6 +1449,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"];
@@ -1449,18 +1583,31 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: { article: id, },
             };
         case "dashboard.create": {
-            const name = requiredPlanFlag(flags, "name", entry.usage);
+            const data = jsonInput(flags);
+            const flagName = flags["name"];
+            const dataName = data?.["name"];
+            const name = flagName ?? (typeof dataName === "string" ? dataName : undefined);
+            if (!name) {
+                throw new UsageError("--name or dashboard settings containing a string name are required. Usage: dss dashboard create --name NAME");
+            }
+            const listed = parseBooleanOption(flags["listed"], "--listed");
+            const payload = { ...(data ?? { pages: [], }), name, };
+            if (listed !== undefined)
+                payload.listed = listed;
             return {
                 method: "POST",
                 endpoint: projectEndpoint("/dashboards/"),
                 identifiers: { name, },
-                payload: { ...(jsonInput(flags) ?? { pages: [], }), name, },
+                payload,
             };
         }
         case "dashboard.update": {
             const payload = { ...jsonInput(flags), };
             if (typeof flags["name"] === "string")
                 payload.name = flags["name"];
+            const listed = parseBooleanOption(flags["listed"], "--listed");
+            if (listed !== undefined)
+                payload.listed = listed;
             return {
                 method: "PUT",
                 endpoint: projectEndpoint(`/dashboards/${encodeURIComponent(id)}/`),
@@ -1597,8 +1744,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/"),
@@ -1728,7 +1878,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"],
@@ -1828,8 +1978,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/"),
@@ -2643,7 +2793,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;
@@ -2743,6 +2893,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",