jupyterlab_commands_extension 1.0.18 → 1.1.3

package/README.md

@@ -55,16 +55,26 @@ JUPYTERLAB_COMMANDS_TOKEN=... jupyterlab-commands --url https://remote-host:8888
 jupyterlab-commands activity
 ```
 
+`file:download` starts a browser download of a file the contents API serves. The `path` argument names the file relative to the server root; the file must exist, and folders are refused. The download starts in the browser tab that runs the relay, so the file lands on the user computer.
+
+```bash
+jupyterlab-commands execute file:download --args '{"path": "data/report.csv"}'
+```
+
 Exit codes: 0 success, 2 discovery or usage error, 3 no browser client, 4 command not allowed, 5 execution error.
 
 The browser tab is the executor: the command runs in the lab, not in the terminal.
 
+Every execute request reaches the JupyterLab server log: the outcome, the command ID, the arguments as compact JSON truncated to 500 characters, the elapsed milliseconds and the caller's remote IP, at INFO on success and WARNING on refusal or failure.
+
 ## Allowlist
 
-The `allowedCommands` setting holds the command IDs the CLI may run. The defaults are `docmanager:open`, `help:open`, `apputils:notify`, `notebook:create-new`, `console:create`, `terminal:create-new`, `launcher:create` and `jupyterlab-commands-reference:open`.
+The `allowedCommands` setting holds the command IDs the CLI may run. The defaults are `docmanager:open`, `help:open`, `apputils:notify`, `notebook:create-new`, `console:create`, `terminal:create-new`, `launcher:create`, `jupyterlab-commands-reference:open` and `file:download`.
 
 The **Add to command executor** button in the Command Executor column of the reference tab appends that command ID to the setting, and the button then shows **Added**. The setting can also be edited directly in **Settings > Settings Editor > Commands Executor**, whose plugin ID is `jupyterlab_commands_extension:plugin`.
 
+A user with a saved `allowedCommands` list keeps it; the extension does not rewrite the list, so add `file:download` with the **Add to command executor** button.
+
 The reference tab opens from the command palette as **Show Commands Reference** under Help, and carries the text editor icon.
 
 ## Agent skill

package/lib/index.js

@@ -9,6 +9,7 @@ import { CommandsReferenceWidget } from './widget';
 var CommandIDs;
 (function (CommandIDs) {
     CommandIDs.open = 'jupyterlab-commands-reference:open';
+    CommandIDs.download = 'file:download';
 })(CommandIDs || (CommandIDs = {}));
 /**
  * The id of this plugin. It is also the id of its settings schema.
@@ -70,6 +71,43 @@ const plugin = {
             command: CommandIDs.open,
             category: 'Help'
         });
+        // Download a file the contents API serves to the computer that runs
+        // the browser tab.
+        app.commands.addCommand(CommandIDs.download, {
+            label: 'Download File',
+            caption: 'Download a file from the server to the local computer',
+            describedBy: () => ({
+                args: {
+                    type: 'object',
+                    properties: {
+                        path: {
+                            type: 'string',
+                            description: 'the file path relative to the server root'
+                        }
+                    },
+                    required: ['path']
+                }
+            }),
+            execute: async (args) => {
+                const path = typeof args.path === 'string' ? args.path : '';
+                if (!path) {
+                    throw new Error('file:download requires a non-empty path argument');
+                }
+                const model = await app.serviceManager.contents.get(path, {
+                    content: false
+                });
+                if (model.type === 'directory') {
+                    throw new Error(`file:download refuses a directory: ${path}`);
+                }
+                const url = await app.serviceManager.contents.getDownloadUrl(model.path);
+                const element = document.createElement('a');
+                element.href = url;
+                element.download = '';
+                document.body.appendChild(element);
+                element.click();
+                document.body.removeChild(element);
+            }
+        });
         if (settings) {
             relay = new RelayClient({
                 app,

package/lib/widget.js

@@ -47,7 +47,8 @@ export class CommandsReferenceWidget extends Widget {
         this._searchInput = document.createElement('input');
         this._searchInput.type = 'text';
         this._searchInput.placeholder = 'Filter commands...';
-        this._searchInput.className = 'jp-CommandsReferenceWidget-search';
+        this._searchInput.className =
+            'jp-CommandsReferenceWidget-search jp-mod-styled';
         this._searchInput.addEventListener('input', () => {
             this._filterCommands();
         });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jupyterlab_commands_extension",
-    "version": "1.0.18",
+    "version": "1.1.3",
     "description": "Display all available JupyterLab commands with their full reference IDs and arguments in a dedicated tab",
     "keywords": [
         "jupyter",

package/schema/plugin.json

@@ -21,7 +21,8 @@
         "console:create",
         "terminal:create-new",
         "launcher:create",
-        "jupyterlab-commands-reference:open"
+        "jupyterlab-commands-reference:open",
+        "file:download"
       ]
     }
   },

package/src/__tests__/file-download.spec.ts

@@ -0,0 +1,121 @@
+import type { JupyterFrontEnd } from '@jupyterlab/application';
+import type { ICommandPalette } from '@jupyterlab/apputils';
+import type { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { CommandRegistry } from '@lumino/commands';
+
+// The tests never run the reference-tab command, so mock the UI modules it
+// reaches for: the real ones pull an untranspiled ESM chain.
+jest.mock('@jupyterlab/apputils', () => ({
+  MainAreaWidget: jest.fn()
+}));
+jest.mock('@jupyterlab/ui-components', () => ({
+  textEditorIcon: null
+}));
+
+import plugin from '../index';
+
+const COMMAND_ID = 'file:download';
+
+interface IFakeApp {
+  app: JupyterFrontEnd;
+  get: jest.Mock;
+  getDownloadUrl: jest.Mock;
+}
+
+/**
+ * Activate the plugin with a registry whose settings load fails, so the relay
+ * never starts, and return the contents mocks the command executes against.
+ */
+async function activatePlugin(): Promise<IFakeApp> {
+  const commands = new CommandRegistry();
+  const get = jest.fn();
+  const getDownloadUrl = jest.fn();
+  const app = {
+    commands,
+    serviceManager: { contents: { get, getDownloadUrl } }
+  } as unknown as JupyterFrontEnd;
+  const palette = { addItem: jest.fn() } as unknown as ICommandPalette;
+  const registry = {
+    load: jest.fn().mockRejectedValue(new Error('no settings in this test'))
+  } as unknown as ISettingRegistry;
+  await plugin.activate(app, palette, registry);
+  return { app, get, getDownloadUrl };
+}
+
+function spyOnAnchorClick(): jest.Mock {
+  const clicked = jest.fn();
+  jest.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(function (
+    this: HTMLAnchorElement
+  ) {
+    clicked({ element: this, parent: this.parentNode });
+  });
+  return clicked;
+}
+
+describe('file:download', () => {
+  it('registers the command with the describedBy path argument', async () => {
+    const { app } = await activatePlugin();
+
+    expect(app.commands.hasCommand(COMMAND_ID)).toBe(true);
+    expect(app.commands.label(COMMAND_ID)).toBe('Download File');
+    const description = await app.commands.describedBy(COMMAND_ID);
+    const args = description.args as Record<string, any>;
+    expect(args.type).toBe('object');
+    expect(args.properties.path.type).toBe('string');
+    expect(args.properties.path.description).toBe(
+      'the file path relative to the server root'
+    );
+    expect(args.required).toEqual(['path']);
+  });
+
+  it('rejects when path is missing or not a non-empty string', async () => {
+    const { app, get } = await activatePlugin();
+
+    await expect(app.commands.execute(COMMAND_ID, {})).rejects.toThrow(
+      'non-empty path'
+    );
+    await expect(
+      app.commands.execute(COMMAND_ID, { path: '' })
+    ).rejects.toThrow('non-empty path');
+    await expect(app.commands.execute(COMMAND_ID, { path: 3 })).rejects.toThrow(
+      'non-empty path'
+    );
+    expect(get).not.toHaveBeenCalled();
+  });
+
+  it('rejects a directory and clicks nothing', async () => {
+    const { app, get, getDownloadUrl } = await activatePlugin();
+    get.mockResolvedValue({ type: 'directory', path: 'data' });
+    const clicked = spyOnAnchorClick();
+
+    await expect(
+      app.commands.execute(COMMAND_ID, { path: 'data' })
+    ).rejects.toThrow(/directory: data/);
+    expect(get).toHaveBeenCalledWith('data', { content: false });
+    expect(getDownloadUrl).not.toHaveBeenCalled();
+    expect(clicked).not.toHaveBeenCalled();
+  });
+
+  it('downloads a file through a temporary anchor', async () => {
+    const { app, get, getDownloadUrl } = await activatePlugin();
+    get.mockResolvedValue({ type: 'file', path: 'data/report.csv' });
+    const url = 'http://host/files/data/report.csv';
+    getDownloadUrl.mockResolvedValue(url);
+    const clicked = spyOnAnchorClick();
+
+    await expect(
+      app.commands.execute(COMMAND_ID, { path: 'data/report.csv' })
+    ).resolves.toBeUndefined();
+    expect(get).toHaveBeenCalledWith('data/report.csv', { content: false });
+    expect(getDownloadUrl).toHaveBeenCalledWith('data/report.csv');
+    expect(clicked).toHaveBeenCalledTimes(1);
+    const { element: anchor, parent } = clicked.mock.calls[0][0] as {
+      element: HTMLAnchorElement;
+      parent: Node | null;
+    };
+    expect(anchor.href).toBe(url);
+    expect(anchor.download).toBe('');
+    expect(parent).toBe(document.body);
+    expect(document.querySelector('a')).toBeNull();
+  });
+});

package/src/index.ts

@@ -17,6 +17,7 @@ import { CommandsReferenceWidget } from './widget';
  */
 namespace CommandIDs {
   export const open = 'jupyterlab-commands-reference:open';
+  export const download = 'file:download';
 }
 
 /**
@@ -103,6 +104,46 @@ const plugin: JupyterFrontEndPlugin<void> = {
       category: 'Help'
     });
 
+    // Download a file the contents API serves to the computer that runs
+    // the browser tab.
+    app.commands.addCommand(CommandIDs.download, {
+      label: 'Download File',
+      caption: 'Download a file from the server to the local computer',
+      describedBy: () => ({
+        args: {
+          type: 'object',
+          properties: {
+            path: {
+              type: 'string',
+              description: 'the file path relative to the server root'
+            }
+          },
+          required: ['path']
+        }
+      }),
+      execute: async args => {
+        const path = typeof args.path === 'string' ? args.path : '';
+        if (!path) {
+          throw new Error('file:download requires a non-empty path argument');
+        }
+        const model = await app.serviceManager.contents.get(path, {
+          content: false
+        });
+        if (model.type === 'directory') {
+          throw new Error(`file:download refuses a directory: ${path}`);
+        }
+        const url = await app.serviceManager.contents.getDownloadUrl(
+          model.path
+        );
+        const element = document.createElement('a');
+        element.href = url;
+        element.download = '';
+        document.body.appendChild(element);
+        element.click();
+        document.body.removeChild(element);
+      }
+    });
+
     if (settings) {
       relay = new RelayClient({
         app,

package/src/widget.ts

@@ -69,7 +69,8 @@ export class CommandsReferenceWidget extends Widget {
     this._searchInput = document.createElement('input');
     this._searchInput.type = 'text';
     this._searchInput.placeholder = 'Filter commands...';
-    this._searchInput.className = 'jp-CommandsReferenceWidget-search';
+    this._searchInput.className =
+      'jp-CommandsReferenceWidget-search jp-mod-styled';
     this._searchInput.addEventListener('input', () => {
       this._filterCommands();
     });

package/style/base.css

@@ -10,6 +10,7 @@
   flex-direction: column;
   height: 100%;
   overflow: hidden;
+  container-type: inline-size;
 }
 
 /* Header with search and count */
@@ -23,23 +24,28 @@
   flex-shrink: 0;
 }
 
-/* Search input */
-.jp-CommandsReferenceWidget-search {
+/*
+ * Search input. jp-mod-styled supplies the same properties at a higher
+ * specificity, so each rule repeats the class after it.
+ */
+input.jp-mod-styled.jp-CommandsReferenceWidget-search {
   flex: 1;
-  padding: 6px 10px;
+  height: 24px;
+  padding: 0 9px;
   border: 1px solid var(--jp-border-color1);
-  border-radius: 4px;
+  border-radius: 2px;
   background: var(--jp-layout-color0);
   color: var(--jp-ui-font-color1);
   font-size: var(--jp-ui-font-size1);
   outline: none;
 }
 
-.jp-CommandsReferenceWidget-search:focus {
+input.jp-mod-styled.jp-CommandsReferenceWidget-search:focus {
   border-color: var(--jp-brand-color1);
+  box-shadow: none;
 }
 
-.jp-CommandsReferenceWidget-search::placeholder {
+input.jp-mod-styled.jp-CommandsReferenceWidget-search::placeholder {
   color: var(--jp-ui-font-color3);
 }
 
@@ -60,6 +66,7 @@
 /* Commands table */
 .jp-CommandsReferenceWidget-table {
   width: 100%;
+  table-layout: fixed;
   border-collapse: collapse;
   font-size: var(--jp-ui-font-size1);
 }
@@ -73,21 +80,29 @@
 }
 
 .jp-CommandsReferenceWidget-table th {
-  padding: 8px 12px;
+  box-sizing: border-box;
+  padding: 6px 12px;
+  overflow: hidden;
   text-align: left;
-  font-weight: 600;
-  color: var(--jp-ui-font-color1);
-  border-bottom: 2px solid var(--jp-border-color1);
+  text-overflow: ellipsis;
   white-space: nowrap;
+  font-size: 10px;
+  font-weight: 600;
+  line-height: 1;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--jp-ui-font-color3);
+  border-bottom: 1px solid var(--jp-border-color2);
 }
 
 /* Table cells */
 .jp-CommandsReferenceWidget-table td {
+  box-sizing: border-box;
   padding: 6px 12px;
   border-bottom: 1px solid var(--jp-border-color2);
   color: var(--jp-ui-font-color1);
   vertical-align: top;
-  max-width: 300px;
+  white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
 }
@@ -101,6 +116,43 @@
   white-space: nowrap;
 }
 
+/* Command executor cell - the row action sits at the right edge */
+.jp-CommandsReferenceWidget-executor {
+  text-align: right;
+}
+
+/* In-row action button */
+.jp-CommandsReferenceWidget-add {
+  display: inline-block;
+  box-sizing: border-box;
+  max-width: 100%;
+  height: 20px;
+  padding: 0 8px;
+  overflow: hidden;
+  border: 1px solid transparent;
+  border-radius: 2px;
+  background: transparent;
+  color: var(--jp-ui-font-color2);
+  font-family: inherit;
+  font-size: var(--jp-ui-font-size0);
+  line-height: 18px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  vertical-align: top;
+  cursor: pointer;
+}
+
+/* Added state, and no settings to add to */
+.jp-CommandsReferenceWidget-add:disabled {
+  opacity: 0.45;
+  cursor: default;
+}
+
+.jp-CommandsReferenceWidget-add:enabled:hover {
+  background: var(--jp-layout-color2);
+  color: var(--jp-ui-font-color1);
+}
+
 /* Alternating row colors */
 .jp-CommandsReferenceWidget-table tbody tr:nth-child(even) {
   background: var(--jp-layout-color1);
@@ -115,27 +167,84 @@
   background: var(--jp-layout-color2);
 }
 
-/* Column widths */
+/* Column widths - five shares summing to 100% under the fixed layout */
 .jp-CommandsReferenceWidget-table th:nth-child(1),
 .jp-CommandsReferenceWidget-table td:nth-child(1) {
-  width: 30%;
-  min-width: 200px;
+  width: 25%;
 }
 
 .jp-CommandsReferenceWidget-table th:nth-child(2),
 .jp-CommandsReferenceWidget-table td:nth-child(2) {
-  width: 20%;
+  width: 17%;
 }
 
 .jp-CommandsReferenceWidget-table th:nth-child(3),
 .jp-CommandsReferenceWidget-table td:nth-child(3) {
-  width: 30%;
+  width: 26%;
+}
+
+.jp-CommandsReferenceWidget-table th:nth-child(4) {
+  width: 17%;
 }
 
-.jp-CommandsReferenceWidget-table th:nth-child(4),
 .jp-CommandsReferenceWidget-table td:nth-child(4) {
-  width: 20%;
+  width: 17%;
   font-family: var(--jp-code-font-family);
   font-size: var(--jp-code-font-size);
   color: var(--jp-ui-font-color2);
 }
+
+.jp-CommandsReferenceWidget-table th:nth-child(5),
+.jp-CommandsReferenceWidget-table td:nth-child(5) {
+  width: 15%;
+}
+
+/* Adaptive columns - keyed to the panel width, not the viewport. Narrower blocks come later so they win. */
+@container (max-width: 1099px) {
+  .jp-CommandsReferenceWidget-table th:nth-child(3),
+  .jp-CommandsReferenceWidget-table td:nth-child(3) {
+    display: none;
+  }
+
+  .jp-CommandsReferenceWidget-table th:nth-child(1),
+  .jp-CommandsReferenceWidget-table td:nth-child(1) {
+    width: 29%;
+  }
+
+  .jp-CommandsReferenceWidget-table th:nth-child(2),
+  .jp-CommandsReferenceWidget-table td:nth-child(2) {
+    width: 21%;
+  }
+
+  .jp-CommandsReferenceWidget-table th:nth-child(4),
+  .jp-CommandsReferenceWidget-table td:nth-child(4) {
+    width: 32%;
+  }
+
+  .jp-CommandsReferenceWidget-table th:nth-child(5),
+  .jp-CommandsReferenceWidget-table td:nth-child(5) {
+    width: 18%;
+  }
+}
+
+@container (max-width: 899px) {
+  .jp-CommandsReferenceWidget-table th:nth-child(4),
+  .jp-CommandsReferenceWidget-table td:nth-child(4) {
+    display: none;
+  }
+
+  .jp-CommandsReferenceWidget-table th:nth-child(1),
+  .jp-CommandsReferenceWidget-table td:nth-child(1) {
+    width: 47%;
+  }
+
+  .jp-CommandsReferenceWidget-table th:nth-child(2),
+  .jp-CommandsReferenceWidget-table td:nth-child(2) {
+    width: 32%;
+  }
+
+  .jp-CommandsReferenceWidget-table th:nth-child(5),
+  .jp-CommandsReferenceWidget-table td:nth-child(5) {
+    width: 21%;
+  }
+}