dataiku-sdk 0.10.0 → 0.11.0

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

@@ -0,0 +1,104 @@
+import { DataikuClient } from "../client.js";
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export type PermissionStatus = "yes" | "no" | "unknown";
+export type DoctorPermissionKey = "canListProjects" | "canReadProject" | "canMutateProject" | "canCreateFolder" | "canRunJobs" | "canCreateScenario" | "canSaveJupyter" | "canMutateConnection";
+export type DoctorPermissions = Record<DoctorPermissionKey, PermissionStatus>;
+export interface DoctorFixtures {
+    defaultDataset: string | null;
+    defaultRecipe: string | null;
+    defaultScenario: string | null;
+    defaultFlowZone: string | null;
+    defaultManagedFolder: string | null;
+    defaultJupyterNotebook: string | null;
+}
+export interface FixtureReject {
+    id?: string;
+    name?: string;
+    type?: string;
+    reason: string;
+}
+export interface FixtureDiscoveryResult {
+    projectKey: string;
+    allowTypes: string[];
+    fixtures: DoctorFixtures;
+    safeDataset: Record<string, unknown> | null;
+    safeManagedFolder: Record<string, unknown> | null;
+    safeJupyterNotebook: Record<string, unknown> | null;
+    unsafe: {
+        datasets: FixtureReject[];
+        managedFolders: FixtureReject[];
+        jupyterNotebooks: FixtureReject[];
+    };
+}
+export interface DoctorEnvironment {
+    projectKey?: string;
+    dssVersion?: string;
+    instanceTime?: string;
+    integrationFlags: {
+        mutating: boolean;
+        adminMutating: boolean;
+        variables: boolean;
+        sqlLive: boolean;
+        bundles: boolean;
+        apiServices: boolean;
+    };
+}
+export interface DoctorResult {
+    ok: boolean;
+    checks: DoctorCheck[];
+    context: {
+        hasUrl: boolean;
+        hasApiKey: boolean;
+        projectKey?: string;
+        tlsVerify: "strict" | "disabled";
+        caCert: "default" | "custom";
+    };
+    permissions?: DoctorPermissions;
+    permissionDetails?: Partial<Record<DoctorPermissionKey, Record<string, unknown>>>;
+    fixtures?: DoctorFixtures;
+    environment?: DoctorEnvironment;
+}
+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 permissionStatusForError(error: unknown): PermissionStatus;
+export declare function probeDoctorPermission(probe: () => Promise<unknown>): Promise<{
+    status: PermissionStatus;
+    details?: Record<string, unknown>;
+}>;
+export declare function probeReadOnlyPrerequisiteForMutation(probe: () => Promise<unknown>, readAction: string): Promise<{
+    status: PermissionStatus;
+    details?: Record<string, unknown>;
+}>;
+export declare function missingProjectPermission(): {
+    status: PermissionStatus;
+    details: Record<string, unknown>;
+};
+export declare function recordsFromUnknownArray(items: unknown[]): Array<Record<string, unknown>>;
+export declare function doctorFixturesFromLists(datasets: unknown[], recipes: unknown[], scenarios: unknown[], flowZones: unknown[], folders: unknown[], jupyterNotebooks: unknown[]): DoctorFixtures;
+export declare function discoverDoctorFixtures(client: DataikuClient, projectKey: string): Promise<DoctorFixtures>;
+export declare const DEFAULT_FIXTURE_ALLOW_TYPES: string[];
+export declare function fixtureAllowTypes(flags: Record<string, string | boolean>): string[];
+export declare function isAllowedFixtureType(type: string | undefined, allowTypes: string[]): boolean;
+export declare function fixtureReject(record: Record<string, unknown>, reason: string): FixtureReject;
+export declare function firstSafeTypedFixture(items: unknown[], allowTypes: string[]): {
+    safe: Record<string, unknown> | null;
+    unsafe: FixtureReject[];
+};
+export declare function firstSafeJupyterNotebook(items: unknown[]): {
+    safe: Record<string, unknown> | null;
+    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 runDoctor(flags: Record<string, string | boolean>): Promise<{
+    result: DoctorResult;
+    exitCode: number;
+}>;
+export declare function runFixtures(flags: Record<string, string | boolean>): Promise<FixtureDiscoveryResult>;

package/dist/src/cli/doctor.js

@@ -0,0 +1,356 @@
+import { DataikuClient, } from "../client.js";
+import { DataikuError, } from "../errors.js";
+import { num, splitCsvFlag, stringField, } from "./coerce.js";
+import { currentCommandContext, resolveCredentials, } from "./runtime.js";
+import { UsageError, } from "./usage.js";
+export function errorDetails(error) {
+    if (error instanceof DataikuError) {
+        return {
+            category: error.category,
+            retryable: error.retryable,
+            status: error.status,
+            statusText: error.statusText,
+        };
+    }
+    return { message: error instanceof Error ? error.message : String(error), };
+}
+export function firstStringField(items, fields) {
+    for (const item of items ?? []) {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const record = item;
+        for (const field of fields) {
+            const value = record[field];
+            if (typeof value === "string" && value.trim().length > 0)
+                return value;
+        }
+    }
+    return null;
+}
+export function integrationFlag(name) {
+    const value = process.env[name];
+    return value === "1" || value?.toLowerCase() === "true";
+}
+export function doctorEnvironment(projectKey) {
+    return {
+        ...(projectKey ? { projectKey, } : {}),
+        integrationFlags: {
+            mutating: integrationFlag("RUN_DATAIKU_INTEGRATION_MUTATING"),
+            adminMutating: integrationFlag("RUN_DATAIKU_ADMIN_MUTATING"),
+            variables: integrationFlag("RUN_DATAIKU_INTEGRATION_VARIABLES"),
+            sqlLive: integrationFlag("RUN_DATAIKU_SQL_LIVE"),
+            bundles: integrationFlag("RUN_DATAIKU_INTEGRATION_BUNDLES"),
+            apiServices: integrationFlag("RUN_DATAIKU_INTEGRATION_API_SERVICES"),
+        },
+    };
+}
+export function permissionStatusForError(error) {
+    if (error instanceof DataikuError) {
+        if (error.status === 401 || error.status === 403 || error.status === 404)
+            return "no";
+        if (error.status === 0 || error.status >= 500 || error.category === "transient")
+            return "unknown";
+        if (error.category === "forbidden" || error.category === "not_found")
+            return "no";
+        return "unknown";
+    }
+    return "unknown";
+}
+export async function probeDoctorPermission(probe) {
+    try {
+        await probe();
+        return { status: "yes", };
+    }
+    catch (error) {
+        return { status: permissionStatusForError(error), details: errorDetails(error), };
+    }
+}
+export async function probeReadOnlyPrerequisiteForMutation(probe, readAction) {
+    const readProbe = await probeDoctorPermission(probe);
+    if (readProbe.status !== "yes")
+        return readProbe;
+    return {
+        status: "unknown",
+        details: {
+            reason: "mutation capability was not verified because doctor capabilities are read-only",
+            readAction,
+            readStatus: "yes",
+        },
+    };
+}
+export function missingProjectPermission() {
+    return {
+        status: "unknown",
+        details: { reason: "projectKey is required for this probe", },
+    };
+}
+export function recordsFromUnknownArray(items) {
+    return items.filter((item) => item !== null && typeof item === "object" && !Array.isArray(item));
+}
+export function doctorFixturesFromLists(datasets, recipes, scenarios, flowZones, folders, jupyterNotebooks) {
+    return {
+        defaultDataset: firstStringField(datasets, ["name",]),
+        defaultRecipe: firstStringField(recipes, ["name",]),
+        defaultScenario: firstStringField(scenarios, ["id",]),
+        defaultFlowZone: firstStringField(flowZones, ["id",]),
+        defaultManagedFolder: firstStringField(folders, ["id",]),
+        defaultJupyterNotebook: firstStringField(jupyterNotebooks, ["name",]),
+    };
+}
+export async function discoverDoctorFixtures(client, projectKey) {
+    const [datasets, recipes, scenarios, flowZones, folders, jupyterNotebooks,] = await Promise.all([
+        client.datasets.list(projectKey),
+        client.recipes.list(projectKey),
+        client.scenarios.list(projectKey),
+        client.flowZones.list(projectKey),
+        client.folders.list(projectKey),
+        client.notebooks.listJupyter(projectKey),
+    ]);
+    return doctorFixturesFromLists(datasets, recipes, scenarios, flowZones, folders, jupyterNotebooks);
+}
+export const DEFAULT_FIXTURE_ALLOW_TYPES = ["Filesystem", "Inline",];
+export function fixtureAllowTypes(flags) {
+    const configured = splitCsvFlag(flags["allow-types"]);
+    return configured.length > 0 ? configured : DEFAULT_FIXTURE_ALLOW_TYPES;
+}
+export function isAllowedFixtureType(type, allowTypes) {
+    if (!type)
+        return false;
+    const normalized = type.trim().toLowerCase();
+    return allowTypes.some((allowed) => allowed.trim().toLowerCase() === normalized);
+}
+export function fixtureReject(record, reason) {
+    return {
+        ...(stringField(record, ["id",]) ? { id: stringField(record, ["id",]), } : {}),
+        ...(stringField(record, ["name",]) ? { name: stringField(record, ["name",]), } : {}),
+        ...(stringField(record, ["type",]) ? { type: stringField(record, ["type",]), } : {}),
+        reason,
+    };
+}
+export function firstSafeTypedFixture(items, allowTypes) {
+    const unsafe = [];
+    for (const record of recordsFromUnknownArray(items)) {
+        const type = stringField(record, ["type",]);
+        if (isAllowedFixtureType(type, allowTypes))
+            return { safe: record, unsafe, };
+        unsafe.push(fixtureReject(record, `type=${type ?? "missing"}`));
+    }
+    return { safe: null, unsafe, };
+}
+export function firstSafeJupyterNotebook(items) {
+    const unsafe = [];
+    for (const record of recordsFromUnknownArray(items)) {
+        const name = stringField(record, ["name",]);
+        if (name && !name.startsWith("_"))
+            return { safe: record, unsafe, };
+        unsafe.push(fixtureReject(record, name ? "name starts with _" : "missing name"));
+    }
+    return { safe: null, unsafe, };
+}
+export async function discoverFixtureReport(client, projectKey, flags) {
+    const allowTypes = fixtureAllowTypes(flags);
+    const [datasets, recipes, scenarios, flowZones, folders, jupyterNotebooks,] = await Promise.all([
+        client.datasets.list(projectKey),
+        client.recipes.list(projectKey),
+        client.scenarios.list(projectKey),
+        client.flowZones.list(projectKey),
+        client.folders.list(projectKey),
+        client.notebooks.listJupyter(projectKey),
+    ]);
+    const dataset = firstSafeTypedFixture(datasets, allowTypes);
+    const folder = firstSafeTypedFixture(folders, allowTypes);
+    const notebook = firstSafeJupyterNotebook(jupyterNotebooks);
+    return {
+        projectKey,
+        allowTypes,
+        fixtures: doctorFixturesFromLists(datasets, recipes, scenarios, flowZones, folders, jupyterNotebooks),
+        safeDataset: dataset.safe,
+        safeManagedFolder: folder.safe,
+        safeJupyterNotebook: notebook.safe,
+        unsafe: {
+            datasets: dataset.unsafe,
+            managedFolders: folder.unsafe,
+            jupyterNotebooks: notebook.unsafe,
+        },
+    };
+}
+export async function doctorCapabilities(client, projectKey, accessibleProjects, flags) {
+    const probeProjectKey = projectKey ?? firstStringField(accessibleProjects, ["projectKey",])
+        ?? undefined;
+    const probes = {
+        canListProjects: () => probeDoctorPermission(async () => accessibleProjects ?? await client.projects.list()),
+        canReadProject: () => probeProjectKey
+            ? probeDoctorPermission(() => client.projects.get(probeProjectKey))
+            : Promise.resolve(missingProjectPermission()),
+        canMutateProject: () => probeProjectKey
+            ? probeReadOnlyPrerequisiteForMutation(() => client.variables.get(probeProjectKey), "variables.get")
+            : Promise.resolve(missingProjectPermission()),
+        canCreateFolder: () => probeProjectKey
+            ? probeReadOnlyPrerequisiteForMutation(() => client.folders.list(probeProjectKey), "folders.list")
+            : Promise.resolve(missingProjectPermission()),
+        canRunJobs: () => probeProjectKey
+            ? probeReadOnlyPrerequisiteForMutation(() => client.jobs.list(probeProjectKey), "jobs.list")
+            : Promise.resolve(missingProjectPermission()),
+        canCreateScenario: () => probeProjectKey
+            ? probeReadOnlyPrerequisiteForMutation(() => client.scenarios.list(probeProjectKey), "scenarios.list")
+            : Promise.resolve(missingProjectPermission()),
+        canSaveJupyter: () => probeProjectKey
+            ? probeReadOnlyPrerequisiteForMutation(() => client.notebooks.listJupyter(probeProjectKey), "notebooks.listJupyter")
+            : Promise.resolve(missingProjectPermission()),
+        canMutateConnection: () => probeReadOnlyPrerequisiteForMutation(() => client.connections.list(), "connections.list"),
+    };
+    const permissions = {};
+    const permissionDetails = {};
+    for (const key of Object.keys(probes)) {
+        const probe = await probes[key]();
+        permissions[key] = probe.status;
+        if (probe.details)
+            permissionDetails[key] = probe.details;
+    }
+    const capabilityResult = {
+        permissions,
+        ...(Object.keys(permissionDetails).length > 0 ? { permissionDetails, } : {}),
+        environment: doctorEnvironment(projectKey),
+    };
+    if (flags["fast"] !== true && probeProjectKey) {
+        try {
+            capabilityResult.fixtures = await discoverDoctorFixtures(client, probeProjectKey);
+        }
+        catch (error) {
+            capabilityResult.fixtures = {
+                defaultDataset: null,
+                defaultRecipe: null,
+                defaultScenario: null,
+                defaultFlowZone: null,
+                defaultManagedFolder: null,
+                defaultJupyterNotebook: null,
+            };
+            capabilityResult.permissionDetails = {
+                ...capabilityResult.permissionDetails,
+                canReadProject: {
+                    ...capabilityResult.permissionDetails?.canReadProject,
+                    fixtureDiscovery: errorDetails(error),
+                },
+            };
+        }
+    }
+    return capabilityResult;
+}
+export async function runDoctor(flags) {
+    const { url, apiKey, projectKey, tlsRejectUnauthorized, caCertPath, } = resolveCredentials(flags);
+    const checks = [];
+    const context = {
+        hasUrl: url.trim().length > 0,
+        hasApiKey: apiKey.trim().length > 0,
+        ...(projectKey ? { projectKey, } : {}),
+        tlsVerify: tlsRejectUnauthorized === false ? "disabled" : "strict",
+        caCert: caCertPath ? "custom" : "default",
+    };
+    const credentialsOk = context.hasUrl && context.hasApiKey;
+    checks.push({
+        name: "credentials_present",
+        ok: credentialsOk,
+        message: credentialsOk
+            ? "Dataiku URL and API key are configured."
+            : "Missing Dataiku URL and/or API key. Set DATAIKU_URL/DATAIKU_API_KEY or pass --url/--api-key.",
+    });
+    let accessibleProjects;
+    if (credentialsOk) {
+        const requestTimeoutMs = num(flags["request-timeout"]);
+        const retryMaxAttempts = num(flags["retries"]);
+        const client = new DataikuClient({
+            url,
+            apiKey,
+            projectKey,
+            verbose: flags["verbose"] === true,
+            requestTimeoutMs,
+            retryMaxAttempts,
+            tlsRejectUnauthorized,
+            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, },
+            });
+        }
+        catch (error) {
+            checks.push({
+                name: "connectivity",
+                ok: false,
+                message: "Could not list accessible projects.",
+                details: errorDetails(error),
+            });
+        }
+        if (projectKey) {
+            try {
+                const project = await client.projects.get(projectKey);
+                checks.push({
+                    name: "default_project",
+                    ok: true,
+                    message: `Project ${projectKey} is accessible.`,
+                    details: {
+                        projectKey,
+                        name: typeof project.name === "string" ? project.name : undefined,
+                    },
+                });
+            }
+            catch (error) {
+                checks.push({
+                    name: "default_project",
+                    ok: false,
+                    message: `Project ${projectKey} is not accessible.`,
+                    details: errorDetails(error),
+                });
+            }
+        }
+    }
+    const result = { ok: checks.every((check) => check.ok), checks, context, };
+    if (flags["capabilities"] === true && credentialsOk) {
+        const requestTimeoutMs = num(flags["request-timeout"]);
+        const retryMaxAttempts = num(flags["retries"]) ?? 1;
+        const client = new DataikuClient({
+            url,
+            apiKey,
+            projectKey,
+            verbose: flags["verbose"] === true,
+            requestTimeoutMs,
+            retryMaxAttempts,
+            tlsRejectUnauthorized,
+            caCertPath,
+        });
+        result.environment = doctorEnvironment(projectKey);
+        Object.assign(result, await doctorCapabilities(client, projectKey, accessibleProjects, flags));
+    }
+    return { result, exitCode: result.ok ? 0 : 2, };
+}
+export async function runFixtures(flags) {
+    const { url, apiKey, projectKey, tlsRejectUnauthorized, caCertPath, } = resolveCredentials(flags);
+    if (!url) {
+        throw new UsageError("Missing Dataiku URL. Set DATAIKU_URL or pass --url.", "missing_required_flag");
+    }
+    if (!apiKey) {
+        throw new UsageError("Missing API key. Set DATAIKU_API_KEY or pass --api-key.", "missing_required_flag");
+    }
+    if (!projectKey) {
+        throw new UsageError("Missing project key. Set DATAIKU_PROJECT_KEY or pass --project-key.", "missing_required_flag");
+    }
+    currentCommandContext.projectKey = projectKey;
+    const requestTimeoutMs = num(flags["request-timeout"]);
+    const retryMaxAttempts = num(flags["retries"]) ?? 1;
+    const client = new DataikuClient({
+        url,
+        apiKey,
+        projectKey,
+        verbose: flags["verbose"] === true,
+        requestTimeoutMs,
+        retryMaxAttempts,
+        tlsRejectUnauthorized,
+        caCertPath,
+    });
+    return discoverFixtureReport(client, projectKey, flags);
+}

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

@@ -0,0 +1,2 @@
+export declare function dataikuEnvironmentEnabled(): boolean;
+export declare function loadEnvFile(): void;

package/dist/src/cli/env.js

@@ -0,0 +1,37 @@
+import { readFileSync, } from "node:fs";
+import { dirname, resolve, } from "node:path";
+import { fileURLToPath, } from "node:url";
+export function dataikuEnvironmentEnabled() {
+    return process.env.DATAIKU_DISABLE_ENV !== "1";
+}
+export function loadEnvFile() {
+    if (!dataikuEnvironmentEnabled())
+        return;
+    // The invocation cwd takes precedence over the CLI install/root directory, so a
+    // project-local .env where `dss` is invoked overrides defaults shipped beside the
+    // CLI. First writer wins below, so cwd must be listed first.
+    const dirs = [
+        process.cwd(),
+        resolve(dirname(fileURLToPath(import.meta.url)), "..", ".."),
+    ];
+    for (const dir of dirs) {
+        try {
+            const content = readFileSync(resolve(dir, ".env"), "utf-8");
+            for (const line of content.split("\n")) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith("#"))
+                    continue;
+                const eq = trimmed.indexOf("=");
+                if (eq === -1)
+                    continue;
+                const key = trimmed.slice(0, eq).trim();
+                const val = trimmed.slice(eq + 1).trim().replace(/^['"]|['"]$/g, "");
+                if (!process.env[key])
+                    process.env[key] = val;
+            }
+        }
+        catch {
+            // no .env file — fine
+        }
+    }
+}

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

@@ -0,0 +1,16 @@
+export declare const BOOLEAN_FLAGS: Set<string>;
+export declare const SHORT_FLAGS: Record<string, string>;
+/** Long-flag aliases: these are normalized to the canonical name in parseArgs. */
+export declare const FLAG_ALIASES: Record<string, string>;
+export declare const VALUE_FLAGS: Set<string>;
+export declare const REPEATABLE_VALUE_FLAGS: Set<string>;
+export declare const KNOWN_LONG_FLAGS: Set<string>;
+export declare function normalizeLongFlag(rawFlagName: string): string;
+export declare function isNegativeNumberToken(value: string): boolean;
+export declare function requireFlagValue(flagLabel: string, next: string | undefined): string;
+export declare function setParsedFlagValue(flags: Record<string, string | boolean>, flagName: string, value: string): void;
+export interface ParsedArgs {
+    positional: string[];
+    flags: Record<string, string | boolean>;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;