@finos/legend-cube-builder 0.0.4 → 0.0.5

package/src/components/source-picker/CubeServiceTab.tsx

@@ -0,0 +1,151 @@
+/**
+ * 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 { observer } from 'mobx-react-lite';
+import {
+  CUBE_SERVICE_MESSAGE,
+  getShownServicesLabel,
+} from '../../__lib__/LegendCubeServiceLabels.js';
+import { CUBE_PENDING_LABEL } from '../../__lib__/LegendCubeLabels.js';
+import type { CubeServiceTabState } from '../../stores/source-picker/CubeServiceTabState.js';
+import { CubeButton } from '../CubeButton.js';
+import {
+  CUBE_PICKER_LIST_CLASS,
+  CubePickerListItem,
+} from './CubePickerListItem.js';
+
+const INPUT_CLASS =
+  'h-7 rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] px-1 text-base text-[var(--color-text-primary)]';
+
+/**
+ * The source dialog's Service tab (PLAN §6.4), in progress: the deployed
+ * services, searched by title, name and pattern, and the picked one's
+ * details. A service can be added, but Cube can't read it yet.
+ */
+export const CubeServiceTab = observer(
+  (props: { tab: CubeServiceTabState }) => {
+    const { tab } = props;
+    const picked = tab.service;
+    const shownLabel = getShownServicesLabel(
+      tab.shownServices.length,
+      tab.matchingServices.length,
+    );
+    return (
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-[var(--color-text-muted)]">
+          {CUBE_SERVICE_MESSAGE.IN_PROGRESS}
+        </span>
+        <input
+          className={INPUT_CLASS}
+          placeholder="Search services"
+          aria-label="Search services"
+          value={tab.search}
+          onChange={(event) => tab.setSearch(event.target.value)}
+        />
+        {tab.isLoading && (
+          <div className="text-base text-[var(--color-text-secondary)]">
+            listing services
+          </div>
+        )}
+        {tab.services && (
+          <>
+            {tab.shownServices.length ? (
+              <ul
+                className={`h-56 overflow-auto ${CUBE_PICKER_LIST_CLASS}`}
+                aria-label="Services"
+              >
+                {tab.shownServices.map((service) => (
+                  <CubePickerListItem
+                    key={service.pattern}
+                    picked={tab.pattern === service.pattern}
+                    title={service.name}
+                    adds={true}
+                    onPick={() => tab.selectService(service.pattern)}
+                  >
+                    <span className="min-w-0 flex-1 truncate">
+                      {service.title ?? service.name}
+                    </span>
+                    <span className="max-w-[50%] shrink-0 truncate text-sm text-[var(--color-text-muted)]">
+                      {service.pattern}
+                    </span>
+                  </CubePickerListItem>
+                ))}
+              </ul>
+            ) : (
+              <div className="text-base text-[var(--color-text-secondary)]">
+                {tab.services.length
+                  ? CUBE_SERVICE_MESSAGE.NO_MATCH
+                  : CUBE_SERVICE_MESSAGE.NONE}
+              </div>
+            )}
+            {shownLabel !== undefined && (
+              <span className="text-sm text-[var(--color-text-muted)]">
+                {shownLabel}
+              </span>
+            )}
+          </>
+        )}
+        {picked && (
+          <section
+            aria-label="Service details"
+            className="flex flex-col gap-1 text-base"
+          >
+            <span className="break-all font-medium">{picked.name}</span>
+            <span className="break-all text-[var(--color-text-secondary)]">
+              {picked.pattern}
+            </span>
+            {picked.owners.length > 0 && (
+              <span className="text-sm text-[var(--color-text-muted)]">
+                {`Owners: ${picked.owners.join(', ')}`}
+              </span>
+            )}
+            {picked.documentation.trim() !== '' && (
+              <p className="max-h-20 overflow-auto whitespace-pre-wrap text-sm text-[var(--color-text-secondary)]">
+                {picked.documentation}
+              </p>
+            )}
+          </section>
+        )}
+        {tab.isAdding && (
+          <div className="text-base text-[var(--color-text-secondary)]">
+            {CUBE_PENDING_LABEL.RESOLVING_SOURCE}
+          </div>
+        )}
+        {tab.error !== undefined && (
+          <div
+            className="flex flex-col gap-1 text-base text-[var(--color-status-error)]"
+            role="alert"
+          >
+            <span>{tab.error.message}</span>
+            {tab.error.detail !== undefined && (
+              <details className="text-sm">
+                <summary className="cursor-pointer">Details</summary>
+                <pre className="whitespace-pre-wrap break-words">
+                  {tab.error.detail}
+                </pre>
+              </details>
+            )}
+            {tab.services === undefined && (
+              <div>
+                <CubeButton onClick={() => tab.retry()}>Retry</CubeButton>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    );
+  },
+);

package/src/components/source-picker/CubeSourcePicker.tsx

@@ -26,14 +26,20 @@ import {
 } from '@finos/legend-art';
 import { flowResult } from 'mobx';
 import { observer } from 'mobx-react-lite';
-import { SELECT_SOURCE_TYPE_PROMPT } from '../../__lib__/LegendCubeLabels.js';
+import {
+  CUBE_PICK_TO_ADD_TITLE,
+  SELECT_SOURCE_TYPE_PROMPT,
+} from '../../__lib__/LegendCubeLabels.js';
 import type { CubeEditorState } from '../../stores/CubeEditorState.js';
 import { CubeSourcePickerTabKey } from '../../stores/source-picker/CubeSourcePickerTab.js';
 import { CubeDataProductTab } from './CubeDataProductTab.js';
 import { CubeIngestTab } from './CubeIngestTab.js';
+import { CubeServiceTab } from './CubeServiceTab.js';
 import { CubeProjectTab } from './CubeProjectTab.js';
 import { CubeDirectConnectionTab } from './CubeDirectConnectionTab.js';
 import { CubeInlineModelTab } from './CubeInlineModelTab.js';
+import { CubePickerConfirmContext } from './CubePickerListItem.js';
+import { CUBE_PRIMARY_BUTTON_DARK_MODE } from '../CubeDialogTheme.js';
 
 /**
  * Adds a source to the cube (PLAN §6.1, §6.2.7, §6.8): a tab per way to find
@@ -63,6 +69,17 @@ export const CubeSourcePicker = observer(
             isLoading={!picker.isChoosingTab && activeTab.isBusy}
           />
           <ModalBody>
+            {picker.isFromExamples && (
+              // a link back, under the title, as the dialog came from Examples
+              <button
+                type="button"
+                className="mb-2 self-start text-base text-[var(--color-accent)] hover:underline"
+                title="Back to the examples, to open an example cube instead"
+                onClick={() => picker.backToExamples()}
+              >
+                ← Back to Examples
+              </button>
+            )}
             {tabs.length > 1 && (
               <div
                 className="mb-2 flex gap-1 border-b border-[var(--color-border-subtle)]"
@@ -99,28 +116,47 @@ export const CubeSourcePicker = observer(
                   : undefined
               }
             >
-              {picker.isChoosingTab ? (
-                <div className="py-4 text-center text-base text-[var(--color-text-secondary)]">
-                  {SELECT_SOURCE_TYPE_PROMPT}
-                </div>
-              ) : activeTab.key === CubeSourcePickerTabKey.DIRECT_CONNECTION ? (
-                <CubeDirectConnectionTab tab={picker.directTab} />
-              ) : activeTab.key === CubeSourcePickerTabKey.DATA_PRODUCT ? (
-                <CubeDataProductTab tab={picker.dataProductTab} />
-              ) : activeTab.key === CubeSourcePickerTabKey.INGEST ? (
-                <CubeIngestTab tab={picker.ingestTab} />
-              ) : activeTab.key === CubeSourcePickerTabKey.PROJECT ? (
-                <CubeProjectTab tab={picker.projectTab} />
-              ) : (
-                <CubeInlineModelTab tab={picker.modelTab} />
-              )}
+              <CubePickerConfirmContext.Provider value={confirm}>
+                {picker.isChoosingTab ? (
+                  <div className="py-4 text-center text-base text-[var(--color-text-secondary)]">
+                    {SELECT_SOURCE_TYPE_PROMPT}
+                  </div>
+                ) : activeTab.key ===
+                  CubeSourcePickerTabKey.DIRECT_CONNECTION ? (
+                  <CubeDirectConnectionTab tab={picker.directTab} />
+                ) : activeTab.key === CubeSourcePickerTabKey.DATA_PRODUCT ? (
+                  <CubeDataProductTab tab={picker.dataProductTab} />
+                ) : activeTab.key === CubeSourcePickerTabKey.INGEST ? (
+                  <CubeIngestTab tab={picker.ingestTab} />
+                ) : activeTab.key === CubeSourcePickerTabKey.PROJECT ? (
+                  <CubeProjectTab tab={picker.projectTab} />
+                ) : activeTab.key ===
+                  CubeSourcePickerTabKey.PROJECT_FUNCTION ? (
+                  <CubeProjectTab tab={picker.projectFunctionTab} />
+                ) : activeTab.key === CubeSourcePickerTabKey.SERVICE ? (
+                  <CubeServiceTab tab={picker.serviceTab} />
+                ) : (
+                  <CubeInlineModelTab tab={picker.modelTab} />
+                )}
+              </CubePickerConfirmContext.Provider>
             </div>
           </ModalBody>
           <ModalFooter>
             <ModalFooterButton
-              darkMode={darkMode}
+              darkMode={CUBE_PRIMARY_BUTTON_DARK_MODE}
               formatText={false}
-              text="Add"
+              text={
+                (picker.activeTab.pickedCount ?? 1) > 1
+                  ? `Add ${picker.activeTab.pickedCount}`
+                  : 'Add'
+              }
+              // the legacy footer button looks the same disabled
+              className="disabled:cursor-not-allowed disabled:opacity-50"
+              title={
+                picker.canConfirm
+                  ? 'Add it to the cube'
+                  : CUBE_PICK_TO_ADD_TITLE
+              }
               disabled={!picker.canConfirm}
               onClick={confirm}
             />

package/src/components/source-picker/CubeTablePreview.tsx

@@ -0,0 +1,49 @@
+/**
+ * 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 type { Schema } from '@finos/legend-cube';
+import { CubeSchemaColumnsTable } from '../CubeSchemaColumnsTable.js';
+
+/**
+ * The columns of the table picked last, under the source dialog's list, as
+ * an access point's preview shows them (the review of the demo, 2026-10-13):
+ * loading, then the columns, or why they couldn't be read. A failure doesn't
+ * keep the table from being added: Add asks the engine again.
+ */
+export const CubeTablePreview: React.FC<{
+  /** The table's name, as the list shows it */
+  name: string;
+  /** Its columns, or why they couldn't be read; `undefined` while they load */
+  columns: Schema | string | undefined;
+}> = ({ name, columns }) => (
+  <section
+    className="flex max-h-48 flex-col gap-1 overflow-auto rounded-sm border border-[var(--color-border-default)] p-2"
+    aria-label="Table preview"
+  >
+    <span className="font-medium">{`Columns of ${name}`}</span>
+    {columns === undefined ? (
+      <span className="text-base text-[var(--color-text-secondary)]">
+        loading columns
+      </span>
+    ) : typeof columns === 'string' ? (
+      <span className="text-base text-[var(--color-status-error)]">
+        {columns}
+      </span>
+    ) : (
+      <CubeSchemaColumnsTable schema={columns} />
+    )}
+  </section>
+);

package/src/components/spec-transfer/CubeImportPureDialog.tsx

@@ -0,0 +1,122 @@
+/**
+ * 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 {
+  Dialog,
+  Modal,
+  ModalBody,
+  ModalFooter,
+  ModalFooterButton,
+  ModalHeader,
+  PanelLoadingIndicator,
+} from '@finos/legend-art';
+import { flowResult } from 'mobx';
+import { observer } from 'mobx-react-lite';
+import { LEGEND_CUBE_TEST_ID } from '../../__lib__/LegendCubeTesting.js';
+import type { CubeEditorState } from '../../stores/CubeEditorState.js';
+import { CUBE_PRIMARY_BUTTON_DARK_MODE } from '../CubeDialogTheme.js';
+
+const TEXT_AREA_CLASS_NAME =
+  'h-80 w-full resize-none rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] p-1 font-mono text-sm text-[var(--color-text-primary)]';
+
+/**
+ * Import Pure (PLAN §11.18): a lambda pasted as Pure, as Show Pure shows one,
+ * or as the engine's JSON, read into the steps Cube writes it with, in
+ * place of this cube
+ */
+export const CubeImportPureDialog = observer(
+  (props: { editorState: CubeEditorState }) => {
+    const { editorState } = props;
+    const { lambdaImport } = editorState;
+    const { applicationStore } = editorState.host;
+    const darkMode =
+      !applicationStore.layoutService.TEMPORARY__isLightColorThemeEnabled;
+    const importText = (): void => {
+      flowResult(lambdaImport.importText()).catch(
+        applicationStore.alertUnhandledError,
+      );
+    };
+    return (
+      <Dialog
+        open={lambdaImport.isDialogOpen}
+        onClose={() => lambdaImport.closeDialog()}
+      >
+        <Modal darkMode={darkMode} className="w-[720px] max-w-full">
+          <ModalHeader>
+            <div className="modal__title">Import Pure</div>
+          </ModalHeader>
+          <PanelLoadingIndicator isLoading={lambdaImport.isImporting} />
+          <ModalBody>
+            <div
+              className="flex flex-col gap-2"
+              data-testid={LEGEND_CUBE_TEST_ID.IMPORT_PURE}
+            >
+              <div className="text-base text-[var(--color-text-secondary)]">
+                Paste a query, as Show Pure shows one, e.g.{' '}
+                <code>
+                  {'|#>{db::Store.SCHEMA.TABLE}#->filter(x | $x.ID > 1)'}
+                </code>
+                , or its JSON. Cube reads it into steps that replace this cube;
+                Undo brings it back. Its sources are read where the source
+                dialog reads them.
+              </div>
+              <textarea
+                className={TEXT_AREA_CLASS_NAME}
+                aria-label="Pure query"
+                placeholder="Pure query"
+                spellCheck={false}
+                value={lambdaImport.text}
+                onChange={(event) => lambdaImport.setText(event.target.value)}
+              />
+              {lambdaImport.dialogError !== undefined && (
+                <div
+                  className="break-words text-base text-[var(--color-status-error)]"
+                  role="alert"
+                >
+                  {lambdaImport.dialogError.message}
+                  {lambdaImport.dialogError.detail !== undefined && (
+                    <details>
+                      <summary className="cursor-pointer">Details</summary>
+                      <pre className="whitespace-pre-wrap text-sm">
+                        {lambdaImport.dialogError.detail}
+                      </pre>
+                    </details>
+                  )}
+                </div>
+              )}
+            </div>
+          </ModalBody>
+          <ModalFooter>
+            <ModalFooterButton
+              darkMode={CUBE_PRIMARY_BUTTON_DARK_MODE}
+              formatText={false}
+              text="Import"
+              disabled={!lambdaImport.text.trim() || lambdaImport.isImporting}
+              onClick={importText}
+            />
+            <ModalFooterButton
+              darkMode={darkMode}
+              formatText={false}
+              type="secondary"
+              text="Cancel"
+              onClick={() => lambdaImport.closeDialog()}
+            />
+          </ModalFooter>
+        </Modal>
+      </Dialog>
+    );
+  },
+);

package/src/components/spec-transfer/CubeSpecTransferDialog.tsx

@@ -23,10 +23,15 @@ import {
   ModalHeader,
   PanelLoadingIndicator,
 } from '@finos/legend-art';
+import { CodeEditor } from '@finos/legend-lego/code-editor';
 import { flowResult } from 'mobx';
 import { observer } from 'mobx-react-lite';
 import type { CubeEditorState } from '../../stores/CubeEditorState.js';
 import { CUBE_SPEC_TRANSFER_MODE } from '../../stores/CubeSpecTransferState.js';
+import { CUBE_PRIMARY_BUTTON_DARK_MODE } from '../CubeDialogTheme.js';
+
+/** The code editor's language: legend-code-editor's `CODE_EDITOR_LANGUAGE.JSON` */
+const JSON_LANGUAGE = 'json';
 
 const TEXT_AREA_CLASS_NAME =
   'h-80 w-full resize-none rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] p-1 font-mono text-sm text-[var(--color-text-primary)]';
@@ -60,12 +65,20 @@ export const CubeSpecTransferDialog = observer(
             <div className="flex flex-col gap-2">
               {isExport ? (
                 transfer.exportText !== undefined && (
-                  <textarea
-                    className={TEXT_AREA_CLASS_NAME}
+                  // a code editor, so each object and list folds from the gutter
+                  <div
+                    className="h-80 w-full overflow-hidden rounded-sm border border-[var(--color-border-default)]"
                     aria-label="Cube spec"
-                    readOnly={true}
-                    value={transfer.exportText}
-                  />
+                  >
+                    <CodeEditor
+                      inputValue={transfer.exportText}
+                      language={JSON_LANGUAGE}
+                      isReadOnly={true}
+                      hideMinimap={true}
+                      hideActionBar={true}
+                      extraEditorOptions={{ scrollBeyondLastLine: false }}
+                    />
+                  </div>
                 )
               ) : (
                 <>
@@ -115,7 +128,7 @@ export const CubeSpecTransferDialog = observer(
             {isExport ? (
               <>
                 <ModalFooterButton
-                  darkMode={darkMode}
+                  darkMode={CUBE_PRIMARY_BUTTON_DARK_MODE}
                   formatText={false}
                   text="Copy"
                   disabled={transfer.exportText === undefined}
@@ -126,7 +139,7 @@ export const CubeSpecTransferDialog = observer(
                   }}
                 />
                 <ModalFooterButton
-                  darkMode={darkMode}
+                  darkMode={CUBE_PRIMARY_BUTTON_DARK_MODE}
                   formatText={false}
                   text="Download"
                   disabled={transfer.exportText === undefined}
@@ -135,7 +148,7 @@ export const CubeSpecTransferDialog = observer(
               </>
             ) : (
               <ModalFooterButton
-                darkMode={darkMode}
+                darkMode={CUBE_PRIMARY_BUTTON_DARK_MODE}
                 formatText={false}
                 text="Import"
                 disabled={!transfer.importText.trim() || transfer.isReadingFile}

package/src/graph-manager/CubeDataProductCatalog.ts

@@ -15,6 +15,7 @@
  */
 
 import type { Schema } from '@finos/legend-cube';
+import type { PlainObject } from '@finos/legend-shared';
 import {
   type CubeDataProductEnvironmentType,
   type CubeDataProductProject,
@@ -243,3 +244,13 @@ export interface CubeDataProductCatalog {
     signal?: AbortSignal,
   ): Promise<ReadonlyMap<string, CubeAccessPointGroupAccess>>;
 }
+
+/**
+ * Where a data product cube's engine reads the project its data products
+ * are in, as protocol JSON: by default the project at the version they were
+ * deployed from (a pointer); a host's own, e.g. Studio's workspace, whose
+ * data products aren't deployed. Fails with a `CubeEngineError`
+ */
+export interface CubeDataProductModelSource {
+  getProjectModel(project: CubeDataProductProject): Promise<PlainObject>;
+}

package/src/graph-manager/CubeEngine.ts

@@ -84,10 +84,45 @@ export interface CubeOutlineRuntime {
   readonly connections?: readonly CubeOutlineConnection[];
 }
 
-/** What a model offers the source picker: its databases and runtimes, as plain data */
+/** A parameter of a function, as its signature declares it */
+export interface CubeOutlineFunctionParameter {
+  readonly name: string;
+  /** Its type's path, as written, e.g. `Float` */
+  readonly type: string;
+  /** Its multiplicity, as written, e.g. `[1]`, `[0..1]` or `[*]` */
+  readonly multiplicity: string;
+}
+
+/** A column a function declares it returns, e.g. `ID:Integer` */
+export interface CubeOutlineFunctionColumn {
+  readonly name: string;
+  readonly type: string;
+}
+
+/** A function of a model that returns a relation (PLAN §6.5), as plain data */
+export interface CubeOutlineFunction {
+  /** The path the lambda calls it by, e.g. `sales::ordersAbove` */
+  readonly path: string;
+  /** The engine's full name, e.g. `sales::ordersAbove_Float_1__Relation_1_` */
+  readonly signature: string;
+  readonly parameters: readonly CubeOutlineFunctionParameter[];
+  readonly columns: readonly CubeOutlineFunctionColumn[];
+  /**
+   * The runtime it reads through, as its body's `from()` names it, directly
+   * or through a function it calls; none when it leaves the runtime to its
+   * caller
+   */
+  readonly runtime?: string | undefined;
+  /** Why it can't be added, e.g. a parameter Cube can't take a value for */
+  readonly problem?: string | undefined;
+}
+
+/** What a model offers the source picker: its databases, runtimes and functions, as plain data */
 export interface CubeModelOutline {
   readonly databases: readonly CubeOutlineDatabase[];
   readonly runtimes: readonly CubeOutlineRuntime[];
+  /** Its functions that return a relation; optional, as an outline from before them has none */
+  readonly functions?: readonly CubeOutlineFunction[] | undefined;
 }
 
 export enum CubeEngineErrorKind {
@@ -192,8 +227,23 @@ export interface CubeEngine {
     lambda: IR,
     options?: { abortController?: AbortController | undefined },
   ): Promise<CubeResult>;
+  /**
+   * Runs an execution lambda and gives its rows as CSV text (PLAN §11.10):
+   * the engine's own, a header row first, every value as the engine writes
+   * it; rejects with a `CubeEngineError`
+   */
+  exportCsv(
+    model: ModelContext,
+    lambda: IR,
+    options?: { abortController?: AbortController | undefined },
+  ): Promise<string>;
   /** The Pure text of a lambda, for display only: never parsed back */
   renderPure(lambda: IR): Promise<string>;
+  /**
+   * A lambda as the engine receives it, pretty-printed, its numbers kept
+   * exact (PLAN §11.16): for a viewer to copy while debugging a run
+   */
+  serializeLambda(lambda: IR): string;
   /**
    * An Extend column's expression as the engine's JSON (PLAN §11.7), located
    * under the source id; rejects with a `CubeEngineError` placed in the text

package/src/graph-manager/CubeEngineClientSettings.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+
+/** What Dev Settings changes on an engine client: the engine server client's own setters */
+export interface CubeEngineClientControls {
+  setBaseUrl(url: string | undefined): void;
+  setCompression(enabled: boolean): void;
+}
+
+/**
+ * The settings every engine client of Cube shares (PLAN §11.16): the
+ * engine's URL and whether requests are compressed. The engine, the
+ * connection explorer and the catalogs each have their own client, built
+ * from the same configuration; each registers here, so Dev Settings changes
+ * them all at once. A change takes effect from the next request.
+ */
+export class CubeEngineClientSettings {
+  /** The URL the host configured, to go back to */
+  readonly defaultBaseUrl: string | undefined;
+  baseUrl: string | undefined;
+  requestCompression: boolean;
+  private readonly clients: CubeEngineClientControls[] = [];
+
+  constructor(config: {
+    readonly baseUrl?: string | undefined;
+    readonly enableCompression?: boolean | undefined;
+  }) {
+    this.defaultBaseUrl = config.baseUrl;
+    this.baseUrl = config.baseUrl;
+    this.requestCompression = Boolean(config.enableCompression);
+  }
+
+  /** Adds a client built from the same configuration, given the settings changed since */
+  register(client: CubeEngineClientControls): void {
+    this.clients.push(client);
+    if (this.baseUrl !== this.defaultBaseUrl) {
+      client.setBaseUrl(this.baseUrl);
+    }
+    client.setCompression(this.requestCompression);
+  }
+
+  setBaseUrl(url: string | undefined): void {
+    this.baseUrl = url;
+    this.clients.forEach((client) => client.setBaseUrl(url));
+  }
+
+  setRequestCompression(enabled: boolean): void {
+    this.requestCompression = enabled;
+    this.clients.forEach((client) => client.setCompression(enabled));
+  }
+}

package/src/graph-manager/CubeIngest.ts

@@ -118,6 +118,21 @@ export interface CubeIngestUrn {
   readonly definition: string;
 }
 
+/** The URN's environment segment of each class */
+const URN_ENVIRONMENTS: Readonly<
+  Record<CubeDataProductEnvironmentType, string>
+> = {
+  [CubeDataProductEnvironmentType.PRODUCTION]: 'prod',
+  [CubeDataProductEnvironmentType.PRODUCTION_PARALLEL]: 'prod-parallel',
+};
+
+/**
+ * The URN of a definition deployed from SDLC, as `parseCubeIngestUrn` reads
+ * it: for a host naming definitions of its own, e.g. Studio's workspace
+ */
+export const formatCubeIngestUrn = (urn: CubeIngestUrn): string =>
+  `urn:lakehouse:${URN_ENVIRONMENTS[urn.environmentType]}:ingest:definition:alloy-git:${urn.groupId}~${urn.artifactId}~${urn.definition}`;
+
 const SDLC_DEPLOYED_URN =
   /^urn:lakehouse:(?<environment>[^:]+):ingest:definition:alloy-git:(?<groupId>[^~]+)~(?<artifactId>[^~]+)~(?<definition>.+)$/u;