dataiku-sdk 1.0.0 → 1.1.0

package/dist/src/cli/contract.js

@@ -234,7 +234,7 @@ const AGENT_CONTRACT_EXAMPLES = [
     "dss agent contract --fields commands.actions",
 ];
 const VERSION_USAGE = "dss version";
-const VERSION_DESCRIPTION = "Print the CLI version and git revision as JSON.";
+const VERSION_DESCRIPTION = "Print the CLI version, checkout/build revisions, load source, runtime, and stale-build status as JSON.";
 const VERSION_EXAMPLES = ["dss version", "dss --version",];
 const INSTALL_SKILL_USAGE = "dss install-skill [--global] [--agent NAME] [--target PATH] [--list-agents] [--dry-run] [--plan]";
 const INSTALL_SKILL_DESCRIPTION = "Install the dataiku-dss agent skill for detected coding agents.";
@@ -270,6 +270,7 @@ const ALLOWED_CLEANUP_ACTIONS = new Set([
     "code-env delete",
     "folder delete",
     "folder delete-file",
+    "project delete",
     "app delete-instance",
 ]);
 export function isAllowedCleanupAction(resource, action) {
@@ -676,6 +677,7 @@ export function inferRequiresProject(resource, action, usage) {
 const ARRAY_OUTPUT_ACTIONS = new Set([
     "history",
     "find",
+    "files",
     "infer",
     "last-results",
     "list",
@@ -861,6 +863,9 @@ function inferPayloadSchema(inputContract) {
 function inferExitCodes(resource, action, asyncKind) {
     const longRunning = asyncKind !== "none" || `${resource}.${action}` === "batch.run";
     const assertion = `${resource}.${action}` === "recipe.assert-unchanged"
+        || `${resource}.${action}` === "dataset.assert-count"
+        || `${resource}.${action}` === "dataset.assert-schema"
+        || `${resource}.${action}` === "data-quality.assert-results"
         || `${resource}.${action}` === "batch.run";
     return {
         ok: 0,
@@ -872,6 +877,9 @@ function inferExitCodes(resource, action, asyncKind) {
     };
 }
 function cleanupCommandFromDeleteUsage(resource, action) {
+    if (`${resource}.${action}` === "project.import") {
+        return "dss project delete <used-project-key> --if-exists --expect-project-incarnation <hash>";
+    }
     if (resource === "project" && (action === "create" || action === "duplicate")) {
         return undefined;
     }
@@ -895,9 +903,20 @@ export function supportsCleanupLedger(resource, action) {
     return cleanupCommandFromDeleteUsage(resource, action) !== undefined
         || `${resource}.${action}` === "folder.upload";
 }
+/**
+ * Write actions that no public DSS route can undo. `dataset upload-file` adds a
+ * file to the dataset's uploaded-files set, and DSS exposes no endpoint to
+ * replace or delete an individual uploaded file, so the write is permanent and
+ * no cleanup-ledger entry can recover the previous file set.
+ */
+const EXPLICIT_DESTRUCTIVE_KEYS = {
+    "dataset.upload-file": true,
+};
 function inferDestructiveLevel(resource, sideEffect, action) {
     if (sideEffect !== "write")
         return "none";
+    if (EXPLICIT_DESTRUCTIVE_KEYS[`${resource}.${action}`] === true)
+        return "destructive";
     if (resource === "project-git") {
         return PROJECT_GIT_DESTRUCTIVE_ACTIONS[action] === true ? "destructive" : "reversible";
     }
@@ -992,7 +1011,7 @@ export function inferCleanupHint(resource, action) {
     return `Delete with \`dss ${resource} delete <id>${ifExists}\` when the created object is disposable.`;
 }
 function buildRegistryEntry(resource, action, meta) {
-    const requiresAuth = inferRequiresAuth(resource);
+    const requiresAuth = meta.localHandler === undefined && inferRequiresAuth(resource);
     const requiresProject = inferRequiresProject(resource, action, meta.usage);
     const sideEffect = inferSideEffect(resource, action);
     const destructive = inferDestructiveLevel(resource, sideEffect, action);
@@ -1781,6 +1800,38 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: { oldName: args[0], newName: args[1], },
                 payload: { oldName: args[0], newName: args[1], },
             };
+        case "dataset.upload-file": {
+            const fileName = requiredPlanFlag(flags, "file-name", entry.usage);
+            const datasetEndpoint = projectEndpoint(`/datasets/${encodeURIComponent(args[0])}`);
+            const filesEndpoint = `${datasetEndpoint}/uploaded/files`;
+            const upload = {
+                method: "POST",
+                endpoint: filesEndpoint,
+                payload: { ...uploadPayload(args[1]), fileName, },
+            };
+            return {
+                ...upload,
+                identifiers: {
+                    datasetName: args[0],
+                    localPath: args[1],
+                    fileName,
+                },
+                requests: [
+                    { sequence: 1, method: "GET", endpoint: datasetEndpoint, },
+                    { sequence: 2, method: "GET", endpoint: filesEndpoint, },
+                    { sequence: 3, ...upload, },
+                    {
+                        sequence: 4,
+                        method: "GET",
+                        endpoint: filesEndpoint,
+                        assert: {
+                            filename: fileName,
+                            length: "local file byte length",
+                        },
+                    },
+                ],
+            };
+        }
         case "dataset.delete":
             return {
                 method: "DELETE",
@@ -2812,17 +2863,74 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 },
             };
         }
-        case "project.delete":
+        case "project.delete": {
+            const expectedProjectIncarnation = flags["expect-project-incarnation"] === undefined
+                ? undefined
+                : requiredPlanFlag(flags, "expect-project-incarnation", entry.usage);
+            if (expectedProjectIncarnation !== undefined
+                && !/^[0-9a-f]{64}$/.test(expectedProjectIncarnation)) {
+                throw new UsageError("--expect-project-incarnation must be a 64-character lowercase SHA-256 hash.", "validation_failed");
+            }
+            const endpoint = `/public/api/projects/${encodeURIComponent(id)}${querySuffix({
+                clearManagedDatasets: flags["drop-data"] === true,
+                clearOutputManagedFolders: false,
+                clearJobAndScenarioLogs: true,
+                wait: true,
+            })}`;
+            const guarded = flags["if-exists"] === true
+                || flags["dry-run"] === true
+                || expectedProjectIncarnation !== undefined;
+            if (!guarded) {
+                return {
+                    method: "DELETE",
+                    endpoint,
+                    identifiers: { projectKey: id, },
+                };
+            }
+            const projectProbe = `/public/api/projects/${encodeURIComponent(id)}/`;
+            const incarnationGate = expectedProjectIncarnation === undefined
+                ? { required: false, provided: false, }
+                : {
+                    required: true,
+                    provided: true,
+                    expectedHash: expectedProjectIncarnation,
+                };
+            if (flags["dry-run"] === true) {
+                return {
+                    method: "GET",
+                    endpoint: projectProbe,
+                    identifiers: {
+                        projectKey: id,
+                        dryRun: true,
+                        ifExists: flags["if-exists"] === true,
+                        projectIncarnationGate: incarnationGate,
+                        note: "Read-only guarded-delete preflight. No DELETE is issued; a supplied creationTag hash must match.",
+                    },
+                };
+            }
             return {
                 method: "DELETE",
-                endpoint: `/public/api/projects/${encodeURIComponent(id)}${querySuffix({
-                    clearManagedDatasets: flags["drop-data"] === true,
-                    clearOutputManagedFolders: false,
-                    clearJobAndScenarioLogs: true,
-                    wait: true,
-                })}`,
-                identifiers: { projectKey: id, },
+                endpoint,
+                identifiers: {
+                    projectKey: id,
+                    ifExists: flags["if-exists"] === true,
+                    projectIncarnationGate: incarnationGate,
+                    incarnationControl: expectedProjectIncarnation === undefined
+                        ? "none"
+                        : "client-side-non-atomic-stale-identity-check",
+                    preflightRequests: [{
+                            method: "GET",
+                            endpoint: projectProbe,
+                            intent: expectedProjectIncarnation === undefined
+                                ? "Confirm existence before a convergent delete."
+                                : "Recompute the current project-incarnation hash from creationTag before DELETE.",
+                        },],
+                    note: expectedProjectIncarnation === undefined
+                        ? "Convergent delete: a 404 preflight is an already-absent success only with --if-exists."
+                        : "Incarnation-bound delete: the GET must match the expected creationTag hash before an unconditional DELETE. DSS exposes no conditional project DELETE, so the client-side gate cannot serialize against key reuse after the GET.",
+                },
             };
+        }
         case "project.duplicate": {
             const options = jsonInput(flags);
             return {
@@ -2844,11 +2952,32 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 },
             };
         }
-        case "project.import":
-            return {
+        case "project.import": {
+            const settings = jsonInput(flags) ?? {};
+            const rawTarget = flags["target-project-key"];
+            const targetProjectKey = rawTarget?.trim();
+            if (rawTarget !== undefined && targetProjectKey === "") {
+                throw new UsageError(`--target-project-key must not be empty. Usage: ${entry.usage}`);
+            }
+            const settingsTarget = settings.targetProjectKey;
+            if (settingsTarget !== undefined
+                && (typeof settingsTarget !== "string" || settingsTarget.trim() === "")) {
+                throw new UsageError(`targetProjectKey in import settings must be a non-empty string. Usage: ${entry.usage}`);
+            }
+            if (targetProjectKey !== undefined
+                && settingsTarget !== undefined
+                && targetProjectKey !== settingsTarget.trim()) {
+                throw new UsageError(`--target-project-key conflicts with targetProjectKey in import settings. Usage: ${entry.usage}`);
+            }
+            const processPayload = targetProjectKey === undefined
+                ? settings
+                : { ...settings, targetProjectKey, };
+            const finalizedPayload = Object.keys(processPayload).length === 0
+                ? { _: "_", }
+                : processPayload;
+            const upload = {
                 method: "POST",
                 endpoint: "/public/api/projects/import/upload",
-                identifiers: { filePath: id, },
                 payload: {
                     contentType: "multipart/form-data",
                     fileField: "file",
@@ -2856,6 +2985,46 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                     fileName: "tmp-import.zip",
                 },
             };
+            return {
+                ...upload,
+                identifiers: {
+                    filePath: id,
+                    ...(targetProjectKey ? { targetProjectKey, } : {}),
+                    archivePreflight: {
+                        local: true,
+                        required: true,
+                        checks: [
+                            "zip-integrity",
+                            "safe-unique-members",
+                            "manifest",
+                            "flow-references",
+                            "orphan-members",
+                        ],
+                    },
+                    successVerification: {
+                        usedProjectKeyRequired: true,
+                        projectReadRequired: true,
+                        projectIncarnationRequired: true,
+                        remappingReported: true,
+                    },
+                    ...(flags["record-cleanup"] === undefined
+                        ? {}
+                        : {
+                            cleanupBinding: "actual used project key plus verified creationTag incarnation hash",
+                        }),
+                },
+                requests: [
+                    { sequence: 1, ...upload, },
+                    {
+                        sequence: 2,
+                        method: "POST",
+                        endpoint: "/public/api/projects/import/{importId}/process",
+                        pathBindings: { importId: "requests[0].response.id", },
+                        payload: finalizedPayload,
+                    },
+                ],
+            };
+        }
         case "project.settings-set":
             return {
                 method: "PUT",

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

@@ -38,6 +38,7 @@ export interface FixtureDiscoveryResult {
 export interface DoctorEnvironment {
     projectKey?: string;
     dssVersion?: string;
+    dssApiVersion?: string;
     instanceTime?: string;
     integrationFlags: {
         mutating: boolean;
@@ -48,6 +49,15 @@ export interface DoctorEnvironment {
         apiServices: boolean;
     };
 }
+/**
+ * Server provenance captured from documented response headers on the public
+ * project-list connectivity call. Null entries mean the header was absent.
+ */
+export interface DoctorVersionInfo {
+    dssVersion: string | null;
+    dssApiVersion: string | null;
+    instanceTime: string | null;
+}
 export interface DoctorResult {
     ok: boolean;
     checks: DoctorCheck[];
@@ -66,7 +76,7 @@ export interface DoctorResult {
 export declare function errorDetails(error: unknown): Record<string, unknown>;
 export declare function firstStringField(items: unknown[] | undefined, fields: string[]): string | null;
 export declare function integrationFlag(name: string): boolean;
-export declare function doctorEnvironment(projectKey?: string): DoctorEnvironment;
+export declare function doctorEnvironment(projectKey?: string, versionInfo?: DoctorVersionInfo): DoctorEnvironment;
 export declare function permissionStatusForError(error: unknown): PermissionStatus;
 export declare function probeDoctorPermission(probe: () => Promise<unknown>): Promise<{
     status: PermissionStatus;
@@ -96,7 +106,7 @@ export declare function firstSafeJupyterNotebook(items: unknown[]): {
     unsafe: FixtureReject[];
 };
 export declare function discoverFixtureReport(client: DataikuClient, projectKey: string, flags: Record<string, string | boolean>): Promise<FixtureDiscoveryResult>;
-export declare function doctorCapabilities(client: DataikuClient, projectKey: string | undefined, accessibleProjects: unknown[] | undefined, flags: Record<string, string | boolean>): Promise<Pick<DoctorResult, "permissions" | "permissionDetails" | "fixtures" | "environment">>;
+export declare function doctorCapabilities(client: DataikuClient, projectKey: string | undefined, accessibleProjects: unknown[] | undefined, flags: Record<string, string | boolean>, versionInfo?: DoctorVersionInfo): Promise<Pick<DoctorResult, "permissions" | "permissionDetails" | "fixtures" | "environment">>;
 export declare function runDoctor(flags: Record<string, string | boolean>): Promise<{
     result: DoctorResult;
     exitCode: number;

package/dist/src/cli/doctor.js

@@ -1,5 +1,6 @@
 import { DataikuClient, } from "../client.js";
 import { DataikuError, } from "../errors.js";
+import { ProjectSummaryArraySchema, safeParseSchema, } from "../schemas.js";
 import { num, splitCsvFlag, stringField, } from "./coerce.js";
 import { currentCommandContext, resolveCredentials, } from "./runtime.js";
 import { UsageError, } from "./usage.js";
@@ -31,9 +32,12 @@ export function integrationFlag(name) {
     const value = process.env[name];
     return value === "1" || value?.toLowerCase() === "true";
 }
-export function doctorEnvironment(projectKey) {
+export function doctorEnvironment(projectKey, versionInfo) {
     return {
         ...(projectKey ? { projectKey, } : {}),
+        ...(versionInfo?.dssVersion ? { dssVersion: versionInfo.dssVersion, } : {}),
+        ...(versionInfo?.dssApiVersion ? { dssApiVersion: versionInfo.dssApiVersion, } : {}),
+        ...(versionInfo?.instanceTime ? { instanceTime: versionInfo.instanceTime, } : {}),
         integrationFlags: {
             mutating: integrationFlag("RUN_DATAIKU_INTEGRATION_MUTATING"),
             adminMutating: integrationFlag("RUN_DATAIKU_ADMIN_MUTATING"),
@@ -174,7 +178,7 @@ export async function discoverFixtureReport(client, projectKey, flags) {
         },
     };
 }
-export async function doctorCapabilities(client, projectKey, accessibleProjects, flags) {
+export async function doctorCapabilities(client, projectKey, accessibleProjects, flags, versionInfo) {
     const probeProjectKey = projectKey ?? firstStringField(accessibleProjects, ["projectKey",])
         ?? undefined;
     const probes = {
@@ -210,7 +214,7 @@ export async function doctorCapabilities(client, projectKey, accessibleProjects,
     const capabilityResult = {
         permissions,
         ...(Object.keys(permissionDetails).length > 0 ? { permissionDetails, } : {}),
-        environment: doctorEnvironment(projectKey),
+        environment: doctorEnvironment(projectKey, versionInfo),
     };
     if (flags["fast"] !== true && probeProjectKey) {
         try {
@@ -255,6 +259,7 @@ export async function runDoctor(flags) {
             : "Missing Dataiku URL and/or API key. Set DATAIKU_URL/DATAIKU_API_KEY or pass --url/--api-key.",
     });
     let accessibleProjects;
+    let environmentVersion;
     if (credentialsOk) {
         const requestTimeoutMs = num(flags["request-timeout"], "--request-timeout");
         const retryMaxAttempts = num(flags["retries"], "--retries");
@@ -269,14 +274,40 @@ export async function runDoctor(flags) {
             caCertPath,
         });
         try {
-            const projects = await client.projects.list();
-            accessibleProjects = projects;
-            checks.push({
-                name: "connectivity",
-                ok: true,
-                message: "Connected to DSS and listed accessible projects.",
-                details: { projectCount: projects.length, },
-            });
+            const projects = await client.getWithMetadata("/public/api/projects/");
+            // Documented headers on the public project-list call populate the
+            // optional environment fields; absent headers stay absent. Header
+            // provenance is independent of the body being well-formed.
+            environmentVersion = {
+                dssVersion: projects.meta.dssVersion,
+                dssApiVersion: projects.meta.dssApiVersion,
+                instanceTime: projects.meta.date,
+            };
+            // A reachable endpoint that answers with something other than a
+            // project list is not working connectivity: the body never becomes
+            // capability input, so probes cannot iterate a non-array.
+            const parsed = safeParseSchema(ProjectSummaryArraySchema, projects.data);
+            if (parsed.success) {
+                accessibleProjects = parsed.data;
+                checks.push({
+                    name: "connectivity",
+                    ok: true,
+                    message: "Connected to DSS and listed accessible projects.",
+                    details: { projectCount: parsed.data.length, },
+                });
+            }
+            else {
+                checks.push({
+                    name: "connectivity",
+                    ok: false,
+                    message: "Connected to DSS but the project list response was not a project list.",
+                    details: {
+                        reason: "invalid_project_list",
+                        errorCount: parsed.errors.length,
+                        errors: parsed.errors.slice(0, 5),
+                    },
+                });
+            }
         }
         catch (error) {
             checks.push({
@@ -323,8 +354,8 @@ export async function runDoctor(flags) {
             tlsRejectUnauthorized,
             caCertPath,
         });
-        result.environment = doctorEnvironment(projectKey);
-        Object.assign(result, await doctorCapabilities(client, projectKey, accessibleProjects, flags));
+        result.environment = doctorEnvironment(projectKey, environmentVersion);
+        Object.assign(result, await doctorCapabilities(client, projectKey, accessibleProjects, flags, environmentVersion));
     }
     return { result, exitCode: result.ok ? 0 : 2, };
 }

package/dist/src/cli/flags.js

@@ -96,11 +96,13 @@ export const VALUE_FLAGS = new Set([
     "env-version",
     "expect-hash",
     "expect-project-incarnation",
+    "expected",
     "expect-version",
     "data-file",
     "database",
     "dataset",
     "file",
+    "file-name",
     "file-type",
     "env",
     "install-core-packages",

package/dist/src/cli/helpers/cleanup.js

@@ -4,7 +4,7 @@ export function projectArg(projectKey) {
 }
 export function cleanupLedgerEntry(resource, action, args, flags, result, projectKey) {
     if (!(action.startsWith("create") || action === "clone" || action === "duplicate"
-        || action === "upload"))
+        || action === "import" || action === "upload"))
         return undefined;
     const record = resultRecord(result);
     if (record.skipped !== undefined)
@@ -190,6 +190,35 @@ export function cleanupLedgerEntry(resource, action, args, flags, result, projec
                 path: args[1],
                 cleanup: { argv: ["folder", "delete-file", args[0], args[1], ...withProject,], },
             };
+        case "project.import": {
+            const usedProjectKey = stringField(record, ["usedProjectKey",]);
+            const recordedIncarnation = stringField(record, ["projectIncarnationHash",]);
+            const boundIncarnation = recordedIncarnation
+                && /^[0-9a-f]{64}$/.test(recordedIncarnation)
+                ? recordedIncarnation
+                : undefined;
+            // Only a verified success may produce a cleanup entry, and it must
+            // bind the concrete landed project incarnation: replaying an
+            // unbound delete could remove a replacement project that reused the
+            // key. Never emit legacy/unbound project entries.
+            if (!usedProjectKey || !boundIncarnation)
+                return undefined;
+            return {
+                ...base,
+                projectKey: usedProjectKey,
+                name: usedProjectKey,
+                cleanup: {
+                    argv: [
+                        "project",
+                        "delete",
+                        usedProjectKey,
+                        "--if-exists",
+                        "--expect-project-incarnation",
+                        boundIncarnation,
+                    ],
+                },
+            };
+        }
         case "app.create-instance":
         case "app.create-successor-instance": {
             const targetKey = stringField(record, ["projectKey", "targetProjectKey",]);

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

@@ -21,7 +21,8 @@ export declare function commandFailureExitCode(result: unknown): number | undefi
  * Stable error code for a command-level failure report. A failed synchronous
  * assertion (exit 4) is a distinct outcome from a failed long-running remote
  * operation (also exit 4), so agents must never see `long_running_failure`
- * for a result that finished synchronously with `unchanged: false`.
+ * for a result that finished synchronously with `unchanged: false` or
+ * `satisfied: false`.
  */
 export declare function commandFailureCode(result: unknown, exitCode: number): StableErrorCode;
 export declare class CommandResultFailure extends Error {
@@ -44,6 +45,7 @@ export declare function planResult(resource: string, action: string, options: {
     payload?: unknown;
     localWrites?: unknown;
     plannedAndDryRun?: boolean;
+    requests?: unknown;
     wait?: unknown;
 }): Record<string, unknown>;
 export declare function encodedProjectEndpoint(client: DataikuClient, projectKey: string | undefined, suffix: string): string;

package/dist/src/cli/output.js

@@ -87,10 +87,10 @@ export function isFailedWaitResult(result) {
         && (typeof record.state === "string" || typeof record.outcome === "string");
 }
 export function isAssertionFailureResult(result) {
-    return result !== null
-        && typeof result === "object"
-        && !Array.isArray(result)
-        && result.unchanged === false;
+    if (result === null || typeof result !== "object" || Array.isArray(result))
+        return false;
+    const record = result;
+    return record.unchanged === false || record.satisfied === false;
 }
 function isNestedAssertionFailureResult(result) {
     if (result === null || typeof result !== "object" || Array.isArray(result))
@@ -121,7 +121,8 @@ export function commandFailureExitCode(result) {
  * Stable error code for a command-level failure report. A failed synchronous
  * assertion (exit 4) is a distinct outcome from a failed long-running remote
  * operation (also exit 4), so agents must never see `long_running_failure`
- * for a result that finished synchronously with `unchanged: false`.
+ * for a result that finished synchronously with `unchanged: false` or
+ * `satisfied: false`.
  */
 export function commandFailureCode(result, exitCode) {
     if (isAssertionFailureResult(result) || isNestedAssertionFailureResult(result)) {
@@ -150,7 +151,10 @@ export function commandFailureMessage(result) {
         return `Command completed with failed long-running result${state ? `: ${state}` : ""}.`;
     }
     if (isAssertionFailureResult(result)) {
-        return "Command completed with failed assertion result.";
+        const record = result;
+        return record.unchanged === false
+            ? "Command completed with failed assertion result."
+            : "Command completed with unsatisfied assertion result.";
     }
     if (isNestedAssertionFailureResult(result)) {
         return "Command completed with nested failed assertion result.";
@@ -188,6 +192,7 @@ export function planResult(resource, action, options) {
         ...(options.endpoint ? { endpoint: options.endpoint, } : {}),
         ...(options.payload !== undefined ? { payload: options.payload, } : {}),
         ...(options.localWrites !== undefined ? { localWrites: options.localWrites, } : {}),
+        ...(options.requests !== undefined ? { requests: options.requests, } : {}),
         ...(options.wait !== undefined ? { wait: options.wait, } : {}),
         idempotency: options.idempotency,
         async: options.asyncKind,

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

@@ -1,5 +1,6 @@
 import type { DataikuClient } from "../client.js";
 export type CommandHandler = (client: DataikuClient, args: string[], flags: Record<string, string | boolean>) => Promise<unknown>;
+export type LocalCommandHandler = (args: string[], flags: Record<string, string | boolean>) => Promise<unknown>;
 export interface CommandPayloadSchema {
     stdin?: boolean;
     dataFlag?: boolean;
@@ -19,6 +20,7 @@ export interface CommandRegistryOverride {
 }
 export interface CommandMeta extends CommandRegistryOverride {
     handler: CommandHandler;
+    localHandler?: LocalCommandHandler;
     usage: string;
     description?: string;
     examples?: string[];

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

@@ -1,14 +1,56 @@
 export declare function findPackageRoot(): string | undefined;
 export declare function packageVersion(packageRoot: string | undefined): string;
 export declare function gitDirectory(packageRoot: string): string;
+export declare function isFullRevision(value: unknown): boolean;
+/**
+ * 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 declare function gitFullRevision(packageRoot: string | undefined): string | undefined;
 export declare function gitRevision(packageRoot: string | undefined): string | undefined;
+export type CliLoadSource = "source" | "dist";
+export type CliRuntime = "bun" | "node";
+export declare function detectLoadSource(modulePath?: string): CliLoadSource;
+export declare function buildMetadataRevision(packageRoot: string | undefined): string | 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 declare function sourceTreeNewerThanBuild(packageRoot: string | undefined): boolean;
+/**
+ * CLI provenance payload. `source` distinguishes a source checkout run from a
+ * published dist run; `runtime` names the executing runtime. `buildRevision`
+ * is only ever claimed by a dist build that carries build metadata — source
+ * execution never claims one. `staleBuild` is true only when the running dist
+ * build revision differs from the checkout or a source input is newer than the
+ * build-completion marker.
+ */
+export interface CliVersionPayload {
+    version: string;
+    gitRevision: string | null;
+    source: CliLoadSource;
+    runtime: CliRuntime;
+    buildRevision: string | null;
+    staleBuild: boolean;
+}
+export declare function detectRuntime(): CliRuntime;
+export declare function buildVersionPayload(input: {
+    packageVersion: string;
+    checkoutRevision: string | undefined;
+    checkoutFullRevision: string | undefined;
+    loadSource: string | undefined;
+    buildRevision: string | undefined;
+    sourceNewerThanBuild?: boolean;
+    runtime: CliRuntime;
+}): CliVersionPayload;
 export declare const PACKAGE_ROOT: string | undefined;
 export declare const CLI_VERSION: string;
 export declare const CLI_GIT_REVISION: string | undefined;
 export declare const AGENT_CONTRACT_VERSION = 2;
 export declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
 export declare const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v2.json";
-export declare function cliVersionResult(): {
-    version: string;
-    gitRevision: string | null;
-};
+export declare function cliVersionResult(): CliVersionPayload;