@oceanum/oceanumlab 4.7.1 → 4.7.2

package/lib/share/plugin.js

@@ -0,0 +1,883 @@
+import { ILabShell } from '@jupyterlab/application';
+import { Dialog, ICommandPalette, InputDialog, Notification, showDialog } from '@jupyterlab/apputils';
+import { PageConfig } from '@jupyterlab/coreutils';
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { IMainMenu } from '@jupyterlab/mainmenu';
+import { INotebookTracker } from '@jupyterlab/notebook';
+import { Menu } from '@lumino/widgets';
+import { startSignIn } from '../auth/startSignIn';
+import { IOceanumAuth } from '../auth/tokens';
+import { SpecStoreClient, SpecStoreError } from './client';
+import { notebooksChanged } from './events';
+import { buildSpecBody, isSpecId, METADATA_KEY, notebookFromRecord, notebookNamesFor, OCEANUM_DIR, partitionSummaries, QUERY_PARAM, readLink, reportForShareFailures, sanitizeName, shareLink, uniqueNotebookPath } from './notebook';
+import { hideFileBrowser, pruneBeforeEachOpen, pruneFileMenu, routeSaves } from './oceanumOnly';
+import { NotebookListBody, ShareBody } from './widgets';
+export const CommandIDs = {
+    open: 'oceanum-share:open',
+    save: 'oceanum-share:save',
+    share: 'oceanum-share:share',
+    rename: 'oceanum-share:rename',
+    delete: 'oceanum-share:delete'
+};
+export const SHARE_PLUGIN_ID = '@oceanum/oceanumlab:share';
+/** The Notebooks tab marks each listed record with this, for its context menu. */
+export const SPEC_ID_ATTRIBUTE = 'data-spec-id';
+export const NOTEBOOK_ITEM_SELECTOR = `.oceanum-notebooks-item[${SPEC_ID_ATTRIBUTE}]`;
+const UNAVAILABLE = ' (unavailable: Oceanum sign-in is not configured for this host)';
+/**
+ * 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 const sharePlugin = {
+    id: SHARE_PLUGIN_ID,
+    description: 'Open, save, share, rename and delete notebooks through the Oceanum spec store.',
+    autoStart: true,
+    requires: [IOceanumAuth, IDocumentManager, INotebookTracker, ICommandPalette],
+    optional: [IMainMenu, ILabShell],
+    activate: (app, auth, docManager, tracker, palette, mainMenu, labShell) => {
+        var _a, _b, _c;
+        const specsUrl = (_b = (_a = auth.urls) === null || _a === void 0 ? void 0 : _a.specs) !== null && _b !== void 0 ? _b : null;
+        const store = specsUrl === null
+            ? null
+            : {
+                specsUrl,
+                client: new SpecStoreClient({
+                    specsUrl,
+                    getAccessToken: () => auth.getAccessToken()
+                })
+            };
+        const oceanumOnly = store !== null && ((_c = auth.environment) === null || _c === void 0 ? void 0 : _c.fileManagement) === 'oceanum';
+        const saving = new Set();
+        // Notebooks whose routed saves stopped reaching Oceanum, and the sign-in they
+        // stopped under: signing in again gives every notebook another go.
+        const muted = new WeakMap();
+        // Notebooks already reported as failing for a passing reason, so a flaky network
+        // does not raise the same notification on every autosave.
+        const warnedTransient = new WeakSet();
+        let signInGeneration = 0;
+        let warnedSignedOut = false;
+        const signedIn = () => store !== null && auth.user !== null;
+        const label = (text) => () => store ? text : `${text}${UNAVAILABLE}`;
+        // --- what a command acts on ---------------------------------------------------
+        /**
+         * Where a command was invoked from. The context menus pass this; the File menu, the
+         * palette and a keyboard shortcut pass nothing, and must not be answered with
+         * whatever happens to have been right-clicked earlier — JupyterLab keeps the last
+         * contextmenu event for the life of the page and never clears it, so the hit tests
+         * below answer long after their menu has gone.
+         */
+        const sourceOf = (args) => args.source === 'row' || args.source === 'notebook' ? args.source : null;
+        /** The record id under the pointer; only ask from the Notebooks tab's own menu. */
+        const hitTestSpecId = () => {
+            const node = app.contextMenuHitTest(candidate => candidate.hasAttribute(SPEC_ID_ATTRIBUTE));
+            const id = node === null || node === void 0 ? void 0 : node.getAttribute(SPEC_ID_ATTRIBUTE);
+            return isSpecId(id) ? id : null;
+        };
+        /**
+         * The notebook a command acts on: from a notebook's or a tab's context menu, the one
+         * under the pointer; anywhere else the current notebook, and only that.
+         */
+        const targetNotebook = (source) => {
+            if (source === 'notebook') {
+                const node = app.contextMenuHitTest(candidate => !!candidate.dataset.id);
+                const id = node === null || node === void 0 ? void 0 : node.dataset.id;
+                if (id) {
+                    const panel = tracker.find(candidate => candidate.id === id);
+                    if (panel) {
+                        return panel;
+                    }
+                }
+            }
+            const widget = tracker.currentWidget;
+            return widget !== null && widget === app.shell.currentWidget
+                ? widget
+                : null;
+        };
+        const linkOf = (panel) => store
+            ? readLink(panel.context.model.getMetadata(METADATA_KEY), store.specsUrl)
+            : null;
+        /** The open notebook linked to a record, if any. */
+        const panelFor = (id) => { var _a; return (_a = tracker.find(panel => { var _a; return ((_a = linkOf(panel)) === null || _a === void 0 ? void 0 : _a.spec_id) === id; })) !== null && _a !== void 0 ? _a : null; };
+        /** A record id from the command's arguments, the pointer, or the target notebook. */
+        const targetSpecId = (args) => {
+            var _a, _b;
+            if (isSpecId(args.id)) {
+                return args.id;
+            }
+            const source = sourceOf(args);
+            if (source === 'row') {
+                return hitTestSpecId();
+            }
+            const panel = targetNotebook(source);
+            return panel ? ((_b = (_a = linkOf(panel)) === null || _a === void 0 ? void 0 : _a.spec_id) !== null && _b !== void 0 ? _b : null) : null;
+        };
+        // --- sign-in and errors -------------------------------------------------------
+        async function offerSignIn(reason) {
+            const result = await showDialog({
+                title: 'Sign in to Oceanum.io',
+                body: `${reason} Sign in to Oceanum.io?`,
+                buttons: [Dialog.cancelButton(), Dialog.okButton({ label: 'Sign in' })]
+            });
+            if (!result.button.accept) {
+                return false;
+            }
+            try {
+                await startSignIn(app.commands, auth);
+            }
+            catch (error) {
+                console.error('Oceanum.io sign-in could not start', error);
+                Notification.error('Oceanum.io sign-in is not available right now.', {
+                    autoClose: 5000
+                });
+                return false;
+            }
+            return true;
+        }
+        async function ensureSignedIn(reason) {
+            await auth.ready;
+            if (auth.user !== null) {
+                return true;
+            }
+            await offerSignIn(reason);
+            return false;
+        }
+        /**
+         * Whether an error calls for signing in. A signed-in user can't sign in again: the
+         * spec store refused a token Auth0 still considers valid, so show the error instead.
+         */
+        const needsSignIn = (error) => (error.kind === 'expired' || error.kind === 'signed-out') &&
+            auth.user === null;
+        /**
+         * Tell the user. Messages never include notebook content, which can hold
+         * credentials. `quiet` is for saves nobody asked for by name (autosave, Ctrl+S in
+         * Oceanum-only mode): a notification, never a dialog.
+         */
+        async function reportError(action, error, quiet = false) {
+            if (!quiet && error instanceof SpecStoreError && needsSignIn(error)) {
+                await offerSignIn(error.message);
+                return;
+            }
+            console.error(`${action}:`, error);
+            const message = error instanceof Error ? error.message : 'Unknown error.';
+            Notification.error(`${action}: ${message}`, {
+                autoClose: quiet ? 8000 : false
+            });
+        }
+        /** Sharing failures are usually the owner check, which is worth explaining. */
+        function shareError(kind, error) {
+            return kind === 'forbidden'
+                ? new Error('Only the owner can share this notebook; if that is you, switch to the organisation you created it under.')
+                : error;
+        }
+        // --- opening ------------------------------------------------------------------
+        /** File names in the `Oceanum` folder, creating the folder if it is missing. */
+        async function oceanumFolderNames() {
+            const contents = docManager.services.contents;
+            let dir;
+            try {
+                dir = await contents.get(OCEANUM_DIR, { content: true });
+            }
+            catch (_a) {
+                dir = null;
+            }
+            if (!dir) {
+                const created = await contents.newUntitled({
+                    path: '',
+                    type: 'directory'
+                });
+                await contents.rename(created.path, OCEANUM_DIR);
+                return [];
+            }
+            if (dir.type !== 'directory' || !Array.isArray(dir.content)) {
+                throw new Error(`"${OCEANUM_DIR}" exists and is not a folder.`);
+            }
+            return dir.content.map((item) => item.name);
+        }
+        /**
+         * The file in the Oceanum folder already holding this record, or null. Only the
+         * names the record itself could have been written to are read.
+         */
+        async function pathHoldingRecord(s, record, names) {
+            var _a, _b;
+            for (const name of notebookNamesFor(record.name, names)) {
+                const path = `${OCEANUM_DIR}/${name}`;
+                try {
+                    const file = await docManager.services.contents.get(path, {
+                        content: true
+                    });
+                    const metadata = (_a = file.content) === null || _a === void 0 ? void 0 : _a.metadata;
+                    if (((_b = readLink(metadata === null || metadata === void 0 ? void 0 : metadata[METADATA_KEY], s.specsUrl)) === null || _b === void 0 ? void 0 : _b.spec_id) ===
+                        record.id) {
+                        return path;
+                    }
+                }
+                catch (_c) {
+                    // Unreadable or gone: not the copy we are looking for.
+                }
+            }
+            return null;
+        }
+        /** Write a record to the local drive as `Oceanum/<name>.ipynb` and open it. */
+        async function openRecord(s, record) {
+            var _a;
+            // Already open: bring it forward rather than writing a second copy.
+            const open = panelFor(record.id);
+            if (open) {
+                app.shell.activateById(open.id);
+                return;
+            }
+            const content = notebookFromRecord(record, s.specsUrl);
+            const names = await oceanumFolderNames();
+            // Reuse the file an earlier session left for this record. A second copy would be
+            // named "<name> (1)", and a record takes its name from the file on every save, so
+            // opening the same notebook twice would quietly rename it on Oceanum.
+            const path = (_a = (await pathHoldingRecord(s, record, names))) !== null && _a !== void 0 ? _a : uniqueNotebookPath(record.name, names);
+            await docManager.services.contents.save(path, {
+                type: 'notebook',
+                format: 'json',
+                content
+            });
+            if (!docManager.openOrReveal(path)) {
+                throw new Error(`Could not open ${path}.`);
+            }
+        }
+        async function openById(id) {
+            if (!store ||
+                !(await ensureSignedIn('Opening notebooks needs an Oceanum.io account.'))) {
+                return;
+            }
+            try {
+                await openRecord(store, await store.client.get(id));
+            }
+            catch (error) {
+                await reportError('Open from Oceanum failed', error);
+            }
+        }
+        async function openFromOceanum() {
+            var _a, _b;
+            if (!store ||
+                !(await ensureSignedIn('Opening notebooks needs an Oceanum.io account.'))) {
+                return;
+            }
+            try {
+                const { mine, shared } = partitionSummaries(await store.client.list(), (_b = (_a = auth.user) === null || _a === void 0 ? void 0 : _a.email) !== null && _b !== void 0 ? _b : null);
+                const result = await showDialog({
+                    title: 'Open from Oceanum',
+                    body: new NotebookListBody(mine, shared),
+                    buttons: [Dialog.cancelButton(), Dialog.okButton({ label: 'Open' })]
+                });
+                if (!result.button.accept || !result.value) {
+                    return;
+                }
+                await openRecord(store, await store.client.get(result.value));
+            }
+            catch (error) {
+                await reportError('Open from Oceanum failed', error);
+            }
+        }
+        // --- saving -------------------------------------------------------------------
+        /** Save a notebook to Oceanum.io; resolves with its record id, or `null`. */
+        async function saveToOceanum(panel, quiet = false) {
+            // Ignore repeat requests while a save is in flight, so it cannot create two records.
+            if (!store || saving.has(panel)) {
+                return null;
+            }
+            saving.add(panel);
+            try {
+                if (quiet) {
+                    if (auth.user === null) {
+                        if (!warnedSignedOut) {
+                            warnedSignedOut = true;
+                            Notification.warning('Not signed in to Oceanum.io: notebooks are only being saved locally.', { autoClose: 8000 });
+                        }
+                        return null;
+                    }
+                }
+                else if (!(await ensureSignedIn('Saving notebooks needs an Oceanum.io account.'))) {
+                    return null;
+                }
+                const id = await saveRecord(store, panel, quiet);
+                if (id !== null) {
+                    muted.delete(panel);
+                    warnedTransient.delete(panel);
+                }
+                return id;
+            }
+            finally {
+                saving.delete(panel);
+            }
+        }
+        /** A routed save: after every local save in Oceanum-only mode. */
+        async function pushQuietly(panel) {
+            if (muted.get(panel) === signInGeneration) {
+                return;
+            }
+            await saveToOceanum(panel, true);
+        }
+        /** Stop routed saves of a notebook until the next explicit save or sign-in. */
+        function mute(panel) {
+            muted.set(panel, signInGeneration);
+        }
+        /** Whether repeating this save unchanged would fail for the same reason. */
+        function isPermanent(error) {
+            return (error instanceof SpecStoreError &&
+                error.kind !== 'network' &&
+                error.kind !== 'server');
+        }
+        async function saveRecord(s, panel, quiet) {
+            await panel.context.ready;
+            const model = panel.context.model;
+            // INotebookModel types toJSON loosely; NotebookModel returns INotebookContent.
+            const content = model.toJSON();
+            const built = buildSpecBody(content, panel.context.path, s.specsUrl);
+            if (!built.ok) {
+                if (quiet) {
+                    mute(panel);
+                }
+                Notification.error('This notebook is too large to save to Oceanum.io, even without outputs.', { autoClose: quiet ? 8000 : false });
+                return null;
+            }
+            const link = readLink(model.getMetadata(METADATA_KEY), s.specsUrl);
+            let record;
+            try {
+                if (link === null) {
+                    record = await s.client.create(built.body);
+                }
+                else {
+                    try {
+                        record = await s.client.update(link.spec_id, built.body);
+                    }
+                    catch (error) {
+                        if (!(error instanceof SpecStoreError) ||
+                            (error.kind !== 'forbidden' && error.kind !== 'not-found')) {
+                            throw error;
+                        }
+                        if (quiet) {
+                            // Nobody asked for this save by name, so no dialog: say once why it
+                            // is not reaching Oceanum and leave the notebook alone until they do.
+                            mute(panel);
+                            Notification.error(`${error.message} Use Save to Oceanum to save a copy.`, { autoClose: 8000 });
+                            return null;
+                        }
+                        const result = await showDialog({
+                            title: 'Cannot save to the linked Oceanum notebook',
+                            body: `${error.message} Save as a new copy instead?`,
+                            buttons: [
+                                Dialog.cancelButton(),
+                                Dialog.okButton({ label: 'Save as a new copy' })
+                            ]
+                        });
+                        if (!result.button.accept) {
+                            return null;
+                        }
+                        record = await s.client.create(built.body);
+                    }
+                }
+            }
+            catch (error) {
+                if (quiet) {
+                    // A reason that will not pass on its own (no access, gone, signed out) mutes
+                    // this notebook until the user saves it themselves or signs in again. A
+                    // passing one (network, 5xx) does not: the next save simply tries again, and
+                    // the warning is raised once rather than on every autosave until one works.
+                    if (isPermanent(error)) {
+                        mute(panel);
+                    }
+                    else if (warnedTransient.has(panel)) {
+                        console.warn('Save to Oceanum failed again', error);
+                        return null;
+                    }
+                    else {
+                        warnedTransient.add(panel);
+                    }
+                }
+                await reportError('Save to Oceanum failed', error, quiet);
+                return null;
+            }
+            if (record.id !== (link === null || link === void 0 ? void 0 : link.spec_id)) {
+                const value = {
+                    spec_id: record.id,
+                    specs_url: s.specsUrl
+                };
+                if (link === null || link === void 0 ? void 0 : link.description) {
+                    value.description = link.description;
+                }
+                model.setMetadata(METADATA_KEY, value);
+                notebooksChanged.emit();
+            }
+            try {
+                await panel.context.save();
+            }
+            catch (error) {
+                await reportError('Saved to Oceanum, but saving the local file failed', error, quiet);
+                return record.id;
+            }
+            if (!quiet) {
+                Notification.success(built.strippedOutputs
+                    ? `Saved "${record.name}" to Oceanum without outputs, which made it too large.`
+                    : `Saved "${record.name}" to Oceanum.`, { autoClose: 5000 });
+            }
+            return record.id;
+        }
+        // --- sharing ------------------------------------------------------------------
+        async function shareOnOceanum(panel) {
+            var _a, _b;
+            if (!store ||
+                !(await ensureSignedIn('Sharing notebooks needs an Oceanum.io account.'))) {
+                return;
+            }
+            await panel.context.ready;
+            let id = (_b = (_a = linkOf(panel)) === null || _a === void 0 ? void 0 : _a.spec_id) !== null && _b !== void 0 ? _b : null;
+            if (id === null) {
+                const result = await showDialog({
+                    title: 'Save to Oceanum first',
+                    body: 'This notebook must be saved to Oceanum before it can be shared. Save it now?',
+                    buttons: [Dialog.cancelButton(), Dialog.okButton({ label: 'Save' })]
+                });
+                if (!result.button.accept) {
+                    return;
+                }
+                id = await saveToOceanum(panel);
+                if (id === null) {
+                    return;
+                }
+            }
+            await shareRecord(id);
+        }
+        async function shareRecord(id) {
+            var _a;
+            if (!store ||
+                !(await ensureSignedIn('Sharing notebooks needs an Oceanum.io account.'))) {
+                return;
+            }
+            const result = await showDialog({
+                title: 'Share on Oceanum',
+                body: new ShareBody(shareLink(PageConfig.getBaseUrl(), window.location.href, id)),
+                focusNodeSelector: 'textarea.jp-OceanumShare-email',
+                buttons: [Dialog.cancelButton(), Dialog.okButton({ label: 'Share' })]
+            });
+            if (!result.button.accept) {
+                return;
+            }
+            const choice = result.value;
+            if (!choice) {
+                Notification.warning('Enter a valid email address to share with a person.', { autoClose: 5000 });
+                return;
+            }
+            if (choice.action === 'revoke') {
+                const { grant } = choice;
+                try {
+                    await store.client.removePermission(id, grant);
+                }
+                catch (error) {
+                    const kind = error instanceof SpecStoreError ? error.kind : null;
+                    if (kind === 'not-found') {
+                        Notification.info('This notebook was not shared with everyone.', {
+                            autoClose: 5000
+                        });
+                        return;
+                    }
+                    await reportError('Share on Oceanum failed', shareError(kind, error));
+                    return;
+                }
+                Notification.success('Only people it is shared with can open this notebook now.', { autoClose: 5000 });
+                return;
+            }
+            // Share with the addresses we can and name the rest. Refusing the whole
+            // submission would be defensible on its own, but the dialog is rebuilt on every
+            // open and is destroyed when it is accepted, so it would also throw away
+            // everything typed — one bad address in a pasted list of twenty would mean
+            // reassembling all twenty.
+            if (choice.invalid.length > 0) {
+                Notification.warning(`Not a valid email address: ${choice.invalid.join(', ')}.` +
+                    (choice.grants.length === 0 ? ' Nobody was added.' : ''), { autoClose: 8000 });
+                if (choice.grants.length === 0) {
+                    return;
+                }
+            }
+            // The spec store takes one grant per request, so share with each person in turn
+            // and report the outcomes together — a failure part-way through must not leave
+            // the user guessing which of them now have access.
+            const failures = [];
+            let shared = 0;
+            for (const grant of choice.grants) {
+                try {
+                    await store.client.addPermission(id, grant);
+                    shared++;
+                }
+                catch (error) {
+                    failures.push({ entity: grant.entity, error });
+                    // The owner check is on the record, not the address: if it refuses one it
+                    // refuses all of them, so stop rather than firing the rest at a wall.
+                    if (error instanceof SpecStoreError && error.kind === 'forbidden') {
+                        break;
+                    }
+                }
+            }
+            const isPublic = choice.grants.some(grant => grant.type === 'public');
+            const forbidden = failures.some(failure => failure.error instanceof SpecStoreError &&
+                failure.error.kind === 'forbidden');
+            // Losing the owner check fails every grant for the same reason, so say it once.
+            if (forbidden && shared === 0) {
+                await reportError('Share on Oceanum failed', shareError('forbidden', null));
+                return;
+            }
+            if (failures.length > 0) {
+                // Keep the original error rather than describing it. It carries the only
+                // explanation the user gets ("Could not reach Oceanum.io", "HTTP 500"), and
+                // reportError reads it to decide whether to offer sign-in — a synthetic Error
+                // is never a SpecStoreError, so an expired session would leave no way back
+                // in. The public grant has an empty entity, so naming entities alone says
+                // nothing at all.
+                const first = failures[0].error;
+                const report = reportForShareFailures(choice.grants.length, failures.map(failure => failure.entity), first instanceof SpecStoreError && needsSignIn(first));
+                if (report.kind === 'original') {
+                    await reportError('Share on Oceanum failed', first);
+                    return;
+                }
+                // Some worked: say which did not, and still give the reason for the first.
+                const reason = first instanceof Error ? first.message : 'Unknown error.';
+                await reportError('Share on Oceanum failed', new Error(`Shared with ${shared} of ${choice.grants.length}. Could not share with ${report.named.join(', ')}: ${reason}`));
+                return;
+            }
+            const level = ((_a = choice.grants[0]) === null || _a === void 0 ? void 0 : _a.permission) === 'write' ? 'can edit' : 'can view';
+            Notification.success(isPublic
+                ? 'Anyone with the link can now view this notebook.'
+                : shared === 1
+                    ? `Shared with ${choice.grants[0].entity} (${level}).`
+                    : `Shared with ${shared} people (${level}).`, { autoClose: 5000 });
+        }
+        // --- renaming and deleting ----------------------------------------------------
+        async function renameRecord(id) {
+            var _a, _b;
+            if (!store ||
+                !(await ensureSignedIn('Renaming notebooks needs an Oceanum.io account.'))) {
+                return;
+            }
+            const open = panelFor(id);
+            let record;
+            try {
+                record = await store.client.get(id);
+            }
+            catch (error) {
+                await reportError('Rename on Oceanum failed', error);
+                return;
+            }
+            const result = await InputDialog.getText({
+                title: 'Rename on Oceanum',
+                text: record.name,
+                okLabel: 'Rename'
+            });
+            const name = (_b = (_a = result.value) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : '';
+            if (!result.button.accept || name === '' || name === record.name) {
+                return;
+            }
+            try {
+                if (open) {
+                    // The record takes its name from the local file on every save, so the file
+                    // has to follow or the next save would put the old name back. It moves first:
+                    // if the record is what fails, the next save renames it anyway and the two
+                    // converge on what was asked for, where the other order would undo itself.
+                    const path = open.context.path;
+                    const dir = path.includes('/')
+                        ? path.slice(0, path.lastIndexOf('/') + 1)
+                        : '';
+                    await docManager.rename(path, `${dir}${sanitizeName(name)}.ipynb`);
+                }
+                // Only the name goes: the notebook stays as it is, so this cannot overwrite a
+                // change another writer made to it while the dialog was open.
+                await store.client.rename(id, name);
+            }
+            catch (error) {
+                await reportError('Rename on Oceanum failed', error);
+                return;
+            }
+            notebooksChanged.emit();
+        }
+        async function deleteRecord(id) {
+            if (!store ||
+                !(await ensureSignedIn('Deleting notebooks needs an Oceanum.io account.'))) {
+                return;
+            }
+            const open = panelFor(id);
+            let name;
+            try {
+                name = (await store.client.get(id)).name;
+            }
+            catch (error) {
+                await reportError('Delete from Oceanum failed', error);
+                return;
+            }
+            const result = await showDialog({
+                title: 'Delete from Oceanum',
+                body: `Delete "${name}" from Oceanum.io? Everyone it is shared with loses it, and this cannot be undone.`,
+                buttons: [Dialog.cancelButton(), Dialog.warnButton({ label: 'Delete' })]
+            });
+            if (!result.button.accept) {
+                return;
+            }
+            try {
+                await store.client.remove(id);
+            }
+            catch (error) {
+                await reportError('Delete from Oceanum failed', error);
+                return;
+            }
+            notebooksChanged.emit();
+            if (!open) {
+                Notification.success(`Deleted "${name}" from Oceanum.`, {
+                    autoClose: 5000
+                });
+                return;
+            }
+            if (oceanumOnly) {
+                // The local file is the hidden working copy of a record that is gone; left
+                // there, the next routed save would bring the record straight back.
+                try {
+                    open.context.model.dirty = false;
+                    await docManager.deleteFile(open.context.path);
+                }
+                catch (error) {
+                    await reportError('Deleted from Oceanum, but closing the notebook failed', error);
+                }
+                Notification.success(`Deleted "${name}" from Oceanum.`, {
+                    autoClose: 5000
+                });
+                return;
+            }
+            // Elsewhere the local file is the user's own: keep it, but forget the record so
+            // the next Save to Oceanum creates a new one rather than failing on a missing id.
+            open.context.model.deleteMetadata(METADATA_KEY);
+            Notification.success(`Deleted "${name}" from Oceanum. The local file was kept.`, { autoClose: 5000 });
+        }
+        // --- shared links -------------------------------------------------------------
+        /**
+         * Try the link again once a user signs in, through the dialog or the account
+         * button. It cannot loop: a signed-in user who still may not open it gets an error
+         * and the link clears.
+         */
+        function openWhenSignedIn() {
+            if (auth.user !== null) {
+                // Already signed in (signIn() does nothing then), so no userChanged will follow.
+                void openFromQuery();
+                return;
+            }
+            const onUserChanged = (_, user) => {
+                if (user !== null) {
+                    auth.userChanged.disconnect(onUserChanged);
+                    void openFromQuery();
+                }
+            };
+            auth.userChanged.connect(onUserChanged);
+        }
+        /** Open `?oceanum-notebook=<id>`, then remove the parameter from the address bar. */
+        async function openFromQuery() {
+            const url = new URL(window.location.href);
+            const id = url.searchParams.get(QUERY_PARAM);
+            if (id === null || !store) {
+                return;
+            }
+            const clearQuery = () => {
+                url.searchParams.delete(QUERY_PARAM);
+                window.history.replaceState(window.history.state, '', url.toString());
+            };
+            if (!isSpecId(id)) {
+                clearQuery();
+                Notification.warning('The Oceanum notebook link is not valid.', {
+                    autoClose: 5000
+                });
+                return;
+            }
+            let record;
+            try {
+                record = await store.client.get(id);
+            }
+            catch (error) {
+                const kind = error instanceof SpecStoreError ? error.kind : null;
+                const reason = kind === 'forbidden' && auth.user === null
+                    ? 'This notebook is not shared publicly.'
+                    : error instanceof SpecStoreError && needsSignIn(error)
+                        ? error.message
+                        : null;
+                if (reason !== null) {
+                    if (!(await offerSignIn(reason))) {
+                        clearQuery();
+                        return;
+                    }
+                    // Leave the parameter in place while signing in, and open the link once
+                    // someone has. Sign-in does not reload the page to try again.
+                    openWhenSignedIn();
+                    return;
+                }
+                clearQuery();
+                await reportError('Opening the shared notebook failed', error);
+                return;
+            }
+            try {
+                await openRecord(store, record);
+            }
+            catch (error) {
+                await reportError('Opening the shared notebook failed', error);
+            }
+            clearQuery();
+        }
+        // --- commands -----------------------------------------------------------------
+        /** Whether the command can act on the pointer's row, the target notebook, or both. */
+        const enabledFor = (wants, args) => {
+            if (!signedIn()) {
+                return false;
+            }
+            const source = sourceOf(args);
+            if (wants !== 'notebook' && source === 'row') {
+                return hitTestSpecId() !== null;
+            }
+            const panel = targetNotebook(source);
+            if (panel === null) {
+                return false;
+            }
+            return wants === 'row-or-link' ? linkOf(panel) !== null : true;
+        };
+        /** The id a row-sourced command acts on, or null anywhere else. */
+        const rowSpecId = (args) => isSpecId(args.id)
+            ? args.id
+            : sourceOf(args) === 'row'
+                ? hitTestSpecId()
+                : null;
+        app.commands.addCommand(CommandIDs.open, {
+            // On a Notebooks row the command is plainly "Open"; elsewhere it opens a picker.
+            label: args => (rowSpecId(args) ? 'Open' : label('Open from Oceanum…')()),
+            caption: 'Open a notebook saved on Oceanum.io',
+            isEnabled: () => signedIn(),
+            execute: async (args) => {
+                const id = rowSpecId(args);
+                await (id ? openById(id) : openFromOceanum());
+            }
+        });
+        app.commands.addCommand(CommandIDs.save, {
+            label: label('Save to Oceanum'),
+            caption: 'Save the notebook to Oceanum.io',
+            isEnabled: args => enabledFor('notebook', args),
+            execute: async (args) => {
+                const panel = targetNotebook(sourceOf(args));
+                if (panel) {
+                    await saveToOceanum(panel);
+                }
+            }
+        });
+        app.commands.addCommand(CommandIDs.share, {
+            label: label('Share on Oceanum…'),
+            caption: 'Share the notebook through Oceanum.io',
+            isEnabled: args => enabledFor('row-or-notebook', args),
+            execute: async (args) => {
+                const id = rowSpecId(args);
+                if (id) {
+                    await shareRecord(id);
+                    return;
+                }
+                const panel = targetNotebook(sourceOf(args));
+                if (panel) {
+                    await shareOnOceanum(panel);
+                }
+            }
+        });
+        app.commands.addCommand(CommandIDs.rename, {
+            label: args => rowSpecId(args) ? 'Rename…' : label('Rename on Oceanum…')(),
+            caption: 'Rename the notebook on Oceanum.io',
+            isEnabled: args => enabledFor('row-or-link', args),
+            execute: async (args) => {
+                const id = targetSpecId(args);
+                if (id) {
+                    await renameRecord(id);
+                }
+            }
+        });
+        app.commands.addCommand(CommandIDs.delete, {
+            label: args => rowSpecId(args) ? 'Delete' : label('Delete from Oceanum')(),
+            caption: 'Delete the notebook from Oceanum.io',
+            isEnabled: args => enabledFor('row-or-link', args),
+            execute: async (args) => {
+                const id = targetSpecId(args);
+                if (id) {
+                    await deleteRecord(id);
+                }
+            }
+        });
+        const commands = [
+            CommandIDs.open,
+            CommandIDs.save,
+            CommandIDs.share,
+            CommandIDs.rename,
+            CommandIDs.delete
+        ];
+        for (const command of commands) {
+            palette.addItem({ command, category: 'Oceanum' });
+        }
+        // After JupyterLab's own Save group (rank 4), before Reload and Rename (rank 5).
+        mainMenu === null || mainMenu === void 0 ? void 0 : mainMenu.fileMenu.addGroup(commands.map(command => ({ command })), 4.5);
+        // Right-click in a notebook, or on its tab.
+        for (const selector of ['.jp-Notebook', '[data-type="document-title"]']) {
+            app.contextMenu.addItem({ type: 'separator', selector, rank: 45 });
+            for (const [i, command] of [
+                CommandIDs.save,
+                CommandIDs.share,
+                CommandIDs.rename,
+                CommandIDs.delete
+            ].entries()) {
+                app.contextMenu.addItem({
+                    command,
+                    args: { source: 'notebook' },
+                    selector,
+                    rank: 46 + i
+                });
+            }
+        }
+        // Right-click on a row of the Notebooks tab.
+        for (const [i, command] of [
+            CommandIDs.open,
+            CommandIDs.rename,
+            CommandIDs.share,
+            CommandIDs.delete
+        ].entries()) {
+            app.contextMenu.addItem({
+                command,
+                args: { source: 'row' },
+                selector: NOTEBOOK_ITEM_SELECTOR,
+                rank: i
+            });
+        }
+        const refresh = () => {
+            for (const command of commands) {
+                app.commands.notifyCommandChanged(command);
+            }
+        };
+        tracker.currentChanged.connect(refresh);
+        labShell === null || labShell === void 0 ? void 0 : labShell.currentChanged.connect(refresh);
+        auth.userChanged.connect((_, user) => {
+            if (user !== null) {
+                signInGeneration++;
+            }
+            warnedSignedOut = false;
+            refresh();
+        });
+        if (oceanumOnly) {
+            void app.restored.then(() => {
+                hideFileBrowser(app.shell);
+                // IFileMenu is the narrow interface; the menu itself is a Lumino Menu, which
+                // is what can drop items.
+                const fileMenu = mainMenu === null || mainMenu === void 0 ? void 0 : mainMenu.fileMenu;
+                if (fileMenu instanceof Menu) {
+                    pruneFileMenu(fileMenu);
+                    pruneBeforeEachOpen(fileMenu);
+                }
+                routeSaves(tracker, pushQuietly);
+            });
+        }
+        Promise.all([app.restored, auth.ready])
+            .then(() => openFromQuery())
+            .catch(error => console.error('Failed to open the Oceanum notebook link', error));
+    }
+};