dataiku-sdk 0.12.7 → 1.1.0

package/dist/src/cli/version.js

@@ -1,4 +1,4 @@
-import { readFileSync, } from "node:fs";
+import { readdirSync, readFileSync, statSync, } from "node:fs";
 import { dirname, resolve, } from "node:path";
 import { fileURLToPath, } from "node:url";
 export function findPackageRoot() {
@@ -36,28 +36,194 @@ export function gitDirectory(packageRoot) {
     }
     return resolve(packageRoot, ".git");
 }
+/**
+ * A full lowercase hexadecimal revision is the only provenance claim trusted.
+ * Git is never invoked from runtime version reporting; revisions are resolved
+ * directly from the filesystem layouts Git documents.
+ */
+const FULL_REVISION_PATTERN = /^[0-9a-f]{40}$/;
+export function isFullRevision(value) {
+    return typeof value === "string" && FULL_REVISION_PATTERN.test(value);
+}
+function readGitFile(base, relative) {
+    try {
+        return readFileSync(resolve(base, relative), "utf-8").trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSafeRefName(ref) {
+    return (ref.length > 0
+        && !ref.startsWith("/")
+        && !ref.endsWith("/")
+        && !ref.includes("\\")
+        && !ref.split("/").includes(".."));
+}
+/** Resolve an entry from packed-refs; peeled `^` lines never match a ref. */
+function packedRefFile(base, ref) {
+    let contents;
+    try {
+        contents = readFileSync(resolve(base, "packed-refs"), "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+    for (const line of contents.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0 || trimmed.startsWith("#") || trimmed.startsWith("^"))
+            continue;
+        const splitAt = trimmed.indexOf(" ");
+        if (splitAt <= 0)
+            continue;
+        const hash = trimmed.slice(0, splitAt);
+        if (isFullRevision(hash) && trimmed.slice(splitAt + 1).trim() === ref)
+            return hash;
+    }
+    return undefined;
+}
+/**
+ * The shared git dir behind a linked worktree or submodule checkout: the
+ * `commondir` file inside the worktree's git dir, resolved relative to that
+ * dir. Normal checkouts (no `commondir` file) share their own git dir.
+ */
+function gitCommonDirectory(gitDir) {
+    try {
+        const commondir = readFileSync(resolve(gitDir, "commondir"), "utf-8").trim();
+        return commondir.length > 0 ? resolve(gitDir, commondir) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Full checkout HEAD revision (40-lowercase-hex) — the basis for staleness
+ * comparison. Resolution follows Git's own layouts: a detached revision, then
+ * loose refs in the worktree git dir, then the shared store reached through
+ * `commondir`, then packed-refs in each. Anything that is not a full
+ * lowercase hexadecimal revision is rejected.
+ */
+export function gitFullRevision(packageRoot) {
+    if (!packageRoot)
+        return undefined;
+    const gitDir = gitDirectory(packageRoot);
+    const head = readGitFile(gitDir, "HEAD");
+    if (!head)
+        return undefined;
+    if (isFullRevision(head))
+        return head;
+    if (!head.startsWith("ref:"))
+        return undefined;
+    const ref = head.slice("ref:".length).trim();
+    if (!isSafeRefName(ref))
+        return undefined;
+    for (const base of [gitDir, gitCommonDirectory(gitDir),]) {
+        if (!base)
+            continue;
+        const loose = readGitFile(base, ref);
+        if (loose && isFullRevision(loose))
+            return loose;
+        const packed = packedRefFile(base, ref);
+        if (packed)
+            return packed;
+    }
+    return undefined;
+}
 export function gitRevision(packageRoot) {
+    const full = gitFullRevision(packageRoot);
+    return full ? full.slice(0, 7) : undefined;
+}
+export function detectLoadSource(modulePath = fileURLToPath(import.meta.url)) {
+    return modulePath.replaceAll("\\", "/").includes("/dist/") ? "dist" : "source";
+}
+export function buildMetadataRevision(packageRoot) {
     if (!packageRoot)
         return undefined;
     try {
-        const gitDir = gitDirectory(packageRoot);
-        const head = readFileSync(resolve(gitDir, "HEAD"), "utf-8").trim();
-        if (!head.startsWith("ref:"))
-            return head.slice(0, 7);
-        const ref = head.slice("ref:".length).trim();
-        const full = readFileSync(resolve(gitDir, ref), "utf-8").trim();
-        return full.slice(0, 7);
+        const metadata = JSON.parse(readFileSync(resolve(packageRoot, "dist", "build-metadata.json"), "utf-8"));
+        return typeof metadata.buildRevision === "string"
+            && isFullRevision(metadata.buildRevision)
+            ? metadata.buildRevision
+            : undefined;
     }
     catch {
         return undefined;
     }
 }
+/**
+ * Whether compiled CLI output predates any source input. The build metadata
+ * file is written after `tsc`, so its mtime is the build-completion marker.
+ * Installed packages omit `src/`; without both sides there is no drift claim.
+ */
+export function sourceTreeNewerThanBuild(packageRoot) {
+    if (!packageRoot)
+        return false;
+    try {
+        const buildMtimeMs = statSync(resolve(packageRoot, "dist", "build-metadata.json")).mtimeMs;
+        const pending = [resolve(packageRoot, "src"),];
+        while (pending.length > 0) {
+            const path = pending.pop();
+            if (!path)
+                break;
+            const stat = statSync(path);
+            if (stat.mtimeMs > buildMtimeMs)
+                return true;
+            if (!stat.isDirectory())
+                continue;
+            for (const entry of readdirSync(path, { withFileTypes: true, })) {
+                if (entry.isDirectory() || entry.isFile()) {
+                    pending.push(resolve(path, entry.name));
+                }
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+export function detectRuntime() {
+    return process.versions.bun ? "bun" : "node";
+}
+export function buildVersionPayload(input) {
+    const isDist = input.loadSource === "dist";
+    // Source execution never claims a build revision, even if the environment
+    // happens to carry one.
+    const buildRevision = isDist && input.buildRevision ? input.buildRevision : null;
+    const staleBuild = isDist
+        && ((buildRevision !== null
+            && input.checkoutFullRevision !== undefined
+            && input.checkoutFullRevision !== buildRevision)
+            || input.sourceNewerThanBuild === true);
+    return {
+        version: input.packageVersion,
+        gitRevision: input.checkoutRevision ?? null,
+        source: isDist ? "dist" : "source",
+        runtime: input.runtime,
+        buildRevision,
+        staleBuild,
+    };
+}
 export const PACKAGE_ROOT = findPackageRoot();
 export const CLI_VERSION = packageVersion(PACKAGE_ROOT);
 export const CLI_GIT_REVISION = gitRevision(PACKAGE_ROOT);
-export const AGENT_CONTRACT_VERSION = 1;
+export const AGENT_CONTRACT_VERSION = 2;
 export const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
-export const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v1.json";
+export const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v2.json";
 export function cliVersionResult() {
-    return { version: CLI_VERSION, gitRevision: CLI_GIT_REVISION ?? null, };
+    const loadSource = process.env["DSS_LOAD_SOURCE"] ?? detectLoadSource();
+    const envBuildRevision = process.env["DSS_BUILD_REVISION"];
+    return buildVersionPayload({
+        packageVersion: CLI_VERSION,
+        checkoutRevision: CLI_GIT_REVISION,
+        checkoutFullRevision: gitFullRevision(PACKAGE_ROOT),
+        loadSource,
+        buildRevision: isFullRevision(envBuildRevision)
+            ? envBuildRevision
+            : (loadSource === "dist" ? buildMetadataRevision(PACKAGE_ROOT) : undefined),
+        sourceNewerThanBuild: loadSource === "dist"
+            ? sourceTreeNewerThanBuild(PACKAGE_ROOT)
+            : false,
+        runtime: detectRuntime(),
+    });
 }

package/dist/src/cli.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
+import * as fs from "node:fs/promises";
 import { num, unknownJsonInput, } from "./cli/coerce.js";
 import { commands, } from "./cli/commands/index.js";
-import { AGENT_CONTRACT_USAGE, AUTH_ACTIONS, BATCH_EXAMPLE_PAYLOAD, BATCH_HINT, BATCH_PLAN_EXIT_CODES, BATCH_USAGE, buildAgentContract, buildCommandRegistry, buildMutationPlan, CLEANUP_USAGE, COMMANDS_USAGE, inferRequiresProject, isAllowedCleanupAction, supportsCleanupLedger, } from "./cli/contract.js";
+import { AGENT_CONTRACT_USAGE, AUTH_ACTIONS, BATCH_EXAMPLE_PAYLOAD, BATCH_HINT, BATCH_PLAN_EXIT_CODES, BATCH_USAGE, buildAgentContract, buildCommandRegistry, buildMutationPlan, CLEANUP_USAGE, commandActionSummary, COMMANDS_USAGE, inferRequiresProject, isAllowedCleanupAction, supportsCleanupLedger, } from "./cli/contract.js";
 import { runDoctor, runFixtures, } from "./cli/doctor.js";
 import { dataikuEnvironmentEnabled, loadEnvFile, } from "./cli/env.js";
 import { FLAG_ALIASES, isNegativeNumberToken, parseArgs, SHORT_FLAGS, VALUE_FLAGS, } from "./cli/flags.js";
 import { cleanupLedgerEntry, } from "./cli/helpers/cleanup.js";
-import { commandFailureExitCode, commandFailureMessage, CommandResultFailure, isFailedWaitResult, planResult, projectResultFields, setCompactJsonOutput, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
+import { commandFailureExitCode, commandFailureMessage, CommandResultFailure, flushCliWarnings, isFailedWaitResult, planResult, projectResultFields, setOutputFieldProjection, writeCommandResult, } from "./cli/output.js";
 import { currentCommandContext, resolveCredentials, resolveTlsSettings, } from "./cli/runtime.js";
 import { COMMANDS_RUN_HINT, missingActionError, noCommandError, requireArgs, unknownActionError, unknownResourceError, UsageError, } from "./cli/usage.js";
 import { cliVersionResult, } from "./cli/version.js";
@@ -31,19 +32,28 @@ import { canonicalDssUrl, } from "./utils/dss-url.js";
 // ---------------------------------------------------------------------------
 // Auth commands (run before client creation)
 // ---------------------------------------------------------------------------
-function findUnboundAppCleanup(entries) {
+function findUnboundLifecycleCleanup(entries) {
     for (const [index, entry,] of entries.entries()) {
         const parsed = parseArgs(entry.cleanup.argv);
         const [resource, action,] = parsed.positional;
-        if (resource !== "app" || action !== "delete-instance")
+        if (resource === "app" && action === "delete-instance") {
+            if (parsed.flags["unconfirmed-creation"] === true)
+                continue;
+            const expected = parsed.flags["expect-project-incarnation"];
+            if (typeof expected !== "string")
+                return { index, resource, action, reason: "missing", };
+            if (!/^[0-9a-f]{64}$/.test(expected))
+                return { index, resource, action, reason: "invalid", };
             continue;
-        if (parsed.flags["unconfirmed-creation"] === true)
+        }
+        if (resource === "project" && action === "delete") {
+            const expected = parsed.flags["expect-project-incarnation"];
+            if (typeof expected !== "string")
+                return { index, resource, action, reason: "missing", };
+            if (!/^[0-9a-f]{64}$/.test(expected))
+                return { index, resource, action, reason: "invalid", };
             continue;
-        const expected = parsed.flags["expect-project-incarnation"];
-        if (typeof expected !== "string")
-            return { index, reason: "missing", };
-        if (!/^[0-9a-f]{64}$/.test(expected))
-            return { index, reason: "invalid", };
+        }
     }
     return undefined;
 }
@@ -83,8 +93,8 @@ async function runCleanup(flags) {
     if (!apiKey) {
         throw new UsageError("Missing API key. Set DATAIKU_API_KEY or pass --api-key.", "missing_required_flag");
     }
-    const requestTimeoutMs = num(flags["request-timeout"]);
-    const retryMaxAttempts = num(flags["retries"]);
+    const requestTimeoutMs = num(flags["request-timeout"], "--request-timeout");
+    const retryMaxAttempts = num(flags["retries"], "--retries");
     const client = new DataikuClient({
         url,
         apiKey,
@@ -118,9 +128,10 @@ async function runCleanup(flags) {
         };
     }
     // Lifecycle binding is as load-bearing as server binding. Validate the whole
-    // reversed plan before step one so a later legacy app entry cannot leave an
-    // earlier cleanup applied and then fail on project-key reuse protection.
-    const lifecycleViolation = findUnboundAppCleanup(ordered);
+    // reversed plan before step one so a later legacy app or project entry
+    // cannot leave an earlier cleanup applied and then fail on project-key
+    // reuse protection.
+    const lifecycleViolation = findUnboundLifecycleCleanup(ordered);
     if (lifecycleViolation) {
         return {
             result: {
@@ -128,8 +139,8 @@ async function runCleanup(flags) {
                 steps,
                 lifecycleError: {
                     entryIndex: lifecycleViolation.index,
-                    resource: "app",
-                    action: "delete-instance",
+                    resource: lifecycleViolation.resource,
+                    action: lifecycleViolation.action,
                     reason: lifecycleViolation.reason,
                 },
             },
@@ -146,6 +157,11 @@ async function runCleanup(flags) {
                 || !commands[resource]?.[action]) {
                 throw new UsageError(`Invalid cleanup argv: ${entry.cleanup.argv.join(" ")}`);
             }
+            if (resource === "project"
+                && action === "delete"
+                && typeof parsed.flags["expect-project-incarnation"] !== "string") {
+                throw new UsageError("Project cleanup entry is not bound to a project incarnation. Refusing deletion after possible project-key reuse.", "validation_failed", "Capture a new cleanup entry from the current CLI. Legacy entries cannot safely delete projects.");
+            }
             if (resource === "app"
                 && action === "delete-instance"
                 && parsed.flags["unconfirmed-creation"] !== true
@@ -252,11 +268,11 @@ function supportedCommandFlags(entry) {
     return supported;
 }
 function scopedCommandDiscoveryHint(resource, action) {
-    return `Use \`dss commands run --fields ${resource}.${action} --json\` to list the flags this command supports.`;
+    return `Use \`dss commands run --fields ${resource}.${action}\` to list the flags this command supports.`;
 }
 /**
  * Resolve the registry field selectors for `commands run --fields`. Omitting the flag
- * selects the whole registry, but an explicitly supplied value carrying no selector is a
+ * selects the action summary; `--output` exports the full registry, but an explicitly supplied value carrying no selector is a
  * usage error: an agent that asked for a scoped subset must never be handed the full
  * registry instead.
  */
@@ -419,6 +435,7 @@ function validateMetaCommandInputs(resource, action, flags) {
             throw missingActionError("commands", ["run",], COMMANDS_USAGE);
         if (action !== "run")
             throw unknownActionError("commands", action, ["run",]);
+        validateSupportedCommandFlags("commands", "run", flags);
         commandRegistrySelectors(flags);
         return action;
     }
@@ -516,9 +533,10 @@ function batchStepCommandContext(argv) {
     }
     return { resource: positionals[0], action: positionals[1], };
 }
-const SENSITIVE_ARGV_VALUE_FLAGS = new Set([
-    "api-key",
-]);
+const SENSITIVE_ARGV_VALUE_FLAGS = {
+    "api-key": true,
+    repository: true,
+};
 function redactArgv(argv) {
     const redacted = [];
     for (let index = 0; index < argv.length; index++) {
@@ -531,7 +549,7 @@ function redactArgv(argv) {
             const eqIdx = arg.indexOf("=");
             const rawFlagName = eqIdx === -1 ? arg.slice(2) : arg.slice(2, eqIdx);
             const flagName = FLAG_ALIASES[rawFlagName] ?? rawFlagName;
-            if (SENSITIVE_ARGV_VALUE_FLAGS.has(flagName)) {
+            if (SENSITIVE_ARGV_VALUE_FLAGS[flagName] === true) {
                 if (eqIdx !== -1) {
                     redacted.push(`${arg.slice(0, eqIdx + 1)}***`);
                 }
@@ -763,6 +781,7 @@ async function runMetaCommand(resource, action, flags) {
         currentCommandContext.action = action;
         if (action !== "run")
             throw unknownActionError("commands", action, ["run",]);
+        validateSupportedCommandFlags("commands", "run", flags);
         const selectors = commandRegistrySelectors(flags);
         const registry = buildCommandRegistry();
         for (const selector of selectors) {
@@ -778,7 +797,20 @@ async function runMetaCommand(resource, action, flags) {
                 throw unknownActionError(selectedResource, selectedAction, Object.keys(resourceActions));
             }
         }
-        return { action, result: registry, exitCode: 0, };
+        const outputPath = flags["output"];
+        const selectedRegistry = selectors.length === 0
+            ? registry
+            : projectResultFields(registry, selectors);
+        if (typeof outputPath === "string") {
+            const exported = selectedRegistry;
+            await fs.writeFile(outputPath, `${JSON.stringify(exported)}\n`, "utf-8");
+            return { action, result: { path: outputPath, }, exitCode: 0, };
+        }
+        return {
+            action,
+            result: selectors.length === 0 ? commandActionSummary(registry) : selectedRegistry,
+            exitCode: 0,
+        };
     }
     if (resource === "version") {
         if (action !== undefined && action !== "run") {
@@ -972,8 +1004,8 @@ async function runBatch(flags) {
             apiKey,
             projectKey,
             verbose: flags["verbose"] === true,
-            requestTimeoutMs: num(flags["request-timeout"]),
-            retryMaxAttempts: num(flags["retries"]),
+            requestTimeoutMs: num(flags["request-timeout"], "--request-timeout"),
+            retryMaxAttempts: num(flags["retries"], "--retries"),
             tlsRejectUnauthorized,
             caCertPath,
         });
@@ -1050,7 +1082,9 @@ async function runBatch(flags) {
             const stepFields = typeof stepFieldsFlag === "string"
                 ? stepFieldsFlag.split(",").map((field) => field.trim()).filter((field) => field.length > 0)
                 : [];
-            const stepResult = stepFields.length > 0 ? projectResultFields(result, stepFields) : result;
+            const stepResult = stepFields.length > 0 && !(resource === "commands" && action === "run")
+                ? projectResultFields(result, stepFields)
+                : result;
             results.push({
                 index,
                 args: redactArgv(argv),
@@ -1175,6 +1209,8 @@ const MISSING_PROJECT_KEY_ERROR_PREFIX = "projectKey is required";
 function errorExitCode(err) {
     if (err instanceof CommandResultFailure)
         return err.exitCode;
+    if (err instanceof ClientValidationError && err.code === "ambiguous_outcome")
+        return 2;
     if (err instanceof UsageError || err instanceof ClientValidationError)
         return 1;
     if (err instanceof DataikuError)
@@ -1186,6 +1222,19 @@ function errorExitCode(err) {
 function buildErrorReport(err) {
     const context = rawCommandContext();
     const exitCode = errorExitCode(err);
+    if (err instanceof ClientValidationError && err.code === "ambiguous_outcome") {
+        return {
+            type: "error",
+            ok: false,
+            error: err.message,
+            code: err.code,
+            category: "dss",
+            exitCode,
+            ...(err.hint ? { hint: err.hint, } : {}),
+            ...(err.details ? { details: err.details, } : {}),
+            ...context,
+        };
+    }
     if (err instanceof UsageError || err instanceof ClientValidationError) {
         return {
             type: "error",
@@ -1268,7 +1317,8 @@ function buildErrorReport(err) {
     };
 }
 function writeErrorReport(err) {
-    process.stderr.write(`${JSON.stringify(buildErrorReport(err))}\n`);
+    flushCliWarnings();
+    process.stdout.write(`${JSON.stringify(buildErrorReport(err))}\n`);
 }
 // ---------------------------------------------------------------------------
 // Main
@@ -1276,12 +1326,14 @@ function writeErrorReport(err) {
 async function main() {
     loadEnvFile();
     const { positional, flags, } = parseArgs(process.argv.slice(2));
-    setCompactJsonOutput(flags["json"] === true);
     const fieldsFlag = flags["fields"];
     if (typeof fieldsFlag === "string") {
         const selected = fieldsFlag.split(",").map((field) => field.trim()).filter((field) => field.length > 0);
-        if (selected.length > 0)
-            setOutputFieldProjection(selected);
+        if (selected.length > 0) {
+            const commandsRunProjection = positional[0] === "commands" && positional[1] === "run";
+            if (!commandsRunProjection)
+                setOutputFieldProjection(selected);
+        }
     }
     if (flags["version"] === true) {
         writeCommandResult(cliVersionResult());
@@ -1324,6 +1376,14 @@ async function main() {
         writeCommandResult(plan);
         return;
     }
+    if (actionMeta.localHandler) {
+        const result = await actionMeta.localHandler(args, flags);
+        const failureExitCode = commandFailureExitCode(result);
+        if (failureExitCode !== undefined)
+            throw new CommandResultFailure(result, failureExitCode);
+        writeCommandResult(result);
+        return;
+    }
     const { url, apiKey, projectKey, tlsRejectUnauthorized, caCertPath, } = resolveCredentials(flags);
     currentCommandContext.projectKey = projectKey;
     if (!url) {
@@ -1332,8 +1392,8 @@ async function main() {
     if (!apiKey) {
         throw new UsageError("Missing API key.", "missing_required_flag", "Set DATAIKU_API_KEY or pass --api-key.", { requiredFlags: ["api-key",], env: ["DATAIKU_API_KEY",], });
     }
-    const requestTimeoutMs = num(flags["request-timeout"]);
-    const retryMaxAttempts = num(flags["retries"]);
+    const requestTimeoutMs = num(flags["request-timeout"], "--request-timeout");
+    const retryMaxAttempts = num(flags["retries"], "--retries");
     const client = new DataikuClient({
         url,
         apiKey,
@@ -1351,12 +1411,7 @@ async function main() {
     const failureExitCode = commandFailureExitCode(result);
     if (failureExitCode !== undefined)
         throw new CommandResultFailure(result, failureExitCode);
-    if (flags["raw"] === true && typeof result === "string" && typeof flags["output"] !== "string") {
-        process.stdout.write(result);
-    }
-    else {
-        writeCommandResult(result);
-    }
+    writeCommandResult(result);
 }
 main().catch((err) => {
     writeErrorReport(err);

package/dist/src/client.d.ts

@@ -21,6 +21,7 @@ import { MetricsResource } from "./resources/metrics.js";
 import { MlTasksResource } from "./resources/ml-tasks.js";
 import { ModelEvaluationStoresResource } from "./resources/model-evaluation-stores.js";
 import { NotebooksResource } from "./resources/notebooks.js";
+import { ProjectGitResource } from "./resources/project-git.js";
 import { ProjectLibraryResource } from "./resources/project-library.js";
 import { ProjectsResource } from "./resources/projects.js";
 import { RecipesResource } from "./resources/recipes.js";
@@ -44,6 +45,21 @@ export interface DataikuClientTraceEvent {
     elapsedMs?: number;
     detail?: string;
 }
+/**
+ * Selected response metadata captured alongside a public API response body.
+ * A fixed whitelist of non-sensitive headers: authorization data is never
+ * returned. Null means the header was absent.
+ */
+export interface DataikuClientResponseMeta {
+    /** `DSS-Version` — version of the DSS backend answering the request. */
+    dssVersion: string | null;
+    /** `DSS-API-Version` — version of the API server handling the request. */
+    dssApiVersion: string | null;
+    /** `Date` — origin server timestamp, when present. */
+    date: string | null;
+    /** Server-provided request id, when present. */
+    requestId: string | null;
+}
 export interface DataikuClientConfig {
     /** DSS base URL (e.g. https://dss.example.com) */
     url: string;
@@ -104,6 +120,7 @@ export declare class DataikuClient {
     private bundlesResource?;
     private projectDeployerResource?;
     private projectLibraryResource?;
+    private projectGitResource?;
     private streamingEndpointsResource?;
     private continuousActivitiesResource?;
     private statisticsResource?;
@@ -139,6 +156,7 @@ export declare class DataikuClient {
     get bundles(): BundlesResource;
     get projectDeployer(): ProjectDeployerResource;
     get projectLibrary(): ProjectLibraryResource;
+    get projectGit(): ProjectGitResource;
     get streamingEndpoints(): StreamingEndpointsResource;
     get continuousActivities(): ContinuousActivitiesResource;
     get statistics(): StatisticsResource;
@@ -160,6 +178,15 @@ export declare class DataikuClient {
     getRequestTimeoutMs(): number;
     resolveProjectKey(paramValue?: string): string;
     get<T = unknown>(path: string): Promise<T>;
+    /**
+     * GET returning the parsed JSON body plus selected response metadata
+     * (documented DSS version headers, server date, request id). Authorization
+     * headers are never included.
+     */
+    getWithMetadata<T = unknown>(path: string): Promise<{
+        data: T;
+        meta: DataikuClientResponseMeta;
+    }>;
     getText(path: string): Promise<string>;
     getTextLimited(path: string, maxBytes: number): Promise<{
         text: string;
@@ -177,10 +204,13 @@ export declare class DataikuClient {
     put<T = unknown>(path: string, body: unknown): Promise<T>;
     del(path: string): Promise<void>;
     putVoid(path: string, body: unknown): Promise<void>;
-    upload(path: string, filePath: string): Promise<void>;
+    private uploadResponse;
+    upload(path: string, filePath: string, fileName?: string): Promise<void>;
+    uploadJson<T>(path: string, filePath: string, fileName?: string): Promise<T>;
     stream(path: string): Promise<Response>;
     private getHeaders;
     private getAnyHeaders;
+    private responseMeta;
     private logTrace;
     /**
      * Validate raw data against a TypeBox schema, throwing on structural mismatch.

package/dist/src/client.js

@@ -1,4 +1,5 @@
-import { readFileSync, } from "node:fs";
+import { openAsBlob, readFileSync, } from "node:fs";
+import { basename, } from "node:path";
 import { getCACertificates, } from "node:tls";
 import { Value, } from "@sinclair/typebox/value";
 import { safeParseSchema, } from "./schemas.js";
@@ -25,6 +26,7 @@ import { MetricsResource, } from "./resources/metrics.js";
 import { MlTasksResource, } from "./resources/ml-tasks.js";
 import { ModelEvaluationStoresResource, } from "./resources/model-evaluation-stores.js";
 import { NotebooksResource, } from "./resources/notebooks.js";
+import { ProjectGitResource, } from "./resources/project-git.js";
 import { ProjectLibraryResource, } from "./resources/project-library.js";
 import { ProjectsResource, } from "./resources/projects.js";
 import { RecipesResource, } from "./resources/recipes.js";
@@ -189,6 +191,7 @@ export class DataikuClient {
     bundlesResource;
     projectDeployerResource;
     projectLibraryResource;
+    projectGitResource;
     streamingEndpointsResource;
     continuousActivitiesResource;
     statisticsResource;
@@ -272,6 +275,9 @@ export class DataikuClient {
     get projectLibrary() {
         return (this.projectLibraryResource ??= new ProjectLibraryResource(this));
     }
+    get projectGit() {
+        return (this.projectGitResource ??= new ProjectGitResource(this));
+    }
     get streamingEndpoints() {
         return (this.streamingEndpointsResource ??= new StreamingEndpointsResource(this));
     }
@@ -355,6 +361,19 @@ export class DataikuClient {
         });
         return this.parseJsonResponse(res);
     }
+    /**
+     * GET returning the parsed JSON body plus selected response metadata
+     * (documented DSS version headers, server date, request id). Authorization
+     * headers are never included.
+     */
+    async getWithMetadata(path) {
+        const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
+            method: "GET",
+            headers: this.getHeaders(),
+        });
+        const data = await this.parseJsonResponse(res);
+        return { data, meta: this.responseMeta(res.headers), };
+    }
     async getText(path) {
         const res = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "GET",
@@ -459,19 +478,23 @@ export class DataikuClient {
             body: JSON.stringify(body),
         });
     }
-    async upload(path, filePath) {
-        const { openAsBlob, } = await import("node:fs");
-        const { basename, } = await import("node:path");
+    async uploadResponse(path, filePath, fileName) {
         const fileBlob = await openAsBlob(filePath);
-        const fileName = basename(filePath);
         const formData = new FormData();
-        formData.append("file", fileBlob, fileName);
-        await this.fetchWithRetry(`${this.baseUrl}${path}`, {
+        formData.append("file", fileBlob, fileName ?? basename(filePath));
+        return this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "POST",
             headers: { Authorization: `Bearer ${this.apiKey}`, },
             body: formData,
         });
     }
+    async upload(path, filePath, fileName) {
+        await this.uploadResponse(path, filePath, fileName);
+    }
+    async uploadJson(path, filePath, fileName) {
+        const response = await this.uploadResponse(path, filePath, fileName);
+        return this.parseJsonResponse(response);
+    }
     async stream(path) {
         return this.fetchWithRetry(`${this.baseUrl}${path}`, {
             method: "GET",
@@ -492,6 +515,15 @@ export class DataikuClient {
             Accept: "*/*",
         };
     }
+    responseMeta(headers) {
+        // Fixed non-sensitive whitelist. `Headers.get` is case-insensitive.
+        return {
+            dssVersion: headers.get("dss-version"),
+            dssApiVersion: headers.get("dss-api-version"),
+            date: headers.get("date"),
+            requestId: this.requestIdFromHeaders(headers) ?? null,
+        };
+    }
     logTrace(event) {
         if (this.verbose)
             this.onTrace({ type: "trace", ...event, });