@oceanum/oceanumlab 4.7.1 → 4.8.0

package/src/__tests__/oceanumOnly.spec.ts

@@ -0,0 +1,317 @@
+import type { INotebookTracker, NotebookPanel } from '@jupyterlab/notebook';
+import { CommandRegistry } from '@lumino/commands';
+import { Signal } from '@lumino/signaling';
+import { Menu, Panel, Widget } from '@lumino/widgets';
+
+import {
+  FILE_BROWSER_ID,
+  hideFileBrowser,
+  LOCAL_FILE_COMMANDS,
+  moveToTop,
+  NON_NOTEBOOK_NEW_COMMANDS,
+  OCEANUM_PANEL_ID,
+  pruneBeforeEachOpen,
+  pruneFileMenu,
+  routeSaves
+} from '../share/oceanumOnly';
+
+describe('hideFileBrowser', () => {
+  /** A left area holding the file browser and the running-sessions panel. */
+  function leftArea(): { left: Panel; browser: Widget; running: Widget } {
+    const left = new Panel();
+    const browser = new Widget();
+    browser.id = FILE_BROWSER_ID;
+    const running = new Widget();
+    running.id = 'jp-running-sessions';
+    left.addWidget(browser);
+    left.addWidget(running);
+    return { left, browser, running };
+  }
+
+  function shell(left: Panel) {
+    const activated: string[] = [];
+    return {
+      activated,
+      widgets: () => left.widgets,
+      activateById: (id: string): void => {
+        activated.push(id);
+      }
+    };
+  }
+
+  it('closes the file browser without disposing it, and leaves the rest', () => {
+    const { left, browser, running } = leftArea();
+
+    expect(hideFileBrowser(shell(left))).toBe(true);
+
+    expect(left.widgets).toEqual([running]);
+    // Other extensions still hold it through IDefaultFileBrowser.
+    expect(browser.isDisposed).toBe(false);
+  });
+
+  it('reports when there is none to hide', () => {
+    const left = new Panel();
+    expect(hideFileBrowser(shell(left))).toBe(false);
+  });
+
+  it('opens the replacement when the file browser was the open panel', () => {
+    const { left } = leftArea();
+    Widget.attach(left, document.body);
+    const fake = shell(left);
+
+    hideFileBrowser(fake, OCEANUM_PANEL_ID);
+
+    expect(fake.activated).toEqual([OCEANUM_PANEL_ID]);
+    Widget.detach(left);
+  });
+
+  it('leaves a collapsed sidebar collapsed', () => {
+    const { left, browser } = leftArea();
+    Widget.attach(left, document.body);
+    browser.hide();
+    const fake = shell(left);
+
+    hideFileBrowser(fake, OCEANUM_PANEL_ID);
+
+    expect(fake.activated).toEqual([]);
+    Widget.detach(left);
+  });
+});
+
+function fileMenu(commands: string[]): {
+  menu: Menu;
+  registry: CommandRegistry;
+} {
+  const registry = new CommandRegistry();
+  const menu = new Menu({ commands: registry });
+  for (const command of commands) {
+    if (command === '-') {
+      menu.addItem({ type: 'separator' });
+      continue;
+    }
+    registry.addCommand(command, { execute: () => undefined, label: command });
+    menu.addItem({ command });
+  }
+  return { menu, registry };
+}
+
+const menuCommands = (menu: Menu): string[] =>
+  menu.items.map(item => (item.type === 'separator' ? '-' : item.command));
+
+describe('pruneFileMenu', () => {
+  it('drops the local-file entries and keeps Save, Rename and everything else', () => {
+    const { menu } = fileMenu([
+      'filebrowser:open-path',
+      'filebrowser:open-url',
+      '-',
+      'docmanager:save',
+      'docmanager:save-as',
+      'docmanager:save-all',
+      '-',
+      'docmanager:reload',
+      'docmanager:restore-checkpoint',
+      'docmanager:rename',
+      'docmanager:duplicate',
+      '-',
+      'docmanager:download',
+      'oceanum-share:save'
+    ]);
+
+    expect(pruneFileMenu(menu)).toBe(7);
+
+    expect(menuCommands(menu)).toEqual([
+      '-',
+      'docmanager:save',
+      'docmanager:save-all',
+      '-',
+      'docmanager:rename',
+      '-',
+      'oceanum-share:save'
+    ]);
+    // Idempotent: nothing left to remove.
+    expect(pruneFileMenu(menu)).toBe(0);
+  });
+
+  it('drops the Open Recent submenu, which the document manager builds by hand', () => {
+    const { menu, registry } = fileMenu(['docmanager:save']);
+    registry.addCommand('docmanager:clear-recents', {
+      execute: () => undefined,
+      label: 'Clear Recent'
+    });
+    const recents = new Menu({ commands: registry });
+    recents.title.label = 'Open Recent';
+    recents.addItem({ command: 'docmanager:clear-recents' });
+    menu.addItem({ type: 'submenu', submenu: recents });
+    const other = new Menu({ commands: registry });
+    other.title.label = 'New';
+    menu.addItem({ type: 'submenu', submenu: other });
+
+    expect(pruneFileMenu(menu)).toBe(1);
+
+    expect(menu.items.map(item => item.type)).toEqual(['command', 'submenu']);
+    expect(menu.items[1].submenu?.title.label).toBe('New');
+  });
+
+  it('names every entry it prunes, so the list is reviewable', () => {
+    expect(LOCAL_FILE_COMMANDS).toEqual([
+      'filebrowser:open-path',
+      'filebrowser:open-url',
+      'docmanager:save-as',
+      'docmanager:reload',
+      'docmanager:restore-checkpoint',
+      'docmanager:duplicate',
+      'docmanager:download'
+    ]);
+  });
+});
+
+describe('pruneBeforeEachOpen', () => {
+  it('prunes entries that arrive after the first pass, each time the menu opens', () => {
+    const { menu, registry } = fileMenu(['docmanager:save']);
+    pruneBeforeEachOpen(menu);
+    // A plugin's settings schema loads late and adds its entry.
+    registry.addCommand('docmanager:save-as', {
+      execute: () => undefined,
+      label: 'Save As'
+    });
+    menu.addItem({ command: 'docmanager:save-as' });
+    expect(menuCommands(menu)).toEqual([
+      'docmanager:save',
+      'docmanager:save-as'
+    ]);
+
+    menu.open(0, 0);
+    try {
+      expect(menuCommands(menu)).toEqual(['docmanager:save']);
+    } finally {
+      menu.close();
+      menu.dispose();
+    }
+  });
+});
+
+/** Just enough of a notebook tracker and its panels to route saves. */
+function fakeTracker(): {
+  tracker: INotebookTracker;
+  add: () => { panel: NotebookPanel; saveState: Signal<unknown, string> };
+} {
+  const panels: NotebookPanel[] = [];
+  const widgetAdded = new Signal<INotebookTracker, NotebookPanel>(
+    {} as INotebookTracker
+  );
+  const tracker = {
+    forEach: (fn: (panel: NotebookPanel) => void) => panels.forEach(fn),
+    widgetAdded
+  } as unknown as INotebookTracker;
+  const add = () => {
+    const saveState = new Signal<unknown, string>({});
+    const panel = { context: { saveState } } as unknown as NotebookPanel;
+    panels.push(panel);
+    widgetAdded.emit(panel);
+    return { panel, saveState };
+  };
+  return { tracker, add };
+}
+
+describe('routeSaves', () => {
+  it('pushes after every completed save, of notebooks open now and later', () => {
+    const { tracker, add } = fakeTracker();
+    const first = add();
+    const pushed: NotebookPanel[] = [];
+    routeSaves(tracker, async panel => {
+      pushed.push(panel);
+    });
+
+    first.saveState.emit('started');
+    expect(pushed).toEqual([]);
+    first.saveState.emit('completed');
+    expect(pushed).toEqual([first.panel]);
+
+    const second = add();
+    second.saveState.emit('completed');
+    second.saveState.emit('failed');
+    first.saveState.emit('completed');
+    expect(pushed).toEqual([first.panel, second.panel, first.panel]);
+  });
+});
+
+describe('the File > New menu', () => {
+  it('loses the entries for files that are not notebooks', () => {
+    const { menu } = fileMenu([
+      'console:create',
+      'notebook:create-new',
+      ...NON_NOTEBOOK_NEW_COMMANDS
+    ]);
+
+    expect(pruneFileMenu(menu, NON_NOTEBOOK_NEW_COMMANDS)).toBe(2);
+
+    expect(menuCommands(menu)).toEqual([
+      'console:create',
+      'notebook:create-new'
+    ]);
+  });
+});
+
+describe('moveToTop', () => {
+  /** A left area in a saved order, and a shell that re-adds by rank as JupyterLab does. */
+  function sidebar(ids: string[]) {
+    const left = new Panel();
+    for (const id of ids) {
+      const widget = new Widget();
+      widget.id = id;
+      left.addWidget(widget);
+    }
+    Widget.attach(left, document.body);
+    const activated: string[] = [];
+    const added: [string, number][] = [];
+    const shell = {
+      widgets: () => left.widgets,
+      add: (widget: Widget, _: 'left', options: { rank: number }): void => {
+        added.push([widget.id, options.rank]);
+        widget.hide();
+        left.insertWidget(0, widget);
+      },
+      activateById: (id: string): void => {
+        activated.push(id);
+      }
+    };
+    const order = (): string[] => left.widgets.map(widget => widget.id);
+    const get = (id: string): Widget => left.widgets.find(w => w.id === id)!;
+    return { left, shell, activated, added, order, get };
+  }
+
+  it('puts a panel a returning user had last back in front, and reopens it', () => {
+    const bar = sidebar(['jp-running-sessions', OCEANUM_PANEL_ID]);
+    bar.get('jp-running-sessions').hide();
+
+    expect(moveToTop(bar.shell, OCEANUM_PANEL_ID)).toBe(true);
+
+    expect(bar.added).toEqual([[OCEANUM_PANEL_ID, 0]]);
+    expect(bar.order()).toEqual([OCEANUM_PANEL_ID, 'jp-running-sessions']);
+    expect(bar.activated).toEqual([OCEANUM_PANEL_ID]);
+    Widget.detach(bar.left);
+  });
+
+  it('does not open a panel that was closed', () => {
+    const bar = sidebar(['jp-running-sessions', OCEANUM_PANEL_ID]);
+    bar.get(OCEANUM_PANEL_ID).hide();
+
+    moveToTop(bar.shell, OCEANUM_PANEL_ID);
+
+    expect(bar.order()[0]).toBe(OCEANUM_PANEL_ID);
+    expect(bar.activated).toEqual([]);
+    Widget.detach(bar.left);
+  });
+
+  it('leaves the sidebar alone when the panel is already first or absent', () => {
+    const first = sidebar([OCEANUM_PANEL_ID, 'jp-running-sessions']);
+    expect(moveToTop(first.shell, OCEANUM_PANEL_ID)).toBe(false);
+    expect(first.added).toEqual([]);
+    Widget.detach(first.left);
+
+    const absent = sidebar(['jp-running-sessions']);
+    expect(moveToTop(absent.shell, OCEANUM_PANEL_ID)).toBe(false);
+    expect(absent.added).toEqual([]);
+    Widget.detach(absent.left);
+  });
+});

package/src/__tests__/settingsSchema.spec.ts

@@ -44,10 +44,20 @@ describe('the datamesh-connect settings schema', () => {
       'datameshToken',
       'injectToken',
       'autoRunCode',
-      'iterate'
+      'iterate',
+      'showExamples'
     ]);
   });
 
+  it('shows the examples unless the user has hidden them', async () => {
+    // Settings stored before the switch existed must still load, showing examples.
+    const before = await registryWith({ datameshToken: 'a-token' }).load(ID);
+    expect(before.get('showExamples').composite).toBe(true);
+
+    const hidden = await registryWith({ showExamples: false }).load(ID);
+    expect(hidden.get('showExamples').composite).toBe(false);
+  });
+
   it('still loads settings stored when they were', async () => {
     const registry = registryWith({
       datameshToken: 'a-token',

package/src/__tests__/shareClient.spec.ts

@@ -0,0 +1,328 @@
+import type { INotebookContent } from '@jupyterlab/nbformat';
+
+import { SpecStoreClient, SpecStoreError } from '../share/client';
+import type { ISpecBody } from '../share/notebook';
+
+const ID = '6f1c1a52-4b8e-4c0f-9a57-1d2e3f4a5b6c';
+const SERVER_ID = '0b7d9f2e-1111-4a2b-8c3d-9e8f7a6b5c4d';
+
+const notebook: INotebookContent = {
+  nbformat: 4,
+  nbformat_minor: 5,
+  metadata: {},
+  cells: []
+};
+
+function record(id: string = ID) {
+  return {
+    id,
+    name: 'Waves',
+    description: null as string | null,
+    modified: '2026-09-12T10:00:00',
+    creator: 'a@example.com',
+    spec: notebook
+  };
+}
+
+function json(data: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => data
+  } as unknown as Response;
+}
+
+function noContent(): Response {
+  return {
+    ok: true,
+    status: 204,
+    json: async () => {
+      throw new Error('no body');
+    }
+  } as unknown as Response;
+}
+
+function setup(
+  response: () => Response | Promise<Response>,
+  token: string | null = 'tok'
+) {
+  const fetch = jest.fn(
+    async (_input: RequestInfo | URL, _init?: RequestInit) => response()
+  );
+  const client = new SpecStoreClient({
+    specsUrl: 'https://specs.example.com/',
+    getAccessToken: async () => token,
+    fetch: fetch as unknown as typeof globalThis.fetch
+  });
+  const call = (i = 0) => {
+    const [url, init] = fetch.mock.calls[i];
+    return {
+      url: String(url),
+      method: init?.method,
+      headers: (init?.headers ?? {}) as Record<string, string>,
+      body: init?.body === undefined ? undefined : JSON.parse(String(init.body))
+    };
+  };
+  return { client, fetch, call };
+}
+
+const body: ISpecBody = { name: 'Waves', description: null, spec: notebook };
+
+describe('SpecStoreClient', () => {
+  it('lists with the bearer token', async () => {
+    const { client, call } = setup(() => json([record()]));
+    const items = await client.list();
+    expect(items).toHaveLength(1);
+    expect(call()).toEqual({
+      url: 'https://specs.example.com/specs/notebook',
+      method: 'GET',
+      headers: { Authorization: 'Bearer tok' },
+      body: undefined
+    });
+  });
+
+  it('requires sign-in to list, without calling the server', async () => {
+    const { client, fetch } = setup(() => json([]), null);
+    await expect(client.list()).rejects.toMatchObject({ kind: 'signed-out' });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('gets a record anonymously when signed out', async () => {
+    const { client, call } = setup(() => json(record()), null);
+    const result = await client.get(ID);
+    expect(result.id).toBe(ID);
+    expect(call().url).toBe(`https://specs.example.com/specs/notebook/${ID}`);
+    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({
+      kind: 'invalid'
+    });
+    await expect(client.update('x/permissions', body)).rejects.toBeInstanceOf(
+      SpecStoreError
+    );
+    await expect(client.remove('x')).rejects.toMatchObject({
+      kind: 'invalid'
+    });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('creates with a JSON body, never sends an id, and uses the server id', async () => {
+    const { client, call } = setup(() => json(record(SERVER_ID)));
+    const withId = { ...body, id: ID } as ISpecBody;
+    const result = await client.create(withId);
+    expect(result.id).toBe(SERVER_ID);
+    expect(call()).toEqual({
+      url: 'https://specs.example.com/specs/notebook',
+      method: 'POST',
+      headers: {
+        Authorization: 'Bearer tok',
+        'Content-Type': 'application/json'
+      },
+      body: { name: 'Waves', description: null, spec: notebook }
+    });
+  });
+
+  it('updates with PUT to the record URL', async () => {
+    const { client, call } = setup(() => json(record()));
+    await client.update(ID, body);
+    expect(call().method).toBe('PUT');
+    expect(call().url).toBe(`https://specs.example.com/specs/notebook/${ID}`);
+    expect(call().body).toEqual(body);
+  });
+
+  it('patches only the fields it is given', async () => {
+    const { client, call } = setup(() => json(record()));
+    await client.patch(ID, { name: 'Renamed' });
+    expect(call()).toEqual({
+      url: `https://specs.example.com/specs/notebook/${ID}`,
+      method: 'PATCH',
+      headers: {
+        Authorization: 'Bearer tok',
+        'Content-Type': 'application/json'
+      },
+      body: { name: 'Renamed' }
+    });
+  });
+
+  it('refuses a patch that carries nothing, without calling the server', async () => {
+    // The store answers an empty patch with 400, and there is nothing to send.
+    const { client, fetch } = setup(() => json(record()));
+    await expect(client.patch(ID, {})).rejects.toMatchObject({
+      kind: 'invalid'
+    });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('renames with a single patch, leaving the notebook alone', async () => {
+    const { client, call, fetch } = setup(() => json(record()));
+    await client.rename(ID, 'Renamed');
+    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(call().method).toBe('PATCH');
+    expect(call().body).toEqual({ name: 'Renamed' });
+  });
+
+  it('renames by reading and putting back where the store has no PATCH', async () => {
+    // Production served no PATCH when this was written; a store without it answers 405.
+    const responses: Record<string, () => Response> = {
+      PATCH: () => json('Method Not Allowed', 405),
+      GET: () => json({ ...record(), description: 'Wave stats' }),
+      PUT: () => json(record())
+    };
+    const fetch = jest.fn(
+      async (_input: RequestInfo | URL, init?: RequestInit) =>
+        responses[init?.method ?? 'GET']()
+    );
+    const client = new SpecStoreClient({
+      specsUrl: 'https://specs.example.com',
+      getAccessToken: async () => 'tok',
+      fetch: fetch as unknown as typeof globalThis.fetch
+    });
+
+    await client.rename(ID, 'Renamed');
+
+    expect(fetch.mock.calls.map(([, init]) => init?.method)).toEqual([
+      'PATCH',
+      'GET',
+      'PUT'
+    ]);
+    const put = JSON.parse(String(fetch.mock.calls[2][1]?.body));
+    // The name changes; everything else goes back as it was read.
+    expect(put).toEqual({
+      name: 'Renamed',
+      description: 'Wave stats',
+      spec: notebook
+    });
+  });
+
+  it('does not fall back for a failure that is not a missing method', async () => {
+    const { client, fetch } = setup(() => json('Forbidden', 403));
+    await expect(client.rename(ID, 'Renamed')).rejects.toMatchObject({
+      kind: 'forbidden'
+    });
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('deletes with DELETE to the record URL, and needs sign-in', async () => {
+    const { client, call } = setup(() => noContent());
+    await client.remove(ID);
+    expect(call().method).toBe('DELETE');
+    expect(call().url).toBe(`https://specs.example.com/specs/notebook/${ID}`);
+    expect(call().body).toBeUndefined();
+
+    const signedOut = setup(() => noContent(), null);
+    await expect(signedOut.client.remove(ID)).rejects.toMatchObject({
+      kind: 'signed-out'
+    });
+    expect(signedOut.fetch).not.toHaveBeenCalled();
+  });
+
+  it('posts permission grants', async () => {
+    const { client, call } = setup(() => json([]));
+    await client.addPermission(ID, {
+      type: 'user',
+      entity: 'b@example.com',
+      permission: 'write'
+    });
+    await client.addPermission(ID, {
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+    expect(call(0).url).toBe(
+      `https://specs.example.com/specs/notebook/${ID}/permissions`
+    );
+    expect(call(0).method).toBe('POST');
+    expect(call(0).body).toEqual({
+      type: 'user',
+      entity: 'b@example.com',
+      permission: 'write'
+    });
+    expect(call(1).body).toEqual({
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+  });
+
+  it('deletes a permission by repeating the exact grant', async () => {
+    const { client, call } = setup(() => json([]));
+    await client.removePermission(ID, {
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+    expect(call(0).url).toBe(
+      `https://specs.example.com/specs/notebook/${ID}/permissions`
+    );
+    expect(call(0).method).toBe('DELETE');
+    expect(call(0).body).toEqual({
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+  });
+
+  it.each([
+    [400, 'expired', 'Your Oceanum session has expired, sign in again.'],
+    [403, 'forbidden', /another organisation/],
+    [404, 'not-found', /no longer exists/],
+    [405, 'unsupported', /does not offer that operation/],
+    [413, 'too-large', /too large/],
+    [500, 'server', 'Oceanum.io returned an error (HTTP 500).']
+  ])('maps HTTP %i to %s', async (status, kind, message) => {
+    const { client } = setup(() => json('Forbidden', status as number));
+    const error = await client.get(ID).catch(e => e);
+    expect(error).toBeInstanceOf(SpecStoreError);
+    expect(error.kind).toBe(kind);
+    expect(error.status).toBe(status);
+    expect(error.message).toMatch(message as string | RegExp);
+  });
+
+  it('maps a network failure', async () => {
+    const { client } = setup(() =>
+      Promise.reject(new TypeError('Failed to fetch'))
+    );
+    await expect(client.create(body)).rejects.toMatchObject({
+      kind: 'network',
+      message: expect.stringMatching(/Could not reach Oceanum.io/)
+    });
+  });
+
+  it('rejects malformed responses', async () => {
+    const { client } = setup(() => json({ id: 'nope', name: 1 }));
+    await expect(client.get(ID)).rejects.toMatchObject({ kind: 'invalid' });
+    const list = setup(() => json({ detail: 'x' }));
+    await expect(list.client.list()).rejects.toMatchObject({
+      kind: 'invalid'
+    });
+  });
+
+  it('asks for a fresh token on every request', async () => {
+    const getAccessToken = jest.fn(async () => 'tok');
+    const client = new SpecStoreClient({
+      specsUrl: 'https://specs.example.com',
+      getAccessToken,
+      fetch: async () => json(record())
+    });
+    await client.get(ID);
+    await client.get(ID);
+    expect(getAccessToken).toHaveBeenCalledTimes(2);
+  });
+});