@oceanum/oceanumlab 4.7.1 → 4.8.0

package/lib/share/notebook.js

@@ -0,0 +1,355 @@
+/** Notebook metadata key linking a local notebook to its spec store record. */
+export const METADATA_KEY = 'oceanum';
+/** Folder that notebooks opened from Oceanum.io are written to. */
+export const OCEANUM_DIR = 'Oceanum';
+/** Query parameter carrying a shared notebook id. */
+export const QUERY_PARAM = 'oceanum-notebook';
+/**
+ * Largest request body we send. Cloud Run rejects requests over 32 MiB; keep a margin
+ * for headers and the server's own encoding.
+ */
+export const MAX_BODY_BYTES = 30 * 1024 * 1024;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Whether `value` is a UUID, and so safe to put in a spec store URL. */
+export function isSpecId(value) {
+    return typeof value === 'string' && UUID_RE.test(value);
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Read the link from an `oceanum` metadata value, or `null` if it is missing, malformed,
+ * or belongs to a different spec store.
+ */
+export function readLink(value, specsUrl) {
+    if (!isObject(value) ||
+        !isSpecId(value.spec_id) ||
+        value.specs_url !== specsUrl) {
+        return null;
+    }
+    const link = { spec_id: value.spec_id, specs_url: specsUrl };
+    if (typeof value.description === 'string') {
+        link.description = value.description;
+    }
+    return link;
+}
+/** The notebook name stored on Oceanum.io for a local path. */
+export function nameFromPath(path) {
+    var _a;
+    const base = (_a = path.split('/').pop()) !== null && _a !== void 0 ? _a : '';
+    return base.replace(/\.ipynb$/i, '') || 'Untitled';
+}
+function byteLength(text) {
+    return new TextEncoder().encode(text).length;
+}
+function withoutLink(content) {
+    const metadata = { ...content.metadata };
+    delete metadata[METADATA_KEY];
+    return { ...content, metadata };
+}
+/**
+ * The notebook with every cell's `trusted` metadata removed.
+ *
+ * JupyterLab trusts a cell whose metadata says `trusted: true` and then renders its HTML
+ * and Markdown unsanitised, running any script in them. A notebook from the spec store
+ * (anyone with write access can edit a record) must arrive untrusted; its outputs
+ * become trusted again when the reader re-runs the cells.
+ */
+export function withoutTrust(content) {
+    const cells = content.cells.map(cell => {
+        if (!isObject(cell.metadata) || !('trusted' in cell.metadata)) {
+            return cell;
+        }
+        const metadata = { ...cell.metadata };
+        delete metadata.trusted;
+        return { ...cell, metadata };
+    });
+    return { ...content, cells };
+}
+function withoutOutputs(content) {
+    const cells = content.cells.map(cell => cell.cell_type === 'code'
+        ? { ...cell, outputs: [], execution_count: null }
+        : cell);
+    return { ...content, cells };
+}
+/**
+ * Build the spec store body for a notebook. The `oceanum` link is not stored in the
+ * record. If the body is over `maxBytes`, code-cell outputs and execution counts are
+ * dropped; if it is still too large, the result is not ok.
+ */
+export function buildSpecBody(content, path, specsUrl, maxBytes = MAX_BODY_BYTES) {
+    var _a;
+    const link = readLink((_a = content.metadata) === null || _a === void 0 ? void 0 : _a[METADATA_KEY], specsUrl);
+    const make = (spec) => {
+        var _a;
+        return ({
+            name: nameFromPath(path),
+            description: (_a = link === null || link === void 0 ? void 0 : link.description) !== null && _a !== void 0 ? _a : null,
+            spec
+        });
+    };
+    const full = make(withoutTrust(withoutLink(content)));
+    const fullBytes = byteLength(JSON.stringify(full));
+    if (fullBytes <= maxBytes) {
+        return { ok: true, body: full, bytes: fullBytes, strippedOutputs: false };
+    }
+    const stripped = make(withoutOutputs(full.spec));
+    const strippedBytes = byteLength(JSON.stringify(stripped));
+    if (strippedBytes <= maxBytes) {
+        return {
+            ok: true,
+            body: stripped,
+            bytes: strippedBytes,
+            strippedOutputs: true
+        };
+    }
+    return { ok: false, bytes: strippedBytes };
+}
+/**
+ * The notebook stored in a record, untrusted. Throws if the record does not hold an
+ * nbformat 4 notebook.
+ */
+function recordNotebook(record) {
+    const spec = record.spec;
+    if (!isNotebook(spec)) {
+        throw new Error('This Oceanum.io record is not a valid notebook.');
+    }
+    return withoutTrust(spec);
+}
+function isNotebook(value) {
+    return (isObject(value) &&
+        value.nbformat === 4 &&
+        Array.isArray(value.cells) &&
+        value.cells.every(cell => isObject(cell) && typeof cell.cell_type === 'string') &&
+        isObject(value.metadata));
+}
+/**
+ * A notebook uploaded from the user's computer, untrusted and linked to nothing: a file
+ * someone else downloaded from a record must not save over that record, and its outputs
+ * must not run scripts on the origin that holds the Oceanum.io session. Throws if the
+ * text is not an nbformat 4 notebook; the message never quotes the file.
+ */
+export function notebookFromUpload(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (_a) {
+        throw new Error('The file is not a Jupyter notebook: it is not JSON.');
+    }
+    if (!isNotebook(parsed)) {
+        throw new Error('The file is not a Jupyter notebook in nbformat 4.');
+    }
+    return withoutLink(withoutTrust(parsed));
+}
+/**
+ * The notebook stored in a record, with its `oceanum` link set. Throws if the record
+ * does not hold an nbformat 4 notebook.
+ */
+export function notebookFromRecord(record, specsUrl) {
+    const link = { spec_id: record.id, specs_url: specsUrl };
+    if (record.description) {
+        link.description = record.description;
+    }
+    const content = recordNotebook(record);
+    return {
+        ...content,
+        metadata: { ...content.metadata, [METADATA_KEY]: { ...link } }
+    };
+}
+/**
+ * A copy of the notebook stored in a record, linked to nothing: untrusted, and without
+ * any `oceanum` link, so saving it creates a record of the user's own instead of
+ * writing to this one. Throws if the record does not hold an nbformat 4 notebook.
+ */
+export function unlinkedNotebookFromRecord(record) {
+    return withoutLink(recordNotebook(record));
+}
+/** Make a record name safe to use as a single path segment. */
+export function sanitizeName(name) {
+    const clean = name
+        .trim()
+        .replace(/\.ipynb$/i, '')
+        .replace(/[/\\]/g, '-')
+        .trim();
+    return clean === '' || clean === '.' || clean === '..' ? 'Untitled' : clean;
+}
+/**
+ * A path `Oceanum/<name>.ipynb` that does not collide with `existing` (file names in the
+ * `Oceanum` folder), appending ` (1)`, ` (2)`, ... as needed.
+ */
+export function uniqueNotebookPath(name, existing) {
+    const taken = new Set(existing);
+    const base = sanitizeName(name);
+    let candidate = `${base}.ipynb`;
+    for (let i = 1; taken.has(candidate); i++) {
+        candidate = `${base} (${i}).ipynb`;
+    }
+    return `${OCEANUM_DIR}/${candidate}`;
+}
+/**
+ * The names in `existing` that `uniqueNotebookPath` could have given a record called
+ * `name`, in the order it would have tried them: `<base>.ipynb`, then `<base> (1).ipynb`,
+ * `<base> (2).ipynb` and so on.
+ *
+ * Opening a record looks through these for the copy a previous session left, so the same
+ * record keeps one local file. Without that the second copy is named `<base> (1)`, and
+ * since a record takes its name from the file on every save, opening a notebook twice
+ * would quietly rename it on Oceanum.
+ */
+export function notebookNamesFor(name, existing) {
+    const base = sanitizeName(name);
+    const prefix = `${base} (`;
+    const suffix = ').ipynb';
+    const plain = [];
+    const numbered = [];
+    for (const candidate of existing) {
+        if (candidate === `${base}.ipynb`) {
+            plain.push(candidate);
+            continue;
+        }
+        if (!candidate.startsWith(prefix) || !candidate.endsWith(suffix)) {
+            continue;
+        }
+        const index = candidate.slice(prefix.length, candidate.length - suffix.length);
+        if (/^\d+$/.test(index)) {
+            numbered.push({ name: candidate, index: Number(index) });
+        }
+    }
+    numbered.sort((a, b) => a.index - b.index);
+    return [...plain, ...numbered.map(entry => entry.name)];
+}
+/**
+ * Split a listing into the caller's own notebooks and the rest, newest first.
+ *
+ * The store only sends `creator` on records the caller created, so anything else it
+ * returns is shared with them — directly, or because it is public. Addresses are
+ * compared case-insensitively: the store matches entities as case-sensitive globs, so
+ * the two sides can differ in case.
+ */
+export function partitionSummaries(items, email) {
+    var _a;
+    const me = (_a = email === null || email === void 0 ? void 0 : email.toLowerCase()) !== null && _a !== void 0 ? _a : null;
+    const sorted = [...items].sort((a, b) => b.modified.localeCompare(a.modified));
+    const isMine = (item) => { var _a; return me !== null && ((_a = item.creator) === null || _a === void 0 ? void 0 : _a.toLowerCase()) === me; };
+    return {
+        mine: sorted.filter(isMine),
+        shared: sorted.filter(item => !isMine(item))
+    };
+}
+/** The `kind` of a Notebook Demo record's spec. */
+export const NOTEBOOK_DEMO_KIND = 'notebook-demo';
+function nonBlank(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+/**
+ * The sections of a Notebook Demo record's spec, keeping only what can be listed: items
+ * with a record id and a title, in sections with a title and at least one such item.
+ * A spec of another kind or version gives no sections, with a warning.
+ */
+export function parseNotebookDemo(spec) {
+    if (!isObject(spec) ||
+        spec.kind !== NOTEBOOK_DEMO_KIND ||
+        spec.version !== 1 ||
+        !Array.isArray(spec.sections)) {
+        console.warn('Oceanum: ignoring a Notebook Demo record this version cannot read.');
+        return [];
+    }
+    const sections = [];
+    for (const section of spec.sections) {
+        if (!isObject(section) ||
+            !nonBlank(section.title) ||
+            !Array.isArray(section.items)) {
+            continue;
+        }
+        const items = [];
+        for (const item of section.items) {
+            if (!isObject(item) || !isSpecId(item.id) || !nonBlank(item.title)) {
+                continue;
+            }
+            items.push(typeof item.summary === 'string'
+                ? { id: item.id, title: item.title, summary: item.summary }
+                : { id: item.id, title: item.title });
+        }
+        if (items.length > 0) {
+            sections.push({ title: section.title, items });
+        }
+    }
+    return sections;
+}
+/** Parse a spec store timestamp, which is UTC but usually has no zone designator. */
+export function parseTimestamp(value) {
+    const zoned = /(Z|[+-]\d{2}:?\d{2})$/i.test(value) ? value : `${value}Z`;
+    const date = new Date(zoned);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/**
+ * Whether `email` can be granted access. Glob characters are refused: the server
+ * matches user entities as globs.
+ */
+export function isShareableEmail(email) {
+    return /^[^\s@*?[\]]+@[^\s@*?[\]]+\.[^\s@*?[\]]+$/.test(email);
+}
+/**
+ * Split what the user typed into individual addresses. Commas, semicolons and any
+ * whitespace all separate, so one-per-line and a comma-separated list both work.
+ *
+ * Bare addresses only: a mail client's "To:" line carries display names, and
+ * `"Alice B" <alice@example.com>` splits into tokens that are not addresses. Those
+ * come back in `invalid` so the user is told, rather than being silently dropped.
+ *
+ * Addresses are lower-cased because the spec store matches the user entity as a
+ * case-sensitive glob against the Auth0 email claim, which Auth0 stores lower case.
+ */
+export function parseShareEmails(raw) {
+    const emails = [];
+    const invalid = [];
+    const seen = new Set();
+    for (const part of raw.split(/[\s,;]+/)) {
+        const entry = part.trim();
+        if (entry === '') {
+            continue;
+        }
+        const email = entry.toLowerCase();
+        if (!isShareableEmail(email)) {
+            // Report it as written, so the user recognises what they typed.
+            invalid.push(entry);
+            continue;
+        }
+        if (!seen.has(email)) {
+            seen.add(email);
+            emails.push(email);
+        }
+    }
+    return { emails, invalid };
+}
+/**
+ * Decide how to report a set of failed grants.
+ *
+ * `entities` are the failed grants' entities, in order; the public grant's entity is
+ * the empty string, which names nobody.
+ */
+export function reportForShareFailures(grantCount, entities, needsSignIn) {
+    const named = entities.filter(entity => entity !== '');
+    // A sign-in problem must reach the reporter as the original error or the user is
+    // never offered a way back in; an unnamed or total failure has nothing extra worth
+    // saying.
+    if (needsSignIn || named.length === 0 || entities.length >= grantCount) {
+        return { kind: 'original' };
+    }
+    return { kind: 'partial', named };
+}
+/**
+ * The link that opens a shared notebook in this deployment.
+ *
+ * JupyterLite is static files, so its page is `lab/index.html`; a JupyterLab server
+ * serves the application at `lab` and has no `index.html` to route.
+ */
+export function shareLink(baseUrl, pageHref, id) {
+    const app = new URL(pageHref).pathname.endsWith('/index.html')
+        ? 'lab/index.html'
+        : 'lab';
+    const url = new URL(app, new URL(baseUrl, pageHref));
+    url.searchParams.set(QUERY_PARAM, id);
+    return url.toString();
+}

package/lib/share/oceanumOnly.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Oceanum-only file management: what a deployment gets when its environment says
+ * `fileManagement: 'oceanum'`, as notebook.oceanum.io does.
+ *
+ * The local drive stays as the working copy underneath, out of sight: the file browser
+ * is taken out of the sidebar, the File menu loses the entries that manage local files,
+ * and every completed local save is pushed to the spec store, so Ctrl+S, the toolbar
+ * button, Save All and autosave all reach Oceanum.
+ */
+import type { INotebookTracker, NotebookPanel } from '@jupyterlab/notebook';
+import type { Menu, Widget } from '@lumino/widgets';
+/** The widget id `@jupyterlab/filebrowser-extension:browser` gives the file browser. */
+export declare const FILE_BROWSER_ID = "filebrowser";
+/** The widget id of this extension's Oceanum.io panel, which takes the browser's place. */
+export declare const OCEANUM_PANEL_ID = "datamesh-connect";
+/**
+ * File menu entries that manage local files. Save, Save All and Rename stay: saving is
+ * routed to Oceanum, and renaming the local file is how a notebook gets its name.
+ */
+export declare const LOCAL_FILE_COMMANDS: readonly string[];
+/**
+ * File > New entries for files that are not notebooks. The spec store holds notebooks
+ * only, so such a file could never be saved anywhere the user can see.
+ */
+export declare const NON_NOTEBOOK_NEW_COMMANDS: readonly string[];
+/**
+ * Take the file browser out of the sidebar; true if it was there. It is closed, not
+ * disposed: other extensions hold it through IDefaultFileBrowser and still use it to
+ * open paths. If it was the open panel, `instead` is opened in its place; a sidebar the
+ * user had collapsed stays collapsed.
+ */
+export declare function hideFileBrowser(shell: {
+    widgets(area: 'left'): Iterable<Widget>;
+    activateById(id: string): void;
+}, instead?: string): boolean;
+/**
+ * Put a left-sidebar widget first, and keep it open if it was. True if it moved.
+ *
+ * A rank alone is not enough: the layout restorer replays the sidebar order each user
+ * last had, so a returning user would keep the panel wherever it used to be. Adding it
+ * again after the restore re-inserts it by rank, and the shell saves the new order.
+ */
+export declare function moveToTop(shell: {
+    widgets(area: 'left'): Iterable<Widget>;
+    add(widget: Widget, area: 'left', options: {
+        rank: number;
+    }): void;
+    activateById(id: string): void;
+}, id: string): boolean;
+/**
+ * Submenus of local files. "Open Recent" is built by the document manager rather than
+ * declared in a schema, and its menu has no id, so it is known by the commands it holds.
+ */
+export declare const LOCAL_FILE_SUBMENU_COMMANDS: readonly string[];
+/**
+ * Remove the local-file entries from a menu; returns how many went. Idempotent, so it
+ * can run every time the menu is about to show: entries arrive from settings schemas as
+ * plugins load, not all at once.
+ */
+export declare function pruneFileMenu(menu: Menu, commands?: readonly string[]): number;
+/**
+ * Prune the menu again every time it opens. Entries arrive from settings schemas as
+ * plugins load rather than all at once, and a menu has no "about to show" signal; it
+ * is attached to the document each time it opens, which a message hook can watch.
+ */
+export declare function pruneBeforeEachOpen(menu: Menu, commands?: readonly string[]): void;
+/**
+ * Call `push` after every completed local save of every notebook, open now or later.
+ * `push` must guard against its own saves: writing the record link back to the notebook
+ * saves it again.
+ */
+export declare function routeSaves(tracker: INotebookTracker, push: (panel: NotebookPanel) => Promise<void>): void;

package/lib/share/oceanumOnly.js

@@ -0,0 +1,127 @@
+import { MessageLoop } from '@lumino/messaging';
+/** The widget id `@jupyterlab/filebrowser-extension:browser` gives the file browser. */
+export const FILE_BROWSER_ID = 'filebrowser';
+/** The widget id of this extension's Oceanum.io panel, which takes the browser's place. */
+export const OCEANUM_PANEL_ID = 'datamesh-connect';
+/**
+ * File menu entries that manage local files. Save, Save All and Rename stay: saving is
+ * routed to Oceanum, and renaming the local file is how a notebook gets its name.
+ */
+export const LOCAL_FILE_COMMANDS = [
+    'filebrowser:open-path',
+    'filebrowser:open-url',
+    'docmanager:save-as',
+    'docmanager:reload',
+    'docmanager:restore-checkpoint',
+    'docmanager:duplicate',
+    'docmanager:download'
+];
+/**
+ * File > New entries for files that are not notebooks. The spec store holds notebooks
+ * only, so such a file could never be saved anywhere the user can see.
+ */
+export const NON_NOTEBOOK_NEW_COMMANDS = [
+    'fileeditor:create-new',
+    'fileeditor:create-new-markdown-file'
+];
+/**
+ * Take the file browser out of the sidebar; true if it was there. It is closed, not
+ * disposed: other extensions hold it through IDefaultFileBrowser and still use it to
+ * open paths. If it was the open panel, `instead` is opened in its place; a sidebar the
+ * user had collapsed stays collapsed.
+ */
+export function hideFileBrowser(shell, instead) {
+    for (const widget of shell.widgets('left')) {
+        if (widget.id === FILE_BROWSER_ID) {
+            const wasOpen = widget.isVisible;
+            widget.close();
+            if (wasOpen && instead) {
+                shell.activateById(instead);
+            }
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Put a left-sidebar widget first, and keep it open if it was. True if it moved.
+ *
+ * A rank alone is not enough: the layout restorer replays the sidebar order each user
+ * last had, so a returning user would keep the panel wherever it used to be. Adding it
+ * again after the restore re-inserts it by rank, and the shell saves the new order.
+ */
+export function moveToTop(shell, id) {
+    const widgets = Array.from(shell.widgets('left'));
+    const index = widgets.findIndex(widget => widget.id === id);
+    if (index <= 0) {
+        return false;
+    }
+    const widget = widgets[index];
+    // Adding hides the widget, so an open panel has to be opened again.
+    const wasOpen = widget.isVisible;
+    shell.add(widget, 'left', { rank: 0 });
+    if (wasOpen) {
+        shell.activateById(id);
+    }
+    return true;
+}
+/**
+ * Submenus of local files. "Open Recent" is built by the document manager rather than
+ * declared in a schema, and its menu has no id, so it is known by the commands it holds.
+ */
+export const LOCAL_FILE_SUBMENU_COMMANDS = [
+    'docmanager:open-recent',
+    'docmanager:clear-recents'
+];
+function isLocalSubmenu(item) {
+    return (item.type === 'submenu' &&
+        !!item.submenu &&
+        (item.submenu.title.label === 'Open Recent' ||
+            item.submenu.items.some(child => LOCAL_FILE_SUBMENU_COMMANDS.includes(child.command))));
+}
+/**
+ * Remove the local-file entries from a menu; returns how many went. Idempotent, so it
+ * can run every time the menu is about to show: entries arrive from settings schemas as
+ * plugins load, not all at once.
+ */
+export function pruneFileMenu(menu, commands = LOCAL_FILE_COMMANDS) {
+    let removed = 0;
+    for (let i = menu.items.length - 1; i >= 0; i--) {
+        const item = menu.items[i];
+        if ((item.type === 'command' && commands.includes(item.command)) ||
+            isLocalSubmenu(item)) {
+            menu.removeItemAt(i);
+            removed++;
+        }
+    }
+    return removed;
+}
+/**
+ * Prune the menu again every time it opens. Entries arrive from settings schemas as
+ * plugins load rather than all at once, and a menu has no "about to show" signal; it
+ * is attached to the document each time it opens, which a message hook can watch.
+ */
+export function pruneBeforeEachOpen(menu, commands = LOCAL_FILE_COMMANDS) {
+    MessageLoop.installMessageHook(menu, (_, message) => {
+        if (message.type === 'before-attach') {
+            pruneFileMenu(menu, commands);
+        }
+        return true;
+    });
+}
+/**
+ * Call `push` after every completed local save of every notebook, open now or later.
+ * `push` must guard against its own saves: writing the record link back to the notebook
+ * saves it again.
+ */
+export function routeSaves(tracker, push) {
+    const watch = (panel) => {
+        panel.context.saveState.connect((_, state) => {
+            if (state === 'completed') {
+                void push(panel);
+            }
+        });
+    };
+    tracker.forEach(watch);
+    tracker.widgetAdded.connect((_, panel) => watch(panel));
+}

package/lib/share/plugin.d.ts

@@ -0,0 +1,23 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+export declare const CommandIDs: {
+    readonly open: "oceanum-share:open";
+    readonly openExample: "oceanum-share:open-example";
+    readonly upload: "oceanum-share:upload";
+    readonly save: "oceanum-share:save";
+    readonly share: "oceanum-share:share";
+    readonly rename: "oceanum-share:rename";
+    readonly delete: "oceanum-share:delete";
+};
+export declare const SHARE_PLUGIN_ID = "@oceanum/oceanumlab:share";
+/** The Notebooks tab marks each listed record with this, for its context menu. */
+export declare const SPEC_ID_ATTRIBUTE = "data-spec-id";
+export declare const NOTEBOOK_ITEM_SELECTOR = ".oceanum-notebooks-item[data-spec-id]";
+/**
+ * Open, save, share, rename and delete notebooks through the Oceanum spec store.
+ *
+ * The commands sit in the File menu, the command palette, a notebook's context menu
+ * (and its tab's), and the Notebooks tab's rows. They are enabled only while signed in.
+ * With `fileManagement: 'oceanum'` in the environment the local drive goes out of
+ * sight and every local save is pushed to the store: see `oceanumOnly.ts`.
+ */
+export declare const sharePlugin: JupyterFrontEndPlugin<void>;