dataiku-sdk 0.12.6 → 1.0.0

package/README.md

@@ -23,29 +23,31 @@ Bun is the primary development runtime and package manager. Examples below assum
 
 ## CLI contract
 
-- Command results write exactly one JSON value to stdout, including `doctor`, `batch`, and `cleanup` failure reports; use the exit code and result fields.
-- Dispatch/runtime failures write one JSONL error event to stderr with `type:"error"`, `ok:false`, `error`, `code`, and `exitCode`, while stdout stays empty.
-- Non-fatal diagnostics and `--verbose` traces are JSONL stderr events (`type:"warning"` / `type:"trace"`); no prose trace lines are part of the contract.
+- Command results write exactly one compact JSON value to stdout; void success is `{ok:true}`. `doctor`, `batch`, and `cleanup` failure reports are their direct result objects on stdout with a nonzero exit code — use the exit code and result fields.
+- Dispatch/runtime failures write one compact structured error object on stdout (`type:"error"`, `ok:false`, `error`, `code`, `category`, `exitCode`) with a nonzero exit code; stderr carries JSONL diagnostics only.
+- Non-fatal diagnostics and `--verbose` traces are JSONL stderr events (`type:"warning"` / `type:"trace"`), flushed before both success and failure output; no prose trace lines are part of the contract.
 - `--fields a,b,c` projects those fields from an object or array-of-objects result; dotted paths (`a.b.c`) drill into nested objects, and missing fields become `null`; string and scalar results pass through unchanged.
 - No prompts, help screens, tables, banners, or prose output are part of the contract.
 - Exit codes: `0` success, `1` usage/configuration error, `2` DSS/internal error, `3` transient DSS error, `4` a failed long-running result or synchronous assertion.
 - `--retries N` controls idempotent GET retries only. `dss sql query --start-retries N` explicitly retries transient failures while starting a query; use it only when executing the SQL more than once is safe.
 - The exit code is the success signal. For portable multi-step mutations, prefer `dss batch`; shell chaining and pipeline exit semantics differ across POSIX shells, Windows PowerShell, PowerShell 7, and Command Prompt.
-- `--raw` is only for recipe payload commands. Without `--output`, stdout is raw bytes; with `--output PATH`, stdout is the JSON string equal to `PATH` and the file contains the exact raw bytes.
+- Recipe payload commands write the payload as a JSON string on stdout; use `--output PATH` to write the exact bytes to a file instead, with stdout carrying the JSON string equal to `PATH`.
 
-Discover the agent contract and command surface with compact, scoped, `--json` calls:
+Discover the agent contract and command surface with scoped calls:
 
 ```text
-dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility --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 --fields dataset --json
-dss agent contract --fields commands.actions --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
+dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility
+dss agent contract --fields commands.actions
 ```
 
-For JSON outputs, prefer `--json`: compact single-line JSON cuts the full registry's context usage by about 40% (~220k tokens versus ~358k pretty-printed). Bootstrap by scoping `agent contract` to `protocol,agentContractVersion,cli,stdio,planning,compatibility` (~250 tokens); request `schemas` or `commands` only when you actually need them. Before choosing syntax, scope `commands run` with `--fields`: `--fields RESOURCE.ACTION` returns one complete registry entry, and appending `.FIELD` paths projects the metadata you need — the four-field per-action projection `usage,description,flags,examples` is the smallest self-sufficient starting point for constructing an invocation. Inspect `flags`, `structuredExamples`, `schemas`, `requiresAuth`, `requiresProject`, `sideEffect`, `async`, `idempotency`, `dryRun`, `cleanupCommand`, `unsafeOutputs`, `outputShape`, `inputContract`, and `exitCodes` instead of guessing.
+`dss commands run` prints the compact resource/action summary — every resource keyed to its action names, about 1k tokens — and never dumps registry entries to stdout. Bootstrap contract discovery with the scoped `agent contract` call above: `protocol,agentContractVersion,cli,stdio,planning,compatibility` cover protocol/schema compatibility, stdout/stderr stream semantics, preferred discovery commands, planning rules, and compatibility guarantees in ~250 tokens; request `schemas` or `commands` only when you actually need them. Before choosing syntax, scope `commands run` with `--fields`: `--fields RESOURCE.ACTION` returns one complete registry entry, `--fields RESOURCE` returns every action of one resource, and appending `.FIELD` paths projects the metadata you need — the four-field per-action projection `usage,description,flags,examples` is the smallest self-sufficient starting point for constructing an invocation. Inspect `flags`, `structuredExamples`, `schemas`, `requiresAuth`, `requiresProject`, `sideEffect`, `async`, `idempotency`, `dryRun`, `cleanupCommand`, `unsafeOutputs`, `outputShape`, `inputContract`, and `exitCodes` instead of guessing.
 
-`--fields` takes a comma-separated list, so request several actions in one call. Each key is echoed exactly as requested (`--fields dataset.create` returns `{"dataset.create": {...}}`). Enumerate every resource and action with `dss agent contract --fields commands.actions --json` (~1k tokens); the ~220k-token unscoped registry remains a compatibility surface, not a discovery workflow. An unknown resource or action exits with code 1 and a JSON error envelope on stderr containing the valid options.
+`--fields` takes a comma-separated list, so request several actions in one call. Each key is echoed exactly as requested (`--fields dataset.create` returns `{"dataset.create": {...}}`); an empty `--fields` is a usage error, never a silent full dump. The full registry (~220k tokens) is exported only via `--output PATH`: the command writes the registry, or the selected `--fields` subset, as compact JSON to `PATH`, and stdout carries the compact `{"path":"PATH"}` result — never the registry itself. An unknown resource or action exits with code 1 and a compact JSON error object on stdout containing the valid options.
 
 ## Agent skill installation
 
@@ -119,8 +121,7 @@ dss doctor --fast
 dss project list
 dss dataset list --project-key MYPROJ
 dss recipe get-payload compute_orders --project-key MYPROJ
-dss recipe get-payload compute_orders --raw --project-key MYPROJ
-dss recipe get-payload compute_orders --raw --output code.py --project-key MYPROJ
+dss recipe get-payload compute_orders --output code.py --project-key MYPROJ
 dss install-skill --dry-run
 dss app validate-manifest --project-key MYAPP_INSTANCE
 dss app compare-manifest my-app --project-key MYAPP_INSTANCE
@@ -230,4 +231,49 @@ never marks that external check complete. The public DSS APIs used by this SDK d
 supported app-template publish/recreate/rename workflow, recipient-level app sharing setter, or
 UI-click smoke test. The CLI does not guess private endpoints for those operations.
 
+## Project Git source-control safety
+
+Project Git commands require DSS 12.4.2 or newer plus read and write access to the project
+content. Inspect state before changing it:
+The DSS project Git API exposes status, remotes, branches, tags, branch switching, fetch,
+rebase-based pull, push, log, diff, commit, revert/reset/rebuild, external-library, and future
+operations. It does not expose a separate checkout operation; use `switch`.
+
+```bash
+dss project-git status --project-key MYPROJ
+dss project-git branches --remote --project-key MYPROJ
+dss project-git log --count 20 --project-key MYPROJ
+```
+
+Creating a branch in a duplicate project is the safe UAT path; creating it in place switches the
+source project to the new branch:
+
+```bash
+dss project-git create-branch feature/orders \
+  --duplicate-project \
+  --target-project-key MYPROJ_ORDERS_UAT \
+  --project-key MYPROJ \
+  --plan
+dss project-git create-branch feature/orders \
+  --duplicate-project \
+  --target-project-key MYPROJ_ORDERS_UAT \
+  --project-key MYPROJ
+```
+
+`pull` rebases rather than merging. `reset-to-head`, `reset-to-upstream`, reverts, forced or
+remote branch deletion, library-directory deletion, and `drop-and-rebuild` are destructive;
+inspect their local `--plan` result first. `drop-and-rebuild` additionally requires
+`--i-know-what-i-am-doing` and destroys all Git history. Repository URLs containing embedded
+HTTP credentials are rejected. External-library credentials must come from
+`--password-env ENV_NAME`; the value is never included in plans or command output. Library
+operations that return a `jobId` can be observed with `project-git future-status` or completed
+with `project-git future-wait`.
+Project Git requests use `/dip/publicapi/projects/{projectKey}/git/*`; they do not configure
+remote authentication. DSS documents administrator Git group rules plus either per-user SSH keys
+under **Profile > Credentials > SSH** or non-interactive system-level credentials for the DSS
+server account. Configure these before private-remote fetch, pull, or push. `--password-env`
+applies only to external project-library operations and does not persist a remote credential.
+The `project-git` resource does not manage these settings, so public/auth-less and
+already-configured remotes are the supported automation paths.
+
 For fake-DSS smoke tests, return project lists as JSON arrays such as `[{ "projectKey": "MYPROJ", "name": "My Project" }]` from `/public/api/projects/`; recipe payload commands read `/public/api/projects/<PROJECT>/recipes/<NAME>?includePayload=true` and expect a JSON object shaped like `{ "recipe": { "name": "<NAME>", "type": "python" }, "payload": "..." }`.

package/bin/dss.js

@@ -77,7 +77,7 @@ if (result.error) {
 			runningOnBun ? "Bun" : "Node"
 		} runtime for packaged dss CLI (${result.error.message}); falling back to the current runtime.`;
 	if (usesSourceCli) {
-		process.stderr.write(`${
+		process.stdout.write(`${
 			JSON.stringify({
 				type: "error",
 				ok: false,

package/dist/packages/types/src/index.d.ts

@@ -66,6 +66,7 @@ export declare const DatasetSummarySchema: import("@sinclair/typebox").TObject<{
     managed: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     params: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         connection: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        uploadConnection: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         catalog: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
@@ -86,6 +87,7 @@ export declare const DatasetDetailsSchema: import("@sinclair/typebox").TObject<{
     managed: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     params: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         connection: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        uploadConnection: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         table: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -111,7 +113,7 @@ export declare const DatasetDetailsSchema: import("@sinclair/typebox").TObject<{
 export type DatasetDetails = Static<typeof DatasetDetailsSchema>;
 export declare const DatasetCreateOptionsSchema: import("@sinclair/typebox").TObject<{
     datasetName: import("@sinclair/typebox").TString;
-    connection: import("@sinclair/typebox").TString;
+    connection: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     dsType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     table: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     dbSchema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -382,8 +384,8 @@ export declare const FlowZoneUpdateOptionsSchema: import("@sinclair/typebox").TO
 export type FlowZoneUpdateOptions = Static<typeof FlowZoneUpdateOptionsSchema>;
 export declare const FolderCreateOptionsSchema: import("@sinclair/typebox").TObject<{
     name: import("@sinclair/typebox").TString;
-    type: import("@sinclair/typebox").TString;
-    connection: import("@sinclair/typebox").TString;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    connection: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     params: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
     projectKey: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -677,6 +679,128 @@ export declare const FlowMapOptionsSchema: import("@sinclair/typebox").TObject<{
     includeRaw: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>;
 export type FlowMapOptions = Static<typeof FlowMapOptionsSchema>;
+/**
+ * Git working-copy status of a project. Stable fields are documented in the
+ * DSS 14.7.3 source; DSS additionally returns extension fields, which are
+ * preserved by `additionalProperties: true`.
+ */
+export declare const ProjectGitStatusSchema: import("@sinclair/typebox").TObject<{
+    currentBranch: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    remotes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        url: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>>;
+    trackingCount: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        ahead: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        behind: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    }>>;
+    clean: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    hasUncommittedChanges: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    added: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    changed: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    removed: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    missing: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    modified: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    conflicting: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    untracked: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    untrackedFolders: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    originProjectKey: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    trackingCountWithOriginProject: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        ahead: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        behind: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    }>>;
+}>;
+export type ProjectGitStatus = Static<typeof ProjectGitStatusSchema>;
+export declare const ProjectGitRemoteSchema: import("@sinclair/typebox").TObject<{
+    url: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type ProjectGitRemote = Static<typeof ProjectGitRemoteSchema>;
+/**
+ * Result of a Git mutation. DSS answers with HTTP 200 even for failures, so
+ * `success` is the field callers must inspect before trusting the operation.
+ */
+export declare const ProjectGitActionResultSchema: import("@sinclair/typebox").TObject<{
+    success: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    output: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    logs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    messages: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+}>;
+export type ProjectGitActionResult = Static<typeof ProjectGitActionResultSchema>;
+export declare const ProjectGitTagSchema: import("@sinclair/typebox").TObject<{
+    name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    shortName: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    commit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    annotations: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    readOnly: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
+export type ProjectGitTag = Static<typeof ProjectGitTagSchema>;
+export declare const ProjectGitTagsSchema: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+    name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    shortName: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    commit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    annotations: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    readOnly: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>>;
+export type ProjectGitTags = Static<typeof ProjectGitTagsSchema>;
+/**
+ * Paginated commit log. `nextCommit` is the cursor DSS expects back to fetch
+ * the following page; entries stay unpinned because commit payloads vary.
+ */
+export declare const ProjectGitLogResultSchema: import("@sinclair/typebox").TObject<{
+    entries: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnknown>;
+    nextCommit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type ProjectGitLogResult = Static<typeof ProjectGitLogResultSchema>;
+/**
+ * Diff between two revisions. Stable fields are documented in the DSS 14.7.3
+ * source; DSS additionally returns extension fields, which are preserved by
+ * `additionalProperties: true`.
+ */
+export declare const ProjectGitDiffResultSchema: import("@sinclair/typebox").TObject<{
+    commitFrom: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    commitTo: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    addedLines: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    removedLines: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    changedFiles: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    entries: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnknown>>;
+}>;
+export type ProjectGitDiffResult = Static<typeof ProjectGitDiffResultSchema>;
+export declare const ProjectGitLibrarySchema: import("@sinclair/typebox").TObject<{
+    repository: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    login: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    pathInGitRepository: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    localTargetPath: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    checkout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    addToPythonPath: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
+export type ProjectGitLibrary = Static<typeof ProjectGitLibrarySchema>;
+export declare const ProjectGitLibrariesSchema: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+    repository: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    login: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    pathInGitRepository: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    localTargetPath: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    checkout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    addToPythonPath: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>>;
+export type ProjectGitLibraries = Static<typeof ProjectGitLibrariesSchema>;
+/** Handle returned by Git operations that run asynchronously as a DSS future. */
+export declare const ProjectGitFutureResponseSchema: import("@sinclair/typebox").TObject<{
+    jobId: import("@sinclair/typebox").TString;
+}>;
+export type ProjectGitFutureResponse = Static<typeof ProjectGitFutureResponseSchema>;
+export declare const ProjectGitFutureStateSchema: import("@sinclair/typebox").TObject<{
+    jobId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    hasResult: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    result: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    alive: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    aborted: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    abortable: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    unknown: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    startTime: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    runningTime: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    error: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+}>;
+export type ProjectGitFutureState = Static<typeof ProjectGitFutureStateSchema>;
 export declare const ProjectSummaryArraySchema: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
     projectKey: import("@sinclair/typebox").TString;
     name: import("@sinclair/typebox").TString;
@@ -689,6 +813,7 @@ export declare const DatasetSummaryArraySchema: import("@sinclair/typebox").TArr
     managed: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     params: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         connection: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        uploadConnection: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         catalog: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;

package/dist/packages/types/src/index.js

@@ -123,6 +123,7 @@ export const DatasetSummarySchema = Type.Object({
     managed: Type.Optional(Type.Boolean()),
     params: Type.Optional(Type.Object({
         connection: Type.Optional(Type.String()),
+        uploadConnection: Type.Optional(Type.String()),
         schema: Type.Optional(Type.String()),
         catalog: Type.Optional(Type.String()),
     }, { additionalProperties: true, })),
@@ -141,6 +142,7 @@ export const DatasetDetailsSchema = Type.Object({
     managed: Type.Optional(Type.Boolean()),
     params: Type.Optional(Type.Object({
         connection: Type.Optional(Type.String()),
+        uploadConnection: Type.Optional(Type.String()),
         path: Type.Optional(Type.String()),
         table: Type.Optional(Type.String()),
         schema: Type.Optional(Type.String()),
@@ -159,7 +161,7 @@ export const DatasetDetailsSchema = Type.Object({
 }, { additionalProperties: true, });
 export const DatasetCreateOptionsSchema = Type.Object({
     datasetName: Type.String(),
-    connection: Type.String(),
+    connection: Type.Optional(Type.String()),
     dsType: Type.Optional(Type.String()),
     table: Type.Optional(Type.String()),
     dbSchema: Type.Optional(Type.String()),
@@ -393,8 +395,8 @@ export const FlowZoneUpdateOptionsSchema = Type.Object({
 // ---------------------------------------------------------------------------
 export const FolderCreateOptionsSchema = Type.Object({
     name: Type.String(),
-    type: Type.String(),
-    connection: Type.String(),
+    type: Type.Optional(Type.String()),
+    connection: Type.Optional(Type.String()),
     path: Type.Optional(Type.String()),
     params: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
     projectKey: Type.Optional(Type.String()),
@@ -642,6 +644,107 @@ export const FlowMapOptionsSchema = Type.Object({
     includeRaw: Type.Optional(Type.Boolean()),
 });
 // ---------------------------------------------------------------------------
+// Project Git
+// ---------------------------------------------------------------------------
+/**
+ * Git working-copy status of a project. Stable fields are documented in the
+ * DSS 14.7.3 source; DSS additionally returns extension fields, which are
+ * preserved by `additionalProperties: true`.
+ */
+export const ProjectGitStatusSchema = Type.Object({
+    currentBranch: Type.Optional(Type.String()),
+    remotes: Type.Optional(Type.Array(Type.Object({
+        name: Type.Optional(Type.String()),
+        url: Type.Optional(Type.String()),
+    }, { additionalProperties: true, }))),
+    trackingCount: Type.Optional(Type.Object({
+        ahead: Type.Optional(Type.Number()),
+        behind: Type.Optional(Type.Number()),
+    }, { additionalProperties: true, })),
+    clean: Type.Optional(Type.Boolean()),
+    hasUncommittedChanges: Type.Optional(Type.Boolean()),
+    added: Type.Optional(Type.Array(Type.String())),
+    changed: Type.Optional(Type.Array(Type.String())),
+    removed: Type.Optional(Type.Array(Type.String())),
+    missing: Type.Optional(Type.Array(Type.String())),
+    modified: Type.Optional(Type.Array(Type.String())),
+    conflicting: Type.Optional(Type.Array(Type.String())),
+    untracked: Type.Optional(Type.Array(Type.String())),
+    untrackedFolders: Type.Optional(Type.Array(Type.String())),
+    originProjectKey: Type.Optional(Type.String()),
+    trackingCountWithOriginProject: Type.Optional(Type.Object({
+        ahead: Type.Optional(Type.Number()),
+        behind: Type.Optional(Type.Number()),
+    }, { additionalProperties: true, })),
+}, { additionalProperties: true, });
+export const ProjectGitRemoteSchema = Type.Object({
+    url: Type.Optional(Type.String()),
+}, { additionalProperties: true, });
+/**
+ * Result of a Git mutation. DSS answers with HTTP 200 even for failures, so
+ * `success` is the field callers must inspect before trusting the operation.
+ */
+export const ProjectGitActionResultSchema = Type.Object({
+    success: Type.Optional(Type.Boolean()),
+    output: Type.Optional(Type.Unknown()),
+    logs: Type.Optional(Type.Unknown()),
+    messages: Type.Optional(Type.Unknown()),
+}, { additionalProperties: true, });
+export const ProjectGitTagSchema = Type.Object({
+    name: Type.Optional(Type.String()),
+    shortName: Type.Optional(Type.String()),
+    commit: Type.Optional(Type.Unknown()),
+    annotations: Type.Optional(Type.Unknown()),
+    readOnly: Type.Optional(Type.Boolean()),
+}, { additionalProperties: true, });
+export const ProjectGitTagsSchema = Type.Array(ProjectGitTagSchema);
+/**
+ * Paginated commit log. `nextCommit` is the cursor DSS expects back to fetch
+ * the following page; entries stay unpinned because commit payloads vary.
+ */
+export const ProjectGitLogResultSchema = Type.Object({
+    entries: Type.Array(Type.Unknown()),
+    nextCommit: Type.Optional(Type.String()),
+}, { additionalProperties: true, });
+/**
+ * Diff between two revisions. Stable fields are documented in the DSS 14.7.3
+ * source; DSS additionally returns extension fields, which are preserved by
+ * `additionalProperties: true`.
+ */
+export const ProjectGitDiffResultSchema = Type.Object({
+    commitFrom: Type.Optional(Type.Unknown()),
+    commitTo: Type.Optional(Type.Unknown()),
+    addedLines: Type.Optional(Type.Number()),
+    removedLines: Type.Optional(Type.Number()),
+    changedFiles: Type.Optional(Type.Number()),
+    entries: Type.Optional(Type.Array(Type.Unknown())),
+}, { additionalProperties: true, });
+export const ProjectGitLibrarySchema = Type.Object({
+    repository: Type.Optional(Type.String()),
+    login: Type.Optional(Type.String()),
+    pathInGitRepository: Type.Optional(Type.String()),
+    localTargetPath: Type.Optional(Type.String()),
+    checkout: Type.Optional(Type.String()),
+    addToPythonPath: Type.Optional(Type.Boolean()),
+}, { additionalProperties: true, });
+export const ProjectGitLibrariesSchema = Type.Array(ProjectGitLibrarySchema);
+/** Handle returned by Git operations that run asynchronously as a DSS future. */
+export const ProjectGitFutureResponseSchema = Type.Object({
+    jobId: Type.String(),
+}, { additionalProperties: true, });
+export const ProjectGitFutureStateSchema = Type.Object({
+    jobId: Type.Optional(Type.String()),
+    hasResult: Type.Optional(Type.Boolean()),
+    result: Type.Optional(Type.Unknown()),
+    alive: Type.Optional(Type.Boolean()),
+    aborted: Type.Optional(Type.Boolean()),
+    abortable: Type.Optional(Type.Boolean()),
+    unknown: Type.Optional(Type.Boolean()),
+    startTime: Type.Optional(Type.Number()),
+    runningTime: Type.Optional(Type.Number()),
+    error: Type.Optional(Type.Unknown()),
+}, { additionalProperties: true, });
+// ---------------------------------------------------------------------------
 // Array wrappers (for runtime validation of list() responses)
 // ---------------------------------------------------------------------------
 export const ProjectSummaryArraySchema = Type.Array(ProjectSummarySchema);

package/dist/src/cli/coerce.d.ts

@@ -1,5 +1,6 @@
 import type { JobBuildTargetType, JobLogFilter } from "../resources/jobs.js";
-export declare function num(v: string | boolean | undefined): number | undefined;
+export declare function num(v: string | boolean | undefined, flagName?: string): number | undefined;
+export declare function numFlag(flags: Record<string, string | boolean>, flagNames: string[]): number | undefined;
 export declare function jobBuildTargetType(v: string | boolean | undefined): JobBuildTargetType;
 export declare function jobBuildTargetTypeFromFlags(flags: Record<string, string | boolean>): JobBuildTargetType;
 export declare function maxLogLinesFromFlags(flags: Record<string, string | boolean>): number | undefined;

package/dist/src/cli/coerce.js

@@ -1,10 +1,31 @@
 import { readFileSync, } from "node:fs";
 import { UsageError, } from "./usage.js";
-export function num(v) {
-    if (typeof v !== "string")
+function safeValuePreview(value) {
+    return value.length <= 32 ? value : `${value.slice(0, 32)}…`;
+}
+export function num(v, flagName) {
+    if (v === undefined || v === false)
         return undefined;
+    if (typeof v !== "string") {
+        throw new UsageError(`${flagName ?? "Numeric flag"} requires a value.`, "invalid_flag_value", undefined, flagName ? { flag: flagName, } : {});
+    }
+    if (v.trim().length === 0) {
+        throw new UsageError(`Invalid numeric value for ${flagName ?? "flag"}.`, "invalid_flag_value", undefined, flagName ? { flag: flagName, } : {});
+    }
     const n = Number(v);
-    return Number.isFinite(n) ? n : undefined;
+    if (!Number.isFinite(n)) {
+        throw new UsageError(`Invalid numeric value for ${flagName ?? "flag"}: ${safeValuePreview(v)}.`, "invalid_flag_value", undefined, {
+            ...(flagName ? { flag: flagName, } : {}),
+            value: safeValuePreview(v),
+        });
+    }
+    return n;
+}
+export function numFlag(flags, flagNames) {
+    const flagName = flagNames.find((name) => flags[name] !== undefined && flags[name] !== false);
+    if (flagName === undefined)
+        return undefined;
+    return num(flags[flagName], `--${flagName}`);
 }
 export function jobBuildTargetType(v) {
     if (v === undefined)
@@ -21,7 +42,7 @@ export function jobBuildTargetTypeFromFlags(flags) {
     return jobBuildTargetType(flags["target-type"] ?? flags["type"]);
 }
 export function maxLogLinesFromFlags(flags) {
-    return num(flags["max-log-lines"] ?? flags["max-lines"]);
+    return numFlag(flags, ["max-log-lines", "max-lines",]);
 }
 export function jobLogFilterFromFlag(v) {
     if (v === undefined)
@@ -124,32 +145,62 @@ export function parseJsonObject(text, source) {
     return expectJsonObject(parseJsonValue(text, source), source);
 }
 export function json(v, source = "JSON flag") {
-    if (typeof v !== "string")
+    if (v === undefined || v === false)
         return undefined;
+    if (typeof v !== "string" || v.trim().length === 0) {
+        throw new UsageError(`${source} requires a JSON value.`, "invalid_flag_value");
+    }
     return parseJsonObject(v, source);
 }
 export function readStdinText() {
     return readFileSync(0, "utf-8");
 }
-export function jsonInput(flags) {
-    if (flags["stdin"] === true)
-        return parseJsonObject(readStdinText(), "stdin");
-    if (typeof flags["data-file"] === "string") {
-        return parseJsonObject(readFileSync(flags["data-file"], "utf-8"), flags["data-file"]);
+const JSON_SOURCE_FLAGS = ["stdin", "data-file", "data",];
+const TEXT_SOURCE_FLAGS = ["content", "file",];
+function selectSingleSource(flags, sourceFlags) {
+    const provided = sourceFlags.filter((name) => {
+        const value = flags[name];
+        if (value === undefined || value === false)
+            return false;
+        return name === "stdin" ? parseBooleanOption(value, "--stdin") === true : true;
+    });
+    if (provided.length > 1) {
+        throw new UsageError(`Conflicting input sources: ${provided.map((name) => `--${name}`).join(" or ")}. Provide exactly one.`, "conflicting_input_sources", undefined, { sources: provided, });
     }
-    if (typeof flags["data"] === "string")
-        return parseJsonObject(flags["data"], "--data");
-    return undefined;
+    return provided[0];
 }
-export function unknownJsonInput(flags) {
-    if (flags["stdin"] === true)
-        return parseJsonValue(readStdinText(), "stdin");
-    if (typeof flags["data-file"] === "string") {
-        return parseJsonValue(readFileSync(flags["data-file"], "utf-8"), flags["data-file"]);
+function resolveJsonSourceText(flags, kind) {
+    const source = selectSingleSource(flags, JSON_SOURCE_FLAGS);
+    if (source === undefined)
+        return undefined;
+    if (source === "stdin") {
+        const jsonText = readStdinText();
+        return kind === "object"
+            ? parseJsonObject(jsonText, "stdin")
+            : parseJsonValue(jsonText, "stdin");
     }
-    if (typeof flags["data"] === "string")
-        return parseJsonValue(flags["data"], "--data");
-    return undefined;
+    if (source === "data-file") {
+        const fileValue = flags["data-file"];
+        if (typeof fileValue === "string") {
+            const jsonText = readFileSync(fileValue, "utf-8");
+            return kind === "object"
+                ? parseJsonObject(jsonText, fileValue)
+                : parseJsonValue(jsonText, fileValue);
+        }
+    }
+    const dataValue = flags["data"];
+    if (typeof dataValue === "string") {
+        return kind === "object"
+            ? parseJsonObject(dataValue, "--data")
+            : parseJsonValue(dataValue, "--data");
+    }
+    throw new UsageError("JSON input source is present but has no value.", "invalid_flag_value");
+}
+export function jsonInput(flags) {
+    return resolveJsonSourceText(flags, "object");
+}
+export function unknownJsonInput(flags) {
+    return resolveJsonSourceText(flags, "any");
 }
 export function schemaColumnsInput(flags, usage) {
     const input = unknownJsonInput(flags);
@@ -184,11 +235,18 @@ export function schemaColumnsInput(flags, usage) {
     });
 }
 export function textInput(flags) {
-    if (typeof flags["content"] === "string")
-        return flags["content"];
-    if (typeof flags["file"] === "string")
-        return readFileSync(flags["file"], "utf-8");
-    return undefined;
+    const source = selectSingleSource(flags, TEXT_SOURCE_FLAGS);
+    if (source === undefined)
+        return undefined;
+    if (source === "file") {
+        const fileValue = flags["file"];
+        if (typeof fileValue === "string")
+            return readFileSync(fileValue, "utf-8");
+    }
+    const contentValue = flags["content"];
+    if (typeof contentValue === "string")
+        return contentValue;
+    throw new UsageError("Text input source is present but has no value.", "invalid_flag_value");
 }
 export function requiredJsonInput(flags, message) {
     const data = jsonInput(flags);

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

@@ -264,8 +264,8 @@ export const appCommands = {
             let waited;
             try {
                 waited = await c.futures.wait(jobId, {
-                    pollIntervalMs: num(f["poll-interval"]),
-                    timeoutMs: num(f["timeout"]),
+                    pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
+                    timeoutMs: num(f["timeout"], "--timeout"),
                 });
             }
             catch (error) {
@@ -353,8 +353,8 @@ export const appCommands = {
                 ...(f["name"] !== undefined ? { name: f["name"], } : {}),
                 copyPermissions: parseBooleanOption(f["copy-permissions"], "--copy-permissions") ?? false,
                 dryRun: parseBooleanOption(f["dry-run"], "--dry-run") ?? false,
-                timeoutMs: num(f["timeout"]),
-                pollIntervalMs: num(f["poll-interval"]),
+                timeoutMs: num(f["timeout"], "--timeout"),
+                pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
             }, CREATE_SUCCESSOR_USAGE);
         },
         usage: CREATE_SUCCESSOR_USAGE,
@@ -550,8 +550,8 @@ export const appCommands = {
             let waited;
             try {
                 waited = await c.futures.wait(futureId, {
-                    pollIntervalMs: num(f["poll-interval"]),
-                    timeoutMs: num(f["timeout"]),
+                    pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
+                    timeoutMs: num(f["timeout"], "--timeout"),
                 });
             }
             catch (error) {