@finos/legend-cube-builder 0.0.4 → 0.0.6

package/src/graph-manager/protocol/pure/v1/V1_LegendCubeEngine.ts

@@ -22,7 +22,11 @@ import {
   type Schema,
   storeAccessor,
 } from '@finos/legend-cube';
-import { V1_EngineServerClient, V1_RenderStyle } from '@finos/legend-graph';
+import {
+  EXECUTION_SERIALIZATION_FORMAT,
+  V1_EngineServerClient,
+  V1_RenderStyle,
+} from '@finos/legend-graph';
 import {
   ContentType,
   HttpHeader,
@@ -50,6 +54,8 @@ import {
   getCubeIngestSettings,
   isCubeIngestModel,
 } from '../../../CubeIngest.js';
+import type { CubeEngineClientSettings } from '../../../CubeEngineClientSettings.js';
+import type { CubeDataProductModelSource } from '../../../CubeDataProductCatalog.js';
 import type { CubeLakehouseEnvironment } from '../../../CubeLakehouseEnvironment.js';
 import {
   checkCubeProjectModel,
@@ -287,6 +293,8 @@ export class V1_LegendCubeEngine implements CubeEngine {
   private readonly getRememberedWarehouse: () => string | undefined;
   /** The deployed ingest definitions, which ingest cubes read */
   private readonly ingestDefinitions: V1_CubeIngestDefinitionSource | undefined;
+  /** The model data product cubes read their project from, when not its deployed version */
+  private readonly dataProductModels: CubeDataProductModelSource | undefined;
 
   constructor(
     config: V1_CubeEngineConfig,
@@ -295,15 +303,42 @@ export class V1_LegendCubeEngine implements CubeEngine {
       lakehouseEnvironment?: CubeLakehouseEnvironment | undefined;
       getRememberedWarehouse?: (() => string | undefined) | undefined;
       ingestDefinitions?: V1_CubeIngestDefinitionSource | undefined;
+      /** Dev Settings' engine URL and compression (PLAN §11.16) */
+      clientSettings?: CubeEngineClientSettings | undefined;
+      dataProductModels?: CubeDataProductModelSource | undefined;
     },
   ) {
     this.client = new V1_EngineServerClient(config);
     // every call throws without one
     this.client.setTracerService(tracerService);
+    options?.clientSettings?.register(this.client);
     this.lakehouseEnvironment = options?.lakehouseEnvironment;
     this.getRememberedWarehouse =
       options?.getRememberedWarehouse ?? (() => undefined);
     this.ingestDefinitions = options?.ingestDefinitions;
+    this.dataProductModels = options?.dataProductModels;
+  }
+
+  /**
+   * The elements an ingest cube's model holds: the host's, when it has more
+   * than the definitions (Studio's workspace), else the definitions read
+   */
+  private async ingestModelElementsOf(
+    definitions: ReadonlyMap<string, PlainObject | CubeEngineError>,
+  ): Promise<readonly PlainObject[]> {
+    const source = this.ingestDefinitions;
+    return source?.getModelElements
+      ? source.getModelElements()
+      : [...definitions.values()].filter(
+          (read): read is PlainObject => !(read instanceof CubeEngineError),
+        );
+  }
+
+  /** The model a data product cube's project is read from: the host's, else its deployed version's pointer */
+  private async dataProductProjectModelOf(
+    project: CubeDataProductProject,
+  ): Promise<PlainObject | undefined> {
+    return this.dataProductModels?.getProjectModel(project);
   }
 
   /** An ingest model's settings, or an unsupported-model error naming its problems */
@@ -636,7 +671,21 @@ export class V1_LegendCubeEngine implements CubeEngine {
         ]),
       );
     }
-    return this.typeOn(V1_buildCubeDataProductTypingContext(project), lambdas);
+    let projectModel: PlainObject | undefined;
+    try {
+      projectModel = await this.dataProductProjectModelOf(project);
+    } catch (error) {
+      return new Map(
+        [...lambdas.keys()].map((nodeId) => [
+          nodeId,
+          V1_toCubeEngineError(error, nodeId, CubeEngineErrorKind.COMPILE),
+        ]),
+      );
+    }
+    return this.typeOn(
+      V1_buildCubeDataProductTypingContext(project, projectModel),
+      lambdas,
+    );
   }
 
   /**
@@ -705,9 +754,19 @@ export class V1_LegendCubeEngine implements CubeEngine {
         typable.set(nodeId, ir);
       }
     });
-    const elements = [...definitions.values()].filter(
-      (read): read is PlainObject => !(read instanceof CubeEngineError),
-    );
+    let elements: readonly PlainObject[];
+    try {
+      elements = await this.ingestModelElementsOf(definitions);
+    } catch (error) {
+      typable.forEach((_ir, nodeId) =>
+        typed.set(
+          nodeId,
+          toIngestError(error, CubeEngineErrorKind.COMPILE, nodeId),
+        ),
+      );
+      typable.clear();
+      elements = [];
+    }
     (
       await this.typeOn(V1_buildCubeIngestTypingContext(elements), typable)
     ).forEach((schema, nodeId) => typed.set(nodeId, schema));
@@ -938,6 +997,39 @@ export class V1_LegendCubeEngine implements CubeEngine {
     }
   }
 
+  async exportCsv(
+    model: ModelContext,
+    executionLambda: IR,
+    options?: { abortController?: AbortController | undefined },
+  ): Promise<string> {
+    const captureId = captureNodeOf(executionLambda);
+    const context = await this.executionContextOf(
+      model,
+      executionLambda,
+      captureId,
+      options?.abortController,
+    );
+    try {
+      const body = this.executionBodyOf(model, context, executionLambda);
+      // the engine answers CSV under a JSON content type, and a failure as JSON with status 500 (PLAN §11.10)
+      const response = (await this.client.runQuery(
+        body as unknown as PlainObject,
+        {
+          returnAsResponse: true,
+          serializationFormat: EXECUTION_SERIALIZATION_FORMAT.CSV,
+          abortController: options?.abortController,
+        },
+      )) as Response;
+      return await response.text();
+    } catch (error) {
+      throw V1_toCubeEngineError(
+        error,
+        captureId,
+        CubeEngineErrorKind.EXECUTION,
+      );
+    }
+  }
+
   /**
    * The model a run on a data product cube runs on (PLAN §6.8): its project at
    * the saved version, and a lakehouse runtime at Cube's fixed path, in the
@@ -975,10 +1067,21 @@ export class V1_LegendCubeEngine implements CubeEngine {
             captureId,
           );
     }
+    let projectModel: PlainObject | undefined;
+    try {
+      projectModel = await this.dataProductProjectModelOf(project);
+    } catch (error) {
+      throw V1_toCubeEngineError(
+        error,
+        captureId,
+        CubeEngineErrorKind.EXECUTION,
+      );
+    }
     return V1_buildCubeDataProductExecutionContext(
       project,
       environment,
       getEffectiveCubeWarehouse(project, this.getRememberedWarehouse()),
+      projectModel,
     );
   }
 
@@ -1015,13 +1118,17 @@ export class V1_LegendCubeEngine implements CubeEngine {
       V1_getCubeIngestUrns(accessors),
       settings,
     );
-    const elements: PlainObject[] = [];
     definitions.forEach((read) => {
       if (read instanceof CubeEngineError) {
         throw toIngestError(read, CubeEngineErrorKind.EXECUTION, captureId);
       }
-      elements.push(read);
     });
+    let elements: readonly PlainObject[];
+    try {
+      elements = await this.ingestModelElementsOf(definitions);
+    } catch (error) {
+      throw toIngestError(error, CubeEngineErrorKind.EXECUTION, captureId);
+    }
     let environment: string;
     try {
       environment = await source.getRuntimeEnvironment(
@@ -1204,6 +1311,14 @@ export class V1_LegendCubeEngine implements CubeEngine {
     }
   }
 
+  serializeLambda(lambdaIR: IR): string {
+    return stringifyLosslessJSON(
+      V1_serializeCubeLambda(lambdaIR),
+      undefined,
+      2,
+    );
+  }
+
   async renderPure(lambdaIR: IR): Promise<string> {
     try {
       // sent as text, as typing and execution are: the serialized lambda holds

package/src/graph-manager/protocol/pure/v1/V1_LegendCubeProjectCatalog.ts

@@ -44,13 +44,13 @@ export const V1_compareCubeProjectVersionsNewestFirst = (
   return 0;
 };
 
-/** The paths of a model's Databases */
-const databasePathsOf = (modelData: PlainObject): Set<string> =>
+/** The paths of a model's elements of a type: its Databases, or its functions by full name */
+const elementPathsOf = (modelData: PlainObject, type: string): Set<string> =>
   new Set(
     (Array.isArray(modelData.elements) ? modelData.elements : [])
       .filter(
         (element: PlainObject) =>
-          element._type === 'relational' &&
+          element._type === type &&
           typeof element.package === 'string' &&
           typeof element.name === 'string',
       )
@@ -135,13 +135,18 @@ export class V1_LegendCubeProjectCatalog implements CubeProjectCatalog {
         true,
       ),
     ]);
-    const ownDatabases = databasePathsOf(own);
+    const ownDatabases = elementPathsOf(own, 'relational');
+    const ownFunctions = elementPathsOf(own, 'function');
+    // a function's runtime is read through its dependencies' functions too
     const outline = V1_buildCubeModelOutline(withDependencies);
     return {
       ...outline,
       databases: outline.databases.filter((database) =>
         ownDatabases.has(database.path),
       ),
+      functions: (outline.functions ?? []).filter((fn) =>
+        ownFunctions.has(fn.signature),
+      ),
     };
   }
 }

package/src/graph-manager/protocol/pure/v1/V1_LegendCubeServiceCatalog.ts

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  DeploymentOwnershipDetail,
+  type ServiceDetail,
+  UserListOwnershipDetail,
+} from '@finos/legend-graph';
+import { HttpStatus, NetworkClientError } from '@finos/legend-shared';
+import type {
+  CubeServiceCatalog,
+  CubeServiceSummary,
+} from '../../../CubeServiceCatalog.js';
+
+/** Who owns a service, as people read it */
+const ownersOf = (service: ServiceDetail): readonly string[] =>
+  service.ownership instanceof UserListOwnershipDetail
+    ? service.ownership.users
+    : service.ownership instanceof DeploymentOwnershipDetail
+      ? [`Deployment ${service.ownership.identifier}`]
+      : [];
+
+/** Why the list can't be read, when the engine has no service registry */
+export const V1_CUBE_NO_SERVICE_REGISTRY_MESSAGE =
+  "This Legend deployment's engine has no service registry, so it lists no services";
+
+const toSummary = (service: ServiceDetail): CubeServiceSummary => ({
+  name: service.name,
+  title: service.title?.trim() ? service.title.trim() : undefined,
+  pattern: service.pattern,
+  documentation: service.documentation,
+  owners: ownersOf(service),
+});
+
+/**
+ * Lists the services in the engine's registry
+ * (`/service/v1/list/detailsFromCache`, as Marketplace's Data APIs page). The
+ * list is read once per page; a failed read is tried again.
+ */
+export class V1_LegendCubeServiceCatalog implements CubeServiceCatalog {
+  private readonly readServices: () => Promise<ServiceDetail[]>;
+  private services: Promise<readonly CubeServiceSummary[]> | undefined;
+
+  constructor(readServices: () => Promise<ServiceDetail[]>) {
+    this.readServices = readServices;
+  }
+
+  listServices(): Promise<readonly CubeServiceSummary[]> {
+    if (!this.services) {
+      const services = this.readServices()
+        .catch((error: unknown) => {
+          // the registry isn't in the open-source engine
+          throw error instanceof NetworkClientError &&
+            error.response.status === HttpStatus.NOT_FOUND
+            ? new Error(V1_CUBE_NO_SERVICE_REGISTRY_MESSAGE)
+            : error;
+        })
+        .then((details) =>
+          details
+            .filter((detail) => detail.name && detail.pattern)
+            .map(toSummary)
+            .sort(
+              (left, right) =>
+                (left.title ?? left.name).localeCompare(
+                  right.title ?? right.name,
+                ) || left.name.localeCompare(right.name),
+            ),
+        );
+      // a failed read is tried again next time
+      services.catch(() => {
+        if (this.services === services) {
+          this.services = undefined;
+        }
+      });
+      this.services = services;
+    }
+    return this.services;
+  }
+}

package/src/graph-manager/protocol/pure/v1/__test-utils__/V1_CubeEngineTestUtils.ts

@@ -15,6 +15,7 @@
  */
 
 import { jest } from '@jest/globals';
+import { V1_getEngineSerializationFormat } from '@finos/legend-graph';
 import {
   ENGINE_TEST_SUPPORT__grammarToJSON_model,
   ENGINE_TEST_SUPPORT_API_URL,
@@ -105,9 +106,13 @@ export const V1_createEngineBackedCubeEngine = (): {
     );
   const runQuery = jest
     .spyOn(client, 'runQuery')
-    .mockImplementation(async (input) => {
+    .mockImplementation(async (input, options) => {
+      // the format as the client sends it, e.g. CSV (PLAN §11.10)
       const response = await CUBE_ENGINE_TEST__execute(
         input as unknown as string,
+        options?.serializationFormat
+          ? V1_getEngineSerializationFormat(options.serializationFormat)
+          : undefined,
       );
       if (!response.ok) {
         throw clientError(response.status, parseOrText(await response.text()));

package/src/index.ts

@@ -19,7 +19,11 @@ export {
   LEGEND_CUBE_COMMAND_KEY,
 } from './__lib__/LegendCubeCommand.js';
 export { LEGEND_CUBE_TEST_ID } from './__lib__/LegendCubeTesting.js';
-export { CubeEditor } from './components/CubeEditor.js';
+export { CubeButton } from './components/CubeButton.js';
+export { CubeEditor, type CubeHeaderActions } from './components/CubeEditor.js';
+export type { CubeEditorState } from './stores/CubeEditorState.js';
+export { buildCubeRunningStepLambda } from './stores/CubeRunningStepLambda.js';
+export { formatDisabledReasons } from './__lib__/LegendCubeLabels.js';
 export {
   type CubeAccessPointEntry,
   type CubeEntrySource,
@@ -32,8 +36,11 @@ export * from './graph-manager/CubeDataProductCatalog.js';
 export * from './graph-manager/CubeIngest.js';
 export * from './graph-manager/CubeIngestCatalog.js';
 export * from './graph-manager/CubeEngine.js';
+export * from './graph-manager/CubeEngineClientSettings.js';
 export * from './graph-manager/CubeProject.js';
 export * from './graph-manager/CubeProjectCatalog.js';
+export * from './graph-manager/CubeService.js';
+export * from './graph-manager/CubeServiceCatalog.js';
 export { getRuntimesForDatabase } from './graph-manager/CubeModelOutlineHelper.js';
 export {
   buildCubeConnectionExplorer,
@@ -42,12 +49,42 @@ export {
   buildCubeEngine,
   buildCubeLakehouseEnvironment,
   buildCubeProjectCatalog,
+  buildCubeServiceCatalog,
+  readCubeIngestDataSets,
+  serializeCubeLambdaForHost,
   type CubeEngineConfig,
   type CubeLakehouseServices,
 } from './graph-manager/protocol/pure/CubeEngineBuilder.js';
 export type { CubeLakehouseEnvironment } from './graph-manager/CubeLakehouseEnvironment.js';
-export type { CubeHost } from './stores/CubeHost.js';
+export {
+  type CubeHost,
+  type CubeHostProject,
+  type CubeHostProjectRuntime,
+  isCubeProjectHost,
+  isCubeSampleDataOffered,
+} from './stores/CubeHost.js';
+export {
+  buildLegendCubeLakehouseServices,
+  buildLegendCubeProjectCatalog,
+  LegendCubeHost,
+  type LegendCubeHostConfig,
+  type LegendCubeHostParts,
+} from './stores/LegendCubeHost.js';
 export { getCubeRememberedWarehouse } from './stores/CubeDataProductWarehouse.js';
+export {
+  CUBE_LAMBDA_IMPORT_MESSAGE,
+  CubeLambdaFidelity,
+  getCubeLambdaFidelity,
+  readCubeLambdaDocument,
+  type CubeInitialLambda,
+  type CubeLambdaImportState,
+  type CubeLambdaReading,
+} from './stores/CubeLambdaImportState.js';
+export {
+  bindCubeLambdaSources,
+  CUBE_LAMBDA_SOURCES_MESSAGE,
+  type CubeLambdaBinding,
+} from './stores/CubeLambdaSources.js';
 export {
   BUNDLED_MODELS,
   type BundledModel,

package/src/stores/CubeAddPlacement.ts

@@ -15,6 +15,7 @@
  */
 
 import type { CubeEditorState } from './CubeEditorState.js';
+import { CUBE_NODE_TYPES_WITHOUT_SETTINGS } from './editors/CubeNodeDraftRegistry.js';
 
 // Where a node added from the palette, the canvas's context menu or 'Add
 // Items' goes (PLAN §11.8, QUESTIONS.md U3 and U4): one rule for all of them.
@@ -34,7 +35,21 @@ export const getCubeAddAfterId = (
     ? undefined
     : (targetNodeId ?? editorState.document.query.selected);
 
-/** Whether a node of the type can be added where the rule puts it */
+/**
+ * Why a node of the type can't be added where the rule puts it, on the
+ * database the query there runs on: a Pivot where it can't run (PLAN §11.12)
+ */
+export const getCubeAddDatabaseProblem = (
+  editorState: CubeEditorState,
+  type: string,
+  targetNodeId?: string,
+): string | undefined =>
+  editorState.getAddDatabaseProblem(
+    type,
+    getCubeAddAfterId(editorState, type, targetNodeId),
+  );
+
+/** Whether a node of the type can be added where the rule puts it, and run on its database */
 export const canAddCubeNode = (
   editorState: CubeEditorState,
   type: string,
@@ -43,12 +58,14 @@ export const canAddCubeNode = (
   editorState.canAddNode(
     type,
     getCubeAddAfterId(editorState, type, targetNodeId),
-  );
+  ) && getCubeAddDatabaseProblem(editorState, type, targetNodeId) === undefined;
 
 /**
  * Adds a node of the type where the rule puts it, after the node editor's
- * edits are applied: a transform with its defaults, no editor opened; a
- * source through the source dialog, on its tab
+ * edits are applied: a transform with its defaults, its editor opened when
+ * it has settings to set, since it can't run until they are (UX audit B3,
+ * user, 2026-10-11, in place of U3's "no add opens the editor"); a source
+ * through the source dialog, on its tab
  */
 export const addCubeNode = (
   editorState: CubeEditorState,
@@ -59,9 +76,12 @@ export const addCubeNode = (
     canAddCubeNode(editorState, type, targetNodeId) &&
     editorState.nodeEditor.finishApplied()
   ) {
-    editorState.addNode(
+    const id = editorState.addNode(
       type,
       getCubeAddAfterId(editorState, type, targetNodeId),
     );
+    if (id !== undefined && !CUBE_NODE_TYPES_WITHOUT_SETTINGS.includes(type)) {
+      editorState.nodeEditor.open(id);
+    }
   }
 };

package/src/stores/CubeDevSettingsState.ts

@@ -0,0 +1,117 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { isValidUrl } from '@finos/legend-shared';
+import { action, computed, makeObservable, observable } from 'mobx';
+import { LEGEND_CUBE_USER_DATA_KEY } from '../__lib__/LegendCubeLabels.js';
+import type { CubeEngineClientSettings } from '../graph-manager/CubeEngineClientSettings.js';
+import type { CubeHost } from './CubeHost.js';
+
+/**
+ * The page's Dev Settings, opened from the menu at the top left as Legend
+ * Query's editor opens its own (PLAN §11.16): the engine's URL, and whether
+ * Cube's engine clients compress their requests (uncompressed, the browser's
+ * Network tab shows each request's JSON). Compression is kept for the user,
+ * on by default; the URL lasts while the application runs, as Query's does.
+ * Both change every engine client of Cube's host, from the next request.
+ */
+export class CubeDevSettingsState {
+  private readonly host: CubeHost;
+  private readonly settings: CubeEngineClientSettings | undefined;
+  isOpen = false;
+  requestCompression: boolean;
+  /** The engine URL as typed: it is used once it is a URL */
+  baseUrlText: string;
+
+  constructor(host: CubeHost) {
+    makeObservable<CubeDevSettingsState, 'host' | 'settings'>(this, {
+      host: false,
+      settings: false,
+      isOpen: observable,
+      requestCompression: observable,
+      baseUrlText: observable,
+      baseUrlError: computed,
+      open: action,
+      close: action,
+      setRequestCompression: action,
+      setBaseUrlText: action,
+      resetBaseUrl: action,
+    });
+    this.host = host;
+    this.settings = host.engineClientSettings;
+    const uncompressed =
+      host.applicationStore.userDataService.getBooleanValue(
+        LEGEND_CUBE_USER_DATA_KEY.UNCOMPRESSED_REQUESTS,
+      ) ?? false;
+    if (uncompressed) {
+      this.settings?.setRequestCompression(false);
+    }
+    this.requestCompression = this.settings?.requestCompression ?? true;
+    this.baseUrlText = this.settings?.baseUrl ?? '';
+  }
+
+  /** Whether the host lets Dev Settings change its engine clients */
+  get isAvailable(): boolean {
+    return this.settings !== undefined;
+  }
+
+  /** The URL the host configured */
+  get defaultBaseUrl(): string | undefined {
+    return this.settings?.defaultBaseUrl;
+  }
+
+  /** Why the typed engine URL isn't used, if it isn't */
+  get baseUrlError(): string | undefined {
+    return isValidUrl(this.baseUrlText) ? undefined : 'Invalid URL';
+  }
+
+  open(): void {
+    this.isOpen = true;
+  }
+
+  close(): void {
+    this.isOpen = false;
+  }
+
+  setRequestCompression(compressed: boolean): void {
+    if (!this.settings) {
+      return;
+    }
+    this.requestCompression = compressed;
+    this.settings.setRequestCompression(compressed);
+    this.host.applicationStore.userDataService.persistValue(
+      LEGEND_CUBE_USER_DATA_KEY.UNCOMPRESSED_REQUESTS,
+      !compressed,
+    );
+  }
+
+  /** Takes the typed engine URL, and uses it once it is a URL */
+  setBaseUrlText(text: string): void {
+    this.baseUrlText = text;
+    if (this.settings && isValidUrl(text)) {
+      this.settings.setBaseUrl(text);
+    }
+  }
+
+  /** Goes back to the engine URL the host configured */
+  resetBaseUrl(): void {
+    if (!this.settings) {
+      return;
+    }
+    this.settings.setBaseUrl(this.settings.defaultBaseUrl);
+    this.baseUrlText = this.settings.defaultBaseUrl ?? '';
+  }
+}