@oceanum/oceanumlab 4.7.2 → 4.8.0

package/src/__tests__/shareClient.spec.ts

@@ -95,6 +95,20 @@ describe('SpecStoreClient', () => {
     expect(call().headers).toEqual({});
   });
 
+  it('reads another spec type when given one', async () => {
+    const fetch = jest.fn(async () => json(record()));
+    const client = new SpecStoreClient({
+      specsUrl: 'https://specs.example.com/',
+      getAccessToken: async () => 'tok',
+      specType: 'notebook-demo',
+      fetch: fetch as unknown as typeof globalThis.fetch
+    });
+    await client.get(ID);
+    expect(String((fetch.mock.calls[0] as unknown[])[0])).toBe(
+      `https://specs.example.com/specs/notebook-demo/${ID}`
+    );
+  });
+
   it('refuses ids that are not UUIDs before building a URL', async () => {
     const { client, fetch } = setup(() => json(record()));
     await expect(client.get('../eidos')).rejects.toMatchObject({

package/src/__tests__/shareNotebook.spec.ts

@@ -6,6 +6,8 @@ import {
   isSpecId,
   nameFromPath,
   notebookFromRecord,
+  notebookFromUpload,
+  parseNotebookDemo,
   parseShareEmails,
   parseTimestamp,
   partitionSummaries,
@@ -14,6 +16,7 @@ import {
   sanitizeName,
   shareLink,
   uniqueNotebookPath,
+  unlinkedNotebookFromRecord,
   withoutTrust
 } from '../share/notebook';
 
@@ -185,6 +188,132 @@ describe('notebookFromRecord', () => {
   });
 });
 
+describe('unlinkedNotebookFromRecord', () => {
+  const base = {
+    id: ID,
+    name: 'Waves',
+    description: 'Wave stats',
+    modified: '2026-09-12T10:00:00',
+    creator: null as string | null
+  };
+
+  it('links the copy to nothing, even when the stored notebook carries a link', () => {
+    const spec = notebook('', { oceanum: { spec_id: ID, specs_url: SPECS } });
+    const content = unlinkedNotebookFromRecord({ ...base, spec });
+    expect(content.metadata).not.toHaveProperty('oceanum');
+    expect(content.metadata.kernelspec).toBeDefined();
+    expect(content.cells).toHaveLength(2);
+  });
+
+  it('arrives untrusted', () => {
+    const spec = notebook();
+    spec.cells[1].metadata = { trusted: true, tags: ['keep'] };
+    const content = unlinkedNotebookFromRecord({ ...base, spec });
+    expect(content.cells[1].metadata).toEqual({ tags: ['keep'] });
+  });
+
+  it('rejects records that are not notebooks', () => {
+    expect(() =>
+      unlinkedNotebookFromRecord({ ...base, spec: { nbformat: 3 } })
+    ).toThrow(/not a valid notebook/);
+  });
+});
+
+describe('parseNotebookDemo', () => {
+  const OTHER = '0b7d9f2e-1111-4a2b-8c3d-9e8f7a6b5c4d';
+  const demo = (sections: unknown, extra: object = {}): unknown => ({
+    kind: 'notebook-demo',
+    version: 1,
+    sections,
+    ...extra
+  });
+
+  let warn: jest.SpyInstance;
+  beforeEach(() => {
+    warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+  });
+  afterEach(() => {
+    warn.mockRestore();
+  });
+
+  it('keeps sections and items in record order', () => {
+    const sections = parseNotebookDemo(
+      demo(
+        [
+          {
+            title: 'Getting started',
+            items: [
+              { id: ID, title: 'Query', summary: 'One line' },
+              { id: OTHER, title: 'Plot', note: 'ignored' }
+            ]
+          },
+          { title: 'Waves', items: [{ id: OTHER, title: 'Spectra' }] }
+        ],
+        { owner: 'ignored' }
+      )
+    );
+    expect(sections).toEqual([
+      {
+        title: 'Getting started',
+        items: [
+          { id: ID, title: 'Query', summary: 'One line' },
+          { id: OTHER, title: 'Plot' }
+        ]
+      },
+      { title: 'Waves', items: [{ id: OTHER, title: 'Spectra' }] }
+    ]);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('skips items without a record id or a title', () => {
+    const sections = parseNotebookDemo(
+      demo([
+        {
+          title: 'Mixed',
+          items: [
+            { id: '../eidos', title: 'Not a record id' },
+            { id: ID, title: '   ' },
+            { id: ID },
+            'not an item',
+            { id: OTHER, title: 'Kept', summary: 42 }
+          ]
+        }
+      ])
+    );
+    expect(sections).toEqual([
+      { title: 'Mixed', items: [{ id: OTHER, title: 'Kept' }] }
+    ]);
+  });
+
+  it('drops sections with no title or nothing left to list', () => {
+    const sections = parseNotebookDemo(
+      demo([
+        { title: 'Empty', items: [] },
+        { title: 'All invalid', items: [{ id: 'x', title: 'y' }] },
+        { title: '', items: [{ id: ID, title: 'Untitled section' }] },
+        { title: 'No items' }
+      ])
+    );
+    expect(sections).toEqual([]);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('reads nothing from a record of another kind or version, and says so once', () => {
+    for (const spec of [
+      demo([], { kind: 'workspace' }),
+      demo([], { version: 2 }),
+      { kind: 'notebook-demo', version: 1, sections: {} },
+      null,
+      [],
+      'notebook-demo'
+    ]) {
+      warn.mockClear();
+      expect(parseNotebookDemo(spec)).toEqual([]);
+      expect(warn).toHaveBeenCalledTimes(1);
+    }
+  });
+});
+
 describe('names and paths', () => {
   it('derives the record name from a path', () => {
     expect(nameFromPath('Oceanum/Waves.ipynb')).toBe('Waves');
@@ -449,3 +578,47 @@ describe('reportForShareFailures', () => {
     });
   });
 });
+
+describe('notebookFromUpload', () => {
+  const linkedAndTrusted: INotebookContent = {
+    nbformat: 4,
+    nbformat_minor: 5,
+    metadata: {
+      oceanum: { spec_id: ID, specs_url: SPECS },
+      kernelspec: { name: 'python', display_name: 'Python' }
+    },
+    cells: [
+      { cell_type: 'markdown', source: 'hi', metadata: { trusted: true } }
+    ]
+  };
+
+  it('drops the oceanum link and cell trust, and keeps everything else', () => {
+    const content = notebookFromUpload(JSON.stringify(linkedAndTrusted));
+
+    expect(content.metadata).toEqual({
+      kernelspec: { name: 'python', display_name: 'Python' }
+    });
+    expect(content.cells).toEqual([
+      { cell_type: 'markdown', source: 'hi', metadata: {} }
+    ]);
+  });
+
+  it.each([
+    ['text that is not JSON', '{'],
+    ['a JSON array', '[]'],
+    ['nbformat 3', JSON.stringify({ ...linkedAndTrusted, nbformat: 3 })],
+    ['no cells', JSON.stringify({ nbformat: 4, metadata: {} })],
+    ['no metadata', JSON.stringify({ nbformat: 4, cells: [] })],
+    [
+      'a cell that is not a cell',
+      JSON.stringify({ nbformat: 4, metadata: {}, cells: [null, {}] })
+    ]
+  ])('refuses %s, without quoting the file', (_, text) => {
+    expect(() => notebookFromUpload(text)).toThrow(/not a Jupyter notebook/);
+    try {
+      notebookFromUpload(text);
+    } catch (error) {
+      expect((error as Error).message).not.toContain(text);
+    }
+  });
+});

package/src/__tests__/sharePlugin.spec.ts

@@ -43,8 +43,24 @@ jest.mock('@jupyterlab/apputils', () => {
   };
 });
 
+/** What the file picker answers: a file, or null for a cancelled picker. */
+const mockPicked: { file: { name: string; text: string } | null } = {
+  file: null
+};
+const mockPickerCalls = { count: 0 };
+
+jest.mock('../share/upload', () => ({
+  chooseNotebookFile: async () => {
+    mockPickerCalls.count++;
+    const picked = mockPicked.file;
+    return picked && { name: picked.name, text: async () => picked.text };
+  }
+}));
+
 const originalFetch = globalThis.fetch;
 afterEach(() => {
+  mockPicked.file = null;
+  mockPickerCalls.count = 0;
   globalThis.fetch = originalFetch;
   mockDialog.accept = true;
   mockDialog.value = null;
@@ -78,8 +94,11 @@ const record = (id: string, name: string): ISpecRecord => ({
   spec: notebook()
 });
 
-/** Records the spec store calls a command makes, and answers them. */
-function store() {
+/**
+ * Records the spec store calls a command makes, and answers them. A record holds
+ * `stored[id]` when given, else an empty notebook.
+ */
+function store(stored: Record<string, INotebookContent> = {}) {
   const calls: string[] = [];
   const bodies: Record<string, unknown>[] = [];
   const names: Record<string, string> = { [ID_A]: 'Alpha', [ID_B]: 'Beta' };
@@ -100,7 +119,10 @@ function store() {
       json: async () =>
         method === 'GET' && id === 'notebook'
           ? [record(ID_A, 'Alpha'), record(ID_B, 'Beta')]
-          : record(id, names[id] ?? 'Alpha')
+          : {
+              ...record(id, names[id] ?? 'Alpha'),
+              spec: stored[id] ?? notebook()
+            }
     } as unknown as Response;
   };
   return { calls, bodies, fetcher };
@@ -139,7 +161,12 @@ interface IHarness {
   calls: string[];
   bodies: Record<string, unknown>[];
   saved: string[];
+  /** What each save wrote, by path. */
+  written: Record<string, unknown>;
   opened: string[];
+  /** The widgets `openOrReveal` returned, in order; set `isDisposed` to close one. */
+  widgets: { id: string; isDisposed: boolean }[];
+  activated: string[];
   renamed: [string, string][];
   /** What a right-click last landed on; never cleared, as JupyterLab does not. */
   setHit: (node: HTMLElement | null) => void;
@@ -152,12 +179,16 @@ function activate(
     panels?: NotebookPanel[];
     current?: NotebookPanel | null;
     folder?: Record<string, unknown>;
+    stored?: Record<string, INotebookContent>;
   } = {}
 ): IHarness {
   const commands = new CommandRegistry();
-  const { calls, bodies, fetcher } = store();
+  const { calls, bodies, fetcher } = store(options.stored);
   const saved: string[] = [];
+  const written: Record<string, unknown> = {};
   const opened: string[] = [];
+  const widgets: { id: string; isDisposed: boolean }[] = [];
+  const activated: string[] = [];
   const renamed: [string, string][] = [];
   const panels = options.panels ?? [];
   let current = options.current ?? null;
@@ -185,7 +216,9 @@ function activate(
       get currentWidget() {
         return current;
       },
-      activateById: (): void => undefined,
+      activateById: (id: string): void => {
+        activated.push(id);
+      },
       widgets: (): Widget[] => []
     },
     contextMenu: { addItem: (): void => undefined },
@@ -213,8 +246,13 @@ function activate(
       }
       return { type: 'notebook', content: folder[name] };
     },
-    save: async (path: string) => {
+    save: async (path: string, model?: { content?: unknown }) => {
       saved.push(path);
+      written[path] = model?.content;
+      // Like the real drive, the folder lists the file from now on.
+      if (path.startsWith('Oceanum/')) {
+        folder[path.replace('Oceanum/', '')] = model?.content;
+      }
       return { path };
     },
     newUntitled: async () => ({ path: 'Untitled Folder' }),
@@ -224,7 +262,9 @@ function activate(
     services: { contents },
     openOrReveal: (path: string) => {
       opened.push(path);
-      return {};
+      const widget = { id: `widget-${widgets.length}`, isDisposed: false };
+      widgets.push(widget);
+      return widget;
     },
     rename: async (from: string, to: string): Promise<void> => {
       renamed.push([from, to]);
@@ -265,7 +305,10 @@ function activate(
     calls,
     bodies,
     saved,
+    written,
     opened,
+    widgets,
+    activated,
     renamed,
     setHit: node => {
       hit = node;
@@ -424,3 +467,198 @@ describe('opening a record whose local copy already exists', () => {
     expect(harness.saved).toEqual(['Oceanum/Alpha (1).ipynb']);
   });
 });
+
+describe('opening an example', () => {
+  // As stored on Oceanum: linked to its own record, with a trusted cell.
+  const example: INotebookContent = {
+    ...notebook(ID_A),
+    cells: [
+      {
+        cell_type: 'code',
+        source: 'print(1)',
+        metadata: { trusted: true },
+        outputs: [],
+        execution_count: null
+      }
+    ]
+  };
+
+  it('writes an untrusted copy linked to nothing, named from its title', async () => {
+    const harness = activate({ stored: { [ID_A]: example } });
+
+    await harness.commands.execute(CommandIDs.openExample, {
+      id: ID_A,
+      title: 'Query a datasource'
+    });
+
+    // Read, never written back: the example's record is Oceanum's.
+    expect(harness.calls).toEqual([`GET ${ID_A}`]);
+    const path = 'Oceanum/Query a datasource.ipynb';
+    expect(harness.saved).toEqual([path]);
+    expect(harness.opened).toEqual([path]);
+    const content = harness.written[path] as INotebookContent;
+    // A linked copy's first save would PUT to the example's record and be refused.
+    expect(content.metadata).not.toHaveProperty('oceanum');
+    expect(content.cells[0].metadata).toEqual({});
+  });
+
+  it('never overwrites a file already there', async () => {
+    const harness = activate({
+      folder: { 'Query a datasource.ipynb': notebook() }
+    });
+
+    await harness.commands.execute(CommandIDs.openExample, {
+      id: ID_A,
+      title: 'Query a datasource'
+    });
+
+    expect(harness.saved).toEqual(['Oceanum/Query a datasource (1).ipynb']);
+  });
+
+  it('brings its open copy forward instead of writing another', async () => {
+    const harness = activate();
+    const args = { id: ID_A, title: 'Example' };
+
+    await harness.commands.execute(CommandIDs.openExample, args);
+    await harness.commands.execute(CommandIDs.openExample, args);
+
+    expect(harness.saved).toEqual(['Oceanum/Example.ipynb']);
+    expect(harness.activated).toEqual([harness.widgets[0].id]);
+  });
+
+  it('writes one copy when opened twice before the first finishes', async () => {
+    const harness = activate();
+    const args = { id: ID_A, title: 'Example' };
+
+    await Promise.all([
+      harness.commands.execute(CommandIDs.openExample, args),
+      harness.commands.execute(CommandIDs.openExample, args)
+    ]);
+
+    expect(harness.saved).toEqual(['Oceanum/Example.ipynb']);
+  });
+
+  it('writes a fresh copy once the last one was closed', async () => {
+    const harness = activate();
+    const args = { id: ID_A, title: 'Example' };
+
+    await harness.commands.execute(CommandIDs.openExample, args);
+    harness.widgets[0].isDisposed = true;
+    await harness.commands.execute(CommandIDs.openExample, args);
+
+    expect(harness.saved).toEqual([
+      'Oceanum/Example.ipynb',
+      'Oceanum/Example (1).ipynb'
+    ]);
+    expect(harness.activated).toEqual([]);
+  });
+
+  it('falls back to the record name when given no title', async () => {
+    const harness = activate();
+
+    await harness.commands.execute(CommandIDs.openExample, { id: ID_A });
+
+    expect(harness.saved).toEqual(['Oceanum/Alpha.ipynb']);
+  });
+
+  it('ignores an id that is not a record id', async () => {
+    const harness = activate();
+
+    await harness.commands.execute(CommandIDs.openExample, {
+      id: '../eidos',
+      title: 'Nope'
+    });
+
+    expect(harness.calls).toEqual([]);
+    expect(harness.saved).toEqual([]);
+  });
+
+  it('is disabled while signed out', () => {
+    const harness = activate({ user: null });
+
+    expect(harness.commands.isEnabled(CommandIDs.openExample)).toBe(false);
+  });
+});
+
+describe('uploading a notebook', () => {
+  // As downloaded from someone else's record: linked to it, with a trusted cell.
+  const downloaded: INotebookContent = {
+    ...notebook(ID_B),
+    cells: [
+      {
+        cell_type: 'code',
+        source: 'print(1)',
+        metadata: { trusted: true },
+        outputs: [],
+        execution_count: null
+      }
+    ]
+  };
+
+  it('writes an untrusted copy linked to nothing into the Oceanum folder, and opens it', async () => {
+    mockPicked.file = {
+      name: 'analysis.ipynb',
+      text: JSON.stringify(downloaded)
+    };
+    const harness = activate();
+
+    await harness.commands.execute(CommandIDs.upload);
+
+    const path = 'Oceanum/analysis.ipynb';
+    expect(harness.saved).toEqual([path]);
+    expect(harness.opened).toEqual([path]);
+    const content = harness.written[path] as INotebookContent;
+    // Linked, its first save would write over the record it was downloaded from.
+    expect(content.metadata).not.toHaveProperty('oceanum');
+    expect(content.cells[0].metadata).toEqual({});
+    // Nothing reaches Oceanum until the notebook is saved.
+    expect(harness.calls).toEqual([]);
+  });
+
+  it('never overwrites a file already there', async () => {
+    mockPicked.file = {
+      name: 'analysis.ipynb',
+      text: JSON.stringify(notebook())
+    };
+    const harness = activate({ folder: { 'analysis.ipynb': notebook() } });
+
+    await harness.commands.execute(CommandIDs.upload);
+
+    expect(harness.saved).toEqual(['Oceanum/analysis (1).ipynb']);
+  });
+
+  it.each([
+    ['not JSON', 'not json at all'],
+    ['JSON that is not a notebook', JSON.stringify({ cells: [] })],
+    ['an nbformat 3 notebook', JSON.stringify({ ...notebook(), nbformat: 3 })]
+  ])('writes nothing for %s', async (_, text) => {
+    mockPicked.file = { name: 'bad.ipynb', text };
+    const harness = activate();
+
+    await harness.commands.execute(CommandIDs.upload);
+
+    expect(harness.saved).toEqual([]);
+    expect(harness.opened).toEqual([]);
+  });
+
+  it('writes nothing when the picker is cancelled', async () => {
+    const harness = activate();
+
+    await harness.commands.execute(CommandIDs.upload);
+
+    expect(mockPickerCalls.count).toBe(1);
+    expect(harness.saved).toEqual([]);
+  });
+
+  it('asks for sign-in first, and writes nothing when declined', async () => {
+    mockPicked.file = { name: 'a.ipynb', text: JSON.stringify(notebook()) };
+    mockDialog.accept = false;
+    const harness = activate({ user: null });
+
+    await harness.commands.execute(CommandIDs.upload);
+
+    expect(mockPickerCalls.count).toBe(0);
+    expect(harness.saved).toEqual([]);
+    expect(harness.commands.isEnabled(CommandIDs.upload)).toBe(false);
+  });
+});

package/src/auth/tokens.ts

@@ -32,6 +32,12 @@ export interface IOceanumEnvironment {
    * absent) keeps JupyterLab's file management alongside the Oceanum commands.
    */
   readonly fileManagement?: 'local' | 'oceanum';
+  /**
+   * The spec store id of this deployment's Notebook Demo record, the curated list the
+   * Notebooks tab shows as Examples. Absent where a deployment has none, and never set
+   * by a JupyterLab server's sign-in.
+   */
+  readonly notebookDemo?: string;
 }
 
 /** Service base URLs for an environment, without trailing slashes. */

package/src/index.ts

@@ -21,6 +21,7 @@ import { ConversationPin } from './conversationPin';
 import { deviceAuthPlugin } from './auth/plugin';
 import { IOceanumAuth } from './auth/tokens';
 import { CommandIDs as ShareCommandIDs, sharePlugin } from './share/plugin';
+import { OCEANUM_PANEL_ID } from './share/oceanumOnly';
 
 import { snapshotFromIpynb, snapshotOf } from './notebookContext';
 import { notebookHost } from './notebookHost';
@@ -79,6 +80,9 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
     const aiBackendUrl = auth?.urls?.ai ?? OCEANUM_AI_BACKEND_URL;
     // The `datameshToken` setting for the AI chat; empty until the settings load.
     let datameshTokenSetting = '';
+    // The `showExamples` setting for the Notebooks tab; null until the settings load, so
+    // examples a user has hidden do not show for a moment on every reload.
+    let showExamplesSetting: boolean | null = null;
     // Tells the sidebar the settings above have changed.
     const settingsChanged = new Signal<JupyterFrontEnd, void>(app);
 
@@ -100,6 +104,7 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
       }
       window.injectToken = set.get('injectToken').user as boolean;
       datameshTokenSetting = set.get('datameshToken').composite as string;
+      showExamplesSetting = set.get('showExamples').composite as boolean;
       settingsChanged.emit();
     };
     //Try to get the datamesh token from the envars
@@ -116,6 +121,10 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
         console.error(
           `Something went wrong when reading the Oceanumlab settings.\n${reason}`
         );
+        // Unreadable settings fall back to the default rather than leaving the examples
+        // waiting for a value that will never come.
+        showExamplesSetting = true;
+        settingsChanged.emit();
       });
 
     const getCurrentWidget = (): Widget => {
@@ -155,9 +164,34 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
         app.commands.execute(ShareCommandIDs.open, { id }).catch(error => {
           console.error('Oceanum: could not open the stored notebook.', error);
         });
+      },
+      openExample: (id, title) => {
+        app.commands
+          .execute(ShareCommandIDs.openExample, { id, title })
+          .catch(error => {
+            console.error('Oceanum: could not open the example.', error);
+          });
+      },
+      uploadNotebook: () => {
+        app.commands.execute(ShareCommandIDs.upload).catch(error => {
+          console.error('Oceanum: could not upload the notebook.', error);
+        });
+      },
+      showExamples: () => showExamplesSetting,
+      // Saved as a user setting, so the choice outlasts the page; the settings'
+      // `changed` signal brings the new value back to the panel. The registry waits
+      // for the plugin's settings to load, so a click before then is not lost.
+      setShowExamples: show => {
+        settingRegistry.set(PLUGIN_ID, 'showExamples', show).catch(error => {
+          // The switch moves only once the setting is saved, so say why it did not.
+          console.error('Oceanum: could not save the Examples setting.', error);
+          Notification.error('Could not save whether to show the examples.', {
+            autoClose: 5000
+          });
+        });
       }
     });
-    datameshConnectWidget.id = 'datamesh-connect';
+    datameshConnectWidget.id = OCEANUM_PANEL_ID;
     datameshConnectWidget.title.icon = oceanumIcon;
     datameshConnectWidget.title.caption = 'Datamesh Connect';
 

package/src/share/client.ts

@@ -90,6 +90,8 @@ export interface ISpecStoreClientOptions {
   specsUrl: string;
   /** Returns a current access token or `null`. Called for every request. */
   getAccessToken: () => Promise<string | null>;
+  /** The spec type the client reads and writes; `notebook` unless given. */
+  specType?: string;
   fetch?: typeof fetch;
 }
 
@@ -109,10 +111,11 @@ function isRecord(value: unknown): value is ISpecRecord {
   return isSummary(value) && 'spec' in value;
 }
 
-/** Client for the `notebook` spec type of the Oceanum spec store. */
+/** Client for one spec type of the Oceanum spec store, `notebook` by default. */
 export class SpecStoreClient {
   constructor(options: ISpecStoreClientOptions) {
-    this._base = `${options.specsUrl.replace(/\/+$/, '')}/specs/notebook`;
+    const specType = options.specType ?? 'notebook';
+    this._base = `${options.specsUrl.replace(/\/+$/, '')}/specs/${specType}`;
     this._getAccessToken = options.getAccessToken;
     this._fetch = options.fetch ?? ((input, init) => fetch(input, init));
   }