dataiku-sdk 2.0.0 → 3.1.0

package/dist/src/resources/scenarios.d.ts

@@ -31,6 +31,25 @@ export interface ScenarioUpdateResult extends ScenarioUpdatePreview {
     verified: true;
     mismatches: [];
 }
+export interface ScenarioScriptRunCleanup {
+    status: "deleted" | "kept" | "failed";
+    error?: string;
+}
+/** Cleanup failure carried on errors thrown from {@link ScenariosResource.runScript}. */
+export interface ScenarioScriptRunCleanupFailure {
+    scenarioId: string;
+    error: string;
+}
+/**
+ * Wraps a primary code-run failure so the original error (and its taxonomy:
+ * category, exit-code semantics) stays intact while the concurrent throwaway
+ * cleanup failure remains observable via {@link cleanupFailure}.
+ */
+export declare class ScenarioScriptRunWithCleanupFailureError extends Error {
+    readonly cause: unknown;
+    readonly cleanupFailure: ScenarioScriptRunCleanupFailure;
+    constructor(cause: unknown, cleanupFailure: ScenarioScriptRunCleanupFailure);
+}
 export interface ScenarioScriptRunResult {
     scenarioId: string;
     runId: string;
@@ -43,6 +62,10 @@ export interface ScenarioScriptRunResult {
     logTruncated: boolean;
     maxLogBytes: number;
     envName?: string;
+    timedOut?: boolean;
+    timeoutMs?: number;
+    /** Observable throwaway-scenario cleanup outcome; never silently swallowed here. */
+    cleanup: ScenarioScriptRunCleanup;
 }
 export declare function normalizeScenarioUpdateData(data: Record<string, unknown>): {
     normalizedData: Record<string, unknown>;
@@ -95,4 +118,11 @@ export declare class ScenariosResource extends BaseResource {
         keepScenario?: boolean;
         maxLogBytes?: number;
     }): Promise<ScenarioScriptRunResult>;
+    /**
+     * Delete the throwaway scenario at the end of a code run, or report the
+     * explicit keep outcome. Never throws: delete failures are surfaced in the
+     * returned cleanup outcome instead of being swallowed. A 404 is idempotent
+     * success — the scenario is already gone.
+     */
+    private removeThrowawayScenario;
 }

package/dist/src/resources/scenarios.js

@@ -12,6 +12,21 @@ export const SCENARIO_CANONICAL_EDITABLE_FIELDS = [
     "active",
     "name",
 ];
+/**
+ * Wraps a primary code-run failure so the original error (and its taxonomy:
+ * category, exit-code semantics) stays intact while the concurrent throwaway
+ * cleanup failure remains observable via {@link cleanupFailure}.
+ */
+export class ScenarioScriptRunWithCleanupFailureError extends Error {
+    cause;
+    cleanupFailure;
+    constructor(cause, cleanupFailure) {
+        super("Code run failed and its throwaway scenario cleanup also failed.");
+        this.cause = cause;
+        this.cleanupFailure = cleanupFailure;
+        this.name = "ScenarioScriptRunWithCleanupFailureError";
+    }
+}
 const DEFAULT_CODE_RUN_MAX_LOG_BYTES = 1_048_576;
 const CODE_RUN_OUTPUT_START = "<<<DSS_CODE_RUN_OUTPUT_b7e3a1>>>";
 const CODE_RUN_OUTPUT_END = "<<<DSS_CODE_RUN_OUTPUT_END_b7e3a1>>>";
@@ -421,6 +436,13 @@ export class ScenariosResource extends BaseResource {
         const adaptivePolling = opts?.pollIntervalMs === undefined;
         const timeout = Math.max(baseIntervalMs, opts?.timeoutMs ?? 120_000);
         const maxLogBytes = Math.max(0, Math.floor(opts?.maxLogBytes ?? DEFAULT_CODE_RUN_MAX_LOG_BYTES));
+        let outcome = "UNKNOWN";
+        let runId = "";
+        let pollCount = 0;
+        let timedOut = false;
+        let log = "";
+        let logTruncated = false;
+        let primaryError;
         try {
             await this.client.post(`/public/api/projects/${pkEnc}/scenarios/`, {
                 id: scenarioId,
@@ -438,12 +460,10 @@ export class ScenariosResource extends BaseResource {
                 throw new DataikuError(500, "Scenario run not started", `Scenario "${scenarioId}" run trigger returned no run id; cannot track the run.`);
             }
             const trigQuery = `triggerId=${encodeURIComponent(triggerId)}&triggerRunId=${encodeURIComponent(triggerRunId)}`;
-            let runId = "";
-            let outcome = "UNKNOWN";
-            let pollCount = 0;
             while (true) {
                 if (Date.now() - startedAt >= timeout) {
                     outcome = "TIMEOUT";
+                    timedOut = true;
                     break;
                 }
                 pollCount += 1;
@@ -465,37 +485,63 @@ export class ScenariosResource extends BaseResource {
                 });
                 await new Promise((r) => setTimeout(r, Math.min(nextDelayMs, Math.max(1, timeout - (Date.now() - startedAt)))));
             }
-            let log = "";
-            let logTruncated = false;
             if (runId && outcome !== "TIMEOUT") {
                 const limitedLog = await this.client.getTextLimited(`${base}/${encodeURIComponent(runId)}/log`, maxLogBytes);
                 log = limitedLog.text;
                 logTruncated = limitedLog.truncated;
             }
-            const output = extractCodeRunOutput(log);
-            return {
-                scenarioId,
-                runId,
-                outcome,
-                success: outcome === "SUCCESS",
-                elapsedMs: Date.now() - startedAt,
-                pollCount,
-                output,
-                log,
-                logTruncated,
-                maxLogBytes,
-                ...(opts?.envName ? { envName: opts.envName, } : {}),
-            };
         }
-        finally {
-            if (opts?.keepScenario !== true) {
-                try {
-                    await this.client.del(base);
-                }
-                catch {
-                    // Best-effort cleanup of the throwaway scenario.
-                }
+        catch (error) {
+            primaryError = error;
+        }
+        const cleanup = await this.removeThrowawayScenario(base, opts?.keepScenario === true);
+        if (primaryError !== undefined) {
+            if (cleanup.status === "failed") {
+                throw new ScenarioScriptRunWithCleanupFailureError(primaryError, {
+                    scenarioId,
+                    error: cleanup.error ?? "unknown cleanup error",
+                });
             }
+            throw primaryError;
+        }
+        const output = extractCodeRunOutput(log);
+        return {
+            scenarioId,
+            runId,
+            outcome,
+            success: outcome === "SUCCESS",
+            elapsedMs: Date.now() - startedAt,
+            pollCount,
+            output,
+            log,
+            logTruncated,
+            maxLogBytes,
+            ...(opts?.envName ? { envName: opts.envName, } : {}),
+            ...(timedOut ? { timedOut: true, timeoutMs: timeout, } : {}),
+            cleanup,
+        };
+    }
+    /**
+     * Delete the throwaway scenario at the end of a code run, or report the
+     * explicit keep outcome. Never throws: delete failures are surfaced in the
+     * returned cleanup outcome instead of being swallowed. A 404 is idempotent
+     * success — the scenario is already gone.
+     */
+    async removeThrowawayScenario(base, keep) {
+        if (keep)
+            return { status: "kept", };
+        try {
+            await this.client.del(base);
+            return { status: "deleted", };
+        }
+        catch (error) {
+            if (error instanceof DataikuError && error.category === "not_found") {
+                return { status: "deleted", };
+            }
+            return {
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            };
         }
     }
 }

package/dist/src/resources/sql.d.ts

@@ -25,6 +25,12 @@ export declare class SqlResource extends BaseResource {
     startQuery(opts: SqlQueryOptions): Promise<SqlQueryResult>;
     /**
      * Stream results of a started query as parsed JSON (array of arrays).
+     *
+     * The result body is buffered under the client's response body limit
+     * (default 50 MiB, `maxResponseBodyBytes`) and the request deadline. A
+     * response exceeding the limit is cancelled and rejected instead of being
+     * parsed — otherwise a collaborator-controlled result set (or a stalled
+     * stream) could exhaust client memory or hang unbounded.
      */
     streamResults(queryId: string): Promise<unknown[][]>;
     /**

package/dist/src/resources/sql.js

@@ -1,6 +1,12 @@
 import { ClientValidationError, DataikuError, } from "../errors.js";
 import { BaseResource, } from "./base.js";
 const UNSUPPORTED_SQL_DATASET_CONNECTION_DETAIL = "neither of sql nor hdfs type";
+/**
+ * Cap on the finish-streaming status text behind the client's response body
+ * limit: the payload is a short status message, so any larger body is a
+ * misbehaving endpoint and must not be buffered further.
+ */
+const MAX_SQL_FINISH_TEXT_BYTES = 1024 * 1024;
 function isUnsupportedSqlDatasetConnectionError(error) {
     if (!(error instanceof DataikuError))
         return false;
@@ -135,10 +141,20 @@ export class SqlResource extends BaseResource {
     }
     /**
      * Stream results of a started query as parsed JSON (array of arrays).
+     *
+     * The result body is buffered under the client's response body limit
+     * (default 50 MiB, `maxResponseBodyBytes`) and the request deadline. A
+     * response exceeding the limit is cancelled and rejected instead of being
+     * parsed — otherwise a collaborator-controlled result set (or a stalled
+     * stream) could exhaust client memory or hang unbounded.
      */
     async streamResults(queryId) {
         const id = encodeURIComponent(queryId);
-        const text = await this.client.getText(`/public/api/sql/queries/${id}/stream?format=json`);
+        const maxBytes = this.client.getMaxResponseBodyBytes();
+        const { text, truncated, } = await this.client.getTextLimited(`/public/api/sql/queries/${id}/stream?format=json`, maxBytes);
+        if (truncated) {
+            throw new DataikuError(0, "Response Too Large", `SQL stream results exceeded the ${maxBytes}-byte response limit and were not parsed.`);
+        }
         return JSON.parse(text);
     }
     /**
@@ -147,7 +163,11 @@ export class SqlResource extends BaseResource {
      */
     async finishStreaming(queryId) {
         const id = encodeURIComponent(queryId);
-        const text = await this.client.getText(`/public/api/sql/queries/${id}/finish-streaming`);
+        const maxBytes = Math.min(this.client.getMaxResponseBodyBytes(), MAX_SQL_FINISH_TEXT_BYTES);
+        const { text, truncated, } = await this.client.getTextLimited(`/public/api/sql/queries/${id}/finish-streaming`, maxBytes);
+        if (truncated) {
+            throw new DataikuError(0, "Response Too Large", `SQL finish-streaming response exceeded the ${maxBytes}-byte response limit.`);
+        }
         if (text.length > 0) {
             throw new Error(`SQL query ${queryId} failed: ${text}`);
         }

package/dist/src/resources/webapps.d.ts

@@ -1,3 +1,4 @@
+import type { FutureWaitResult } from "../schemas.js";
 import { BaseResource } from "./base.js";
 export interface WebappListItem {
     id?: string;
@@ -9,6 +10,20 @@ export interface WebappListItem {
 export interface WebappCreateResult {
     webAppId: string;
 }
+/**
+ * 64-hex SHA-256 hash of the webapp object as last fetched, used as a
+ * non-atomic stale-read guard: the write is refused when the object already
+ * differs at the verification read. DSS exposes no conditional write (no
+ * ETag, no If-Match), so a writer committing between that read and the PUT
+ * is still not detected.
+ */
+export interface WebappUpdateOptions {
+    expectHash?: string;
+}
+export interface WebappWaitOptions {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+}
 export declare class WebappsResource extends BaseResource {
     /** List all webapps in a project. */
     list(projectKey?: string): Promise<WebappListItem[]>;
@@ -16,12 +31,28 @@ export declare class WebappsResource extends BaseResource {
     getSettings(webappId: string, projectKey?: string): Promise<Record<string, unknown>>;
     /** Create a webapp. */
     create(body: Record<string, unknown>, projectKey?: string): Promise<WebappCreateResult>;
-    /** Update one webapp's settings. */
-    updateSettings(webappId: string, body: Record<string, unknown>, projectKey?: string): Promise<Record<string, unknown>>;
+    /**
+     * Update one webapp's settings via GET-merge-PUT. The public API requires
+     * the object passed to a PUT call to have been obtained from a GET call at
+     * the same URL, so the current object is fetched first, the supplied
+     * fields are merged over it (fields absent from `body` are preserved), and
+     * the whole merged object is PUT back.
+     *
+     * With `expectHash` armed, the fresh GET doubles as the stale-read guard:
+     * the stable hash of the fetched object must match, or the write is
+     * refused before any PUT.
+     */
+    updateSettings(webappId: string, body: Record<string, unknown>, projectKey?: string, options?: WebappUpdateOptions): Promise<Record<string, unknown>>;
     /** Stop a webapp backend. */
     stopBackend(webappId: string, projectKey?: string): Promise<void>;
-    /** Start or restart a webapp backend. */
-    startOrRestartBackend(webappId: string, projectKey?: string): Promise<void>;
+    /**
+     * Start or restart a webapp backend. The documented endpoint returns a
+     * reference to a future, which is surfaced as-is; settle it with
+     * {@link restartBackendAndWait} or `client.futures.wait`.
+     */
+    startOrRestartBackend(webappId: string, projectKey?: string): Promise<Record<string, unknown>>;
+    /** Restart a webapp backend and wait for the returned future to settle. */
+    restartBackendAndWait(webappId: string, projectKey?: string, options?: WebappWaitOptions): Promise<FutureWaitResult>;
     /** Get a webapp backend's state. */
     getBackendState(webappId: string, projectKey?: string): Promise<Record<string, unknown>>;
 }

package/dist/src/resources/webapps.js

@@ -1,4 +1,22 @@
+import { ClientValidationError, } from "../errors.js";
+import { deepMerge, } from "../utils/deep-merge.js";
+import { stableHash, } from "../utils/stable-hash.js";
 import { BaseResource, } from "./base.js";
+const EXPECT_HASH_PATTERN = /^[0-9a-fA-F]{64}$/;
+function assertExpectedHash(id, expectHash, current, projectKey) {
+    if (!EXPECT_HASH_PATTERN.test(expectHash)) {
+        throw new ClientValidationError("Expected webapp hash must be a 64-character SHA-256 hex digest.", "validation_failed", "Use the hash value returned by a previous read.", { projectKey, id, });
+    }
+    const actual = stableHash(current);
+    if (actual !== expectHash.toLowerCase()) {
+        throw new ClientValidationError(`The webapp ${JSON.stringify(id)} changed since it was read.`, "validation_failed", "Re-read the webapp settings and retry with the current hash value.", {
+            projectKey,
+            id,
+            expectedHash: expectHash.toLowerCase(),
+            actualHash: actual,
+        });
+    }
+}
 export class WebappsResource extends BaseResource {
     /** List all webapps in a project. */
     async list(projectKey) {
@@ -13,20 +31,51 @@ export class WebappsResource extends BaseResource {
     async create(body, projectKey) {
         return this.client.post(`/public/api/projects/${this.enc(projectKey)}/webapps/`, body);
     }
-    /** Update one webapp's settings. */
-    async updateSettings(webappId, body, projectKey) {
+    /**
+     * Update one webapp's settings via GET-merge-PUT. The public API requires
+     * the object passed to a PUT call to have been obtained from a GET call at
+     * the same URL, so the current object is fetched first, the supplied
+     * fields are merged over it (fields absent from `body` are preserved), and
+     * the whole merged object is PUT back.
+     *
+     * With `expectHash` armed, the fresh GET doubles as the stale-read guard:
+     * the stable hash of the fetched object must match, or the write is
+     * refused before any PUT.
+     */
+    async updateSettings(webappId, body, projectKey, options = {}) {
+        const current = await this.getSettings(webappId, projectKey);
+        if (options.expectHash !== undefined) {
+            assertExpectedHash(webappId, options.expectHash, current, projectKey);
+        }
+        const next = deepMerge(current, body);
         const id = encodeURIComponent(webappId);
-        return this.client.put(`/public/api/projects/${this.enc(projectKey)}/webapps/${id}`, body);
+        return this.client.put(`/public/api/projects/${this.enc(projectKey)}/webapps/${id}`, next);
     }
     /** Stop a webapp backend. */
     async stopBackend(webappId, projectKey) {
         const id = encodeURIComponent(webappId);
         await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/webapps/${id}/backend/actions/stop`, {});
     }
-    /** Start or restart a webapp backend. */
+    /**
+     * Start or restart a webapp backend. The documented endpoint returns a
+     * reference to a future, which is surfaced as-is; settle it with
+     * {@link restartBackendAndWait} or `client.futures.wait`.
+     */
     async startOrRestartBackend(webappId, projectKey) {
         const id = encodeURIComponent(webappId);
-        await this.client.putVoid(`/public/api/projects/${this.enc(projectKey)}/webapps/${id}/backend/actions/restart`, {});
+        return this.client.put(`/public/api/projects/${this.enc(projectKey)}/webapps/${id}/backend/actions/restart`, {});
+    }
+    /** Restart a webapp backend and wait for the returned future to settle. */
+    async restartBackendAndWait(webappId, projectKey, options = {}) {
+        const future = await this.startOrRestartBackend(webappId, projectKey);
+        const jobId = future.jobId;
+        if (typeof jobId !== "string" || jobId.length === 0) {
+            throw new Error("Webapp backend restart did not return a future jobId.");
+        }
+        return this.client.futures.wait(jobId, {
+            pollIntervalMs: options.pollIntervalMs,
+            timeoutMs: options.timeoutMs,
+        });
     }
     /** Get a webapp backend's state. */
     async getBackendState(webappId, projectKey) {

package/dist/src/schemas.d.ts

@@ -3,5 +3,5 @@
  * The types package (packages/types/) owns the TypeBox schema definitions.
  * SDK consumers get everything through this re-export.
  */
-export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";
-export type { BuildMode, CodeEnvActionResult, CodeEnvCreateOptions, CodeEnvDetails, CodeEnvPackageList, CodeEnvSetPackagesOptions, CodeEnvSummary, CodeEnvUpdatePackagesOptions, CodeEnvUsage, CodeEnvWaitOptions, ConnectionSummary, DashboardDetails, DashboardSummary, DataQualityComputeResult, DataQualityProjectStatus, DataQualityRule, DataQualityRuleResult, DataQualityRules, DataQualityStatus, DataQualityStatusByPartition, DataQualityTimeline, DataQualityTimelineEntry, DatasetCreateOptions, DatasetDetails, DatasetSchema, DatasetSummary, FlowMapOptions, FlowZone, FlowZoneCreateOptions, FlowZoneItem, FlowZoneObjectType, FlowZonePosition, FlowZoneUpdateOptions, FolderCreateOptions, FolderDetails, FolderItem, FolderSummary, FutureState, FutureWaitResult, InsightDetails, InsightSummary, JobSummary, JobWaitResult, JupyterCell, JupyterNotebookContent, JupyterNotebookSummary, NotebookSession, ProjectDetails, ProjectGitActionResult, ProjectGitDiffResult, ProjectGitFutureResponse, ProjectGitFutureState, ProjectGitLibraries, ProjectGitLibrary, ProjectGitLogResult, ProjectGitRemote, ProjectGitStatus, ProjectGitTag, ProjectGitTags, ProjectMetadata, ProjectSummary, ProjectVariables, RecipeCreateOptions, RecipeCreateResult, RecipeDetails, RecipeSummary, SafeParseResult, ScenarioDetails, ScenarioStatus, ScenarioStepRun, ScenarioSummary, ScenarioWaitResult, SqlNotebookCell, SqlNotebookContent, SqlNotebookSummary, SqlQueryResponse, SqlQueryResult, SqlQuerySchema, WikiArticleData, WikiArticleMetadata, WikiSettings, WikiTaxonomyNode, } from "../packages/types/src/index.js";
+export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvGetLogOptionsSchema, CodeEnvLogResultSchema, CodeEnvLogSummaryArraySchema, CodeEnvLogSummarySchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdateImagesOptionsSchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";
+export type { BuildMode, CodeEnvActionResult, CodeEnvCreateOptions, CodeEnvDetails, CodeEnvGetLogOptions, CodeEnvLogResult, CodeEnvLogSummary, CodeEnvPackageList, CodeEnvSetPackagesOptions, CodeEnvSummary, CodeEnvUpdateImagesOptions, CodeEnvUpdatePackagesOptions, CodeEnvUsage, CodeEnvVersionForProject, CodeEnvWaitOptions, ConnectionSummary, DashboardDetails, DashboardSummary, DataQualityComputeResult, DataQualityProjectStatus, DataQualityRule, DataQualityRuleResult, DataQualityRules, DataQualityStatus, DataQualityStatusByPartition, DataQualityTimeline, DataQualityTimelineEntry, DatasetCreateOptions, DatasetDetails, DatasetSchema, DatasetSummary, FlowMapOptions, FlowZone, FlowZoneCreateOptions, FlowZoneItem, FlowZoneObjectType, FlowZonePosition, FlowZoneUpdateOptions, FolderCreateOptions, FolderDetails, FolderItem, FolderSummary, FutureState, FutureWaitResult, InsightDetails, InsightSummary, JobSummary, JobWaitResult, JupyterCell, JupyterNotebookContent, JupyterNotebookSummary, NotebookSession, ProjectDetails, ProjectGitActionResult, ProjectGitDiffResult, ProjectGitFutureResponse, ProjectGitFutureState, ProjectGitLibraries, ProjectGitLibrary, ProjectGitLogResult, ProjectGitRemote, ProjectGitStatus, ProjectGitTag, ProjectGitTags, ProjectMetadata, ProjectSummary, ProjectVariables, RecipeCreateOptions, RecipeCreateResult, RecipeDetails, RecipeSummary, SafeParseResult, ScenarioDetails, ScenarioStatus, ScenarioStepRun, ScenarioSummary, ScenarioWaitResult, SqlNotebookCell, SqlNotebookContent, SqlNotebookHistory, SqlNotebookSummary, SqlQueryResponse, SqlQueryResult, SqlQuerySchema, WikiArticleData, WikiArticleMetadata, WikiSettings, WikiTaxonomyNode, } from "../packages/types/src/index.js";

package/dist/src/schemas.js

@@ -3,4 +3,4 @@
  * The types package (packages/types/) owns the TypeBox schema definitions.
  * SDK consumers get everything through this re-export.
  */
-export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";
+export { BuildModeSchema, CodeEnvActionResultSchema, CodeEnvCreateOptionsSchema, CodeEnvDetailsSchema, CodeEnvGetLogOptionsSchema, CodeEnvLogResultSchema, CodeEnvLogSummaryArraySchema, CodeEnvLogSummarySchema, CodeEnvPackageListSchema, CodeEnvSetPackagesOptionsSchema, CodeEnvSummaryArraySchema, CodeEnvSummarySchema, CodeEnvUpdateImagesOptionsSchema, CodeEnvUpdatePackagesOptionsSchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, CodeEnvWaitOptionsSchema, ConnectionSummarySchema, DashboardDetailsSchema, DashboardSummaryArraySchema, DashboardSummarySchema, DataQualityComputeResultSchema, DataQualityProjectStatusSchema, DataQualityRuleArraySchema, DataQualityRuleResultArraySchema, DataQualityRuleResultSchema, DataQualityRuleSchema, DataQualityRulesSchema, DataQualityStatusByPartitionSchema, DataQualityStatusSchema, DataQualityTimelineEntrySchema, DataQualityTimelineSchema, DatasetCreateOptionsSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, DatasetSummarySchema, FlowMapOptionsSchema, FlowZoneArraySchema, FlowZoneCreateOptionsSchema, FlowZoneItemSchema, FlowZoneObjectTypeSchema, FlowZonePositionSchema, FlowZoneSchema, FlowZoneUpdateOptionsSchema, FolderCreateOptionsSchema, FolderDetailsSchema, FolderItemArraySchema, FolderItemSchema, FolderSummaryArraySchema, FolderSummarySchema, FutureStateSchema, FutureWaitResultSchema, InsightDetailsSchema, InsightSummaryArraySchema, InsightSummarySchema, JobSummaryArraySchema, JobSummarySchema, JobWaitResultSchema, JupyterCellSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, JupyterNotebookSummarySchema, NotebookSessionArraySchema, NotebookSessionSchema, parseSchema, ProjectDetailsSchema, ProjectGitActionResultSchema, ProjectGitDiffResultSchema, ProjectGitFutureResponseSchema, ProjectGitFutureStateSchema, ProjectGitLibrariesSchema, ProjectGitLibrarySchema, ProjectGitLogResultSchema, ProjectGitRemoteSchema, ProjectGitStatusSchema, ProjectGitTagSchema, ProjectGitTagsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, ProjectSummarySchema, ProjectVariablesSchema, RecipeCreateOptionsSchema, RecipeCreateResultSchema, RecipeDetailsSchema, RecipeSummaryArraySchema, RecipeSummarySchema, safeParseSchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioStepRunSchema, ScenarioSummaryArraySchema, ScenarioSummarySchema, ScenarioWaitResultSchema, SqlNotebookCellSchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, SqlNotebookSummarySchema, SqlQueryResponseSchema, SqlQueryResultSchema, SqlQuerySchemaSchema, WikiArticleDataArraySchema, WikiArticleDataSchema, WikiArticleMetadataSchema, WikiSettingsSchema, WikiTaxonomyNodeSchema, } from "../packages/types/src/index.js";

package/dist/src/skill.d.ts

@@ -28,10 +28,19 @@ export declare function detectAgents(): DetectedAgent[];
  * Agent config directories are install targets, not workspace roots.
  */
 export declare function findWorkspaceRoot(startDir: string): string;
+export type SkillStatus = "missing" | "stale" | "current";
 export interface InstallResult {
     agent: string;
     path: string;
     via: DetectedAgent["via"];
+    /** Deterministic state of the destination file relative to the canonical skill content. */
+    status: SkillStatus;
+    /** Whether an install run would (or did) write the destination file. */
+    changed: boolean;
+    /** SHA-256 hex of the canonical skill bytes this installation writes. */
+    expectedSha256: string;
+    /** SHA-256 hex of the destination file when it exists; absent when status is "missing". */
+    actualSha256?: string;
 }
 export declare function planSkillInstalls(agents: DetectedAgent[], opts: {
     global: boolean;

package/dist/src/skill.js

@@ -1,3 +1,4 @@
+import { createHash, } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -97,6 +98,18 @@ export function findWorkspaceRoot(startDir) {
     }
     return startDir;
 }
+function sha256Hex(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function skillState(target, expectedSha256) {
+    if (!fs.existsSync(target))
+        return { status: "missing", };
+    const actualSha256 = sha256Hex(fs.readFileSync(target));
+    return {
+        status: actualSha256 === expectedSha256 ? "current" : "stale",
+        actualSha256,
+    };
+}
 export function planSkillInstalls(agents, opts) {
     const home = os.homedir();
     const results = [];
@@ -108,7 +121,17 @@ export function planSkillInstalls(agents, opts) {
                 : undefined;
         if (!dir)
             continue;
-        results.push({ agent: id, path: path.join(dir, def.filename), via, });
+        const target = path.join(dir, def.filename);
+        const expectedSha256 = sha256Hex(def.content());
+        const state = skillState(target, expectedSha256);
+        results.push({
+            agent: id,
+            path: target,
+            via,
+            ...state,
+            changed: state.status !== "current",
+            expectedSha256,
+        });
     }
     return results;
 }
@@ -116,10 +139,20 @@ export function installSkill(agents, opts) {
     const results = planSkillInstalls(agents, opts);
     for (const result of results) {
         const def = AGENTS[result.agent];
-        if (!def)
+        if (!def || !result.changed)
             continue;
-        fs.mkdirSync(path.dirname(result.path), { recursive: true, });
-        fs.writeFileSync(result.path, def.content(), "utf-8");
+        const content = def.content();
+        const dir = path.dirname(result.path);
+        fs.mkdirSync(dir, { recursive: true, });
+        const tmpPath = path.join(dir, `.${path.basename(result.path)}.tmp-${process.pid}-${Date.now().toString(36)}`);
+        fs.writeFileSync(tmpPath, content, "utf-8");
+        try {
+            fs.renameSync(tmpPath, result.path);
+        }
+        catch (error) {
+            fs.rmSync(tmpPath, { force: true, });
+            throw error;
+        }
     }
     return results;
 }

package/dist/src/utils/flow-analysis.d.ts

@@ -0,0 +1,53 @@
+import type { FlowZone } from "../schemas.js";
+import type { NormalizedFlowMap, NormalizedFlowNode } from "./flow-map.js";
+export type FlowRenderFormat = "ascii" | "mermaid";
+export type FlowDiagnosticSeverity = "info" | "warning";
+export interface AnalyzedFlowNode extends NormalizedFlowNode {
+    componentId: string;
+    layer: number;
+    zoneId: string;
+    zoneName: string;
+}
+export interface FlowMapZone {
+    id: string;
+    name: string;
+    color?: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    itemCount: number;
+    nodeIds: string[];
+}
+export interface FlowMapComponent {
+    id: string;
+    nodeIds: string[];
+    rootIds: string[];
+    leafIds: string[];
+    cyclic: boolean;
+}
+export interface FlowMapDiagnostic {
+    code: string;
+    severity: FlowDiagnosticSeverity;
+    message: string;
+    nodeIds?: string[];
+    componentIds?: string[];
+    edgeCount?: number;
+}
+export interface AnalyzedFlowMap extends Omit<NormalizedFlowMap, "nodes"> {
+    nodes: AnalyzedFlowNode[];
+    zones: FlowMapZone[];
+    components: FlowMapComponent[];
+    diagnostics: FlowMapDiagnostic[];
+    topologyFingerprint: string;
+}
+export interface FlowMapRendering {
+    format: FlowRenderFormat;
+    content: string;
+}
+export declare function flowTopologyFingerprint(map: NormalizedFlowMap): string;
+export declare function analyzeFlowMap(map: NormalizedFlowMap, flowZones: FlowZone[], options?: {
+    topologyFingerprint?: string;
+    truncated?: boolean;
+}): AnalyzedFlowMap;
+export declare function renderFlowMap(map: AnalyzedFlowMap, format: FlowRenderFormat): FlowMapRendering;