@jupyterlite/terminal 0.1.0

package/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c), Ian Thomas
+Copyright (c), JupyterLite Contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,92 @@
+# jupyterlite_terminal
+
+[![Github Actions Status](https://github.com/jupyterlite/terminal/workflows/Build/badge.svg)](https://github.com/jupyterlite/terminal/actions/workflows/build.yml)
+
+A terminal for JupyterLite.
+
+⚠️ This extension is still in development and not yet ready for general use. ⚠️
+
+![a screenshot showing a terminal running in JupyterLite](https://github.com/jupyterlite/terminal/assets/591645/1b4ff620-e8f2-4abf-b608-6badd66370ac)
+
+## Requirements
+
+- JupyterLite >= 0.4.0
+
+## Install
+
+To install the extension, execute:
+
+```bash
+pip install jupyterlite-terminal
+```
+
+You will also need to install the JupyterLite CLI:
+
+```bash
+python -m pip install --pre jupyterlite-core
+```
+
+## Usage
+
+After installing `jupyterlite-core` and `jupyterlite-terminal`, create a `jupyter-lite.json` file with the following content to activate the terminal extension:
+
+```json
+{
+  "jupyter-lite-schema-version": 0,
+  "jupyter-config-data": {
+    "terminalsAvailable": true
+  }
+}
+```
+
+Then build a new JupyterLite site:
+
+```bash
+jupyter lite build
+```
+
+## Contributing
+
+### Development install
+
+Note: You will need NodeJS to build the extension package.
+
+The `jlpm` command is JupyterLab's pinned version of
+[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
+`yarn` or `npm` in lieu of `jlpm` below.
+
+```bash
+# Clone the repo to your local environment
+# Change directory to the jupyterlite_terminal directory
+# Install package in development mode
+pip install -e "."
+# Link your development version of the extension with JupyterLab
+jupyter labextension develop . --overwrite
+# Rebuild extension Typescript source after making changes
+jlpm build
+```
+
+You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.
+
+```bash
+# Watch the source directory in one terminal, automatically rebuilding when needed
+jlpm watch
+# Run JupyterLab in another terminal
+jupyter lab
+```
+
+Then build a JupyterLite distribution with the extension installed:
+
+```bash
+jupyter lite build
+```
+
+And serve it:
+
+```bash
+jupyter lite serve
+```
+
+### Packaging the extension
+
+See [RELEASE](RELEASE.md)

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+import { JupyterLiteServerPlugin } from '@jupyterlite/server';
+import { ITerminals } from './tokens';
+declare const _default: (JupyterLiteServerPlugin<ITerminals> | JupyterLiteServerPlugin<void>)[];
+export default _default;

package/lib/index.js

@@ -0,0 +1,49 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+import { ITerminals } from './tokens';
+import { Terminals } from './terminals';
+/**
+ * The terminals service plugin.
+ */
+const terminalsPlugin = {
+    id: '@jupyterlite/terminal:plugin',
+    description: 'A terminal for JupyterLite',
+    autoStart: true,
+    provides: ITerminals,
+    activate: async (app) => {
+        console.log('JupyterLab extension @jupyterlite/terminal:plugin is activated!');
+        const { serviceManager } = app;
+        const { contents, serverSettings, terminals } = serviceManager;
+        console.log('terminals available:', terminals.isAvailable());
+        console.log('terminals ready:', terminals.isReady); // Not ready
+        console.log('terminals active:', terminals.isActive);
+        // Not sure this is necessary?
+        await terminals.ready;
+        console.log('terminals ready after await:', terminals.isReady); // Ready
+        return new Terminals(serverSettings.wsUrl, contents);
+    }
+};
+/**
+ * A plugin providing the routes for the terminals service
+ */
+const terminalsRoutesPlugin = {
+    id: '@jupyterlite/terminal:routes-plugin',
+    autoStart: true,
+    requires: [ITerminals],
+    activate: (app, terminals) => {
+        console.log('JupyterLab extension @jupyterlite/terminal:routes-plugin is activated!', terminals);
+        // GET /api/terminals - List the running terminals
+        app.router.get('/api/terminals', async (req) => {
+            const res = terminals.list();
+            // Should return last_activity for each too,
+            return new Response(JSON.stringify(res));
+        });
+        // POST /api/terminals - Start a terminal
+        app.router.post('/api/terminals', async (req) => {
+            const res = await terminals.startNew();
+            // Should return last_activity too.
+            return new Response(JSON.stringify(res));
+        });
+    }
+};
+export default [terminalsPlugin, terminalsRoutesPlugin];

package/lib/terminal.d.ts

@@ -0,0 +1,15 @@
+import { ITerminal } from './tokens';
+export declare class Terminal implements ITerminal {
+    /**
+     * Construct a new Terminal.
+     */
+    constructor(options: ITerminal.IOptions);
+    /**
+     * Get the name of the terminal.
+     */
+    get name(): string;
+    wsConnect(url: string): Promise<void>;
+    private _name;
+    private _fs;
+    private _shell?;
+}

package/lib/terminal.js

@@ -0,0 +1,60 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+import { JupyterFileSystem, Shell } from '@jupyterlite/cockle';
+import { Server as WebSocketServer } from 'mock-socket';
+export class Terminal {
+    /**
+     * Construct a new Terminal.
+     */
+    constructor(options) {
+        this._name = options.name;
+        this._fs = new JupyterFileSystem(options.contentsManager);
+        console.log('==> new Terminal', this._name, this._fs);
+    }
+    /**
+     * Get the name of the terminal.
+     */
+    get name() {
+        return this._name;
+    }
+    async wsConnect(url) {
+        console.log('==> Terminal.wsConnect', url);
+        // const server = new WebSocketServer(url, { mock: false });
+        const server = new WebSocketServer(url);
+        server.on('connection', async (socket) => {
+            console.log('==> server connection', this, socket);
+            const outputCallback = async (output) => {
+                console.log('==> recv from shell:', output);
+                const ret = JSON.stringify(['stdout', output]);
+                socket.send(ret);
+            };
+            this._shell = new Shell(this._fs, outputCallback);
+            console.log('==> shell', this._shell);
+            socket.on('message', async (message) => {
+                const data = JSON.parse(message);
+                console.log('==> socket message', data);
+                const message_type = data[0];
+                const content = data.slice(1);
+                if (message_type === 'stdin') {
+                    await this._shell.input(content[0]);
+                }
+                else if (message_type === 'set_size') {
+                    const rows = content[0];
+                    const columns = content[1];
+                    await this._shell.setSize(rows, columns);
+                }
+            });
+            socket.on('close', async () => {
+                console.log('==> socket close');
+            });
+            socket.on('error', async () => {
+                console.log('==> socket error');
+            });
+            // Return handshake.
+            const res = JSON.stringify(['setup']);
+            console.log('==> Returning handshake via socket', res);
+            socket.send(res);
+            await this._shell.start();
+        });
+    }
+}

package/lib/terminals.d.ts

@@ -0,0 +1,23 @@
+import { Contents, TerminalAPI } from '@jupyterlab/services';
+import { ITerminals } from './tokens';
+/**
+ * A class to handle requests to /api/terminals
+ */
+export declare class Terminals implements ITerminals {
+    /**
+     * Construct a new Terminals object.
+     */
+    constructor(wsUrl: string, contentsManager: Contents.IManager);
+    /**
+     * List the running terminals.
+     */
+    list(): Promise<TerminalAPI.IModel[]>;
+    /**
+     * Start a new kernel.
+     */
+    startNew(): Promise<TerminalAPI.IModel>;
+    private _nextAvailableName;
+    private _wsUrl;
+    private _contentsManager;
+    private _terminals;
+}

package/lib/terminals.js

@@ -0,0 +1,47 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+import { Terminal } from './terminal';
+/**
+ * A class to handle requests to /api/terminals
+ */
+export class Terminals {
+    /**
+     * Construct a new Terminals object.
+     */
+    constructor(wsUrl, contentsManager) {
+        this._terminals = new Map();
+        this._wsUrl = wsUrl;
+        this._contentsManager = contentsManager;
+        console.log('==> Terminals.constructor', this._wsUrl, this._contentsManager);
+    }
+    /**
+     * List the running terminals.
+     */
+    async list() {
+        const ret = [...this._terminals.values()].map(terminal => ({
+            name: terminal.name
+        }));
+        console.log('==> Terminals.list', ret);
+        return ret;
+    }
+    /**
+     * Start a new kernel.
+     */
+    async startNew() {
+        const name = this._nextAvailableName();
+        console.log('==> Terminals.new', name);
+        const term = new Terminal({ name, contentsManager: this._contentsManager });
+        this._terminals.set(name, term);
+        const url = `${this._wsUrl}terminals/websocket/${name}`;
+        await term.wsConnect(url);
+        return { name };
+    }
+    _nextAvailableName() {
+        for (let i = 1;; ++i) {
+            const name = `${i}`;
+            if (!this._terminals.has(name)) {
+                return name;
+            }
+        }
+    }
+}

package/lib/tokens.d.ts

@@ -0,0 +1,43 @@
+import { Contents, TerminalAPI } from '@jupyterlab/services';
+import { Token } from '@lumino/coreutils';
+/**
+ * The token for the Terminals service.
+ */
+export declare const ITerminals: Token<ITerminals>;
+/**
+ * An interface for the Terminals service.
+ */
+export interface ITerminals {
+    /**
+     * List the running terminals.
+     */
+    list: () => Promise<TerminalAPI.IModel[]>;
+    /**
+     * Start a new kernel.
+     */
+    startNew: () => Promise<TerminalAPI.IModel>;
+}
+/**
+ * An interface for a server-side terminal running in the browser.
+ */
+export interface ITerminal {
+    /**
+     * The name of the server-side terminal.
+     */
+    readonly name: string;
+}
+/**
+ * A namespace for ITerminal statics.
+ */
+export declare namespace ITerminal {
+    /**
+     * The instantiation options for an ITerminal.
+     */
+    interface IOptions {
+        /**
+         * The name of the terminal.
+         */
+        name: string;
+        contentsManager: Contents.IManager;
+    }
+}

package/lib/tokens.js

@@ -0,0 +1,7 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+import { Token } from '@lumino/coreutils';
+/**
+ * The token for the Terminals service.
+ */
+export const ITerminals = new Token('@jupyterlite/terminal:ITerminals');

package/package.json

@@ -0,0 +1,204 @@
+{
+    "name": "@jupyterlite/terminal",
+    "version": "0.1.0",
+    "description": "A terminal for JupyterLite",
+    "keywords": [
+        "jupyter",
+        "jupyterlab",
+        "jupyterlite",
+        "jupyterlite-extension"
+    ],
+    "homepage": "https://github.com/jupyterlite/terminal",
+    "bugs": {
+        "url": "https://github.com/jupyterlite/terminal/issues"
+    },
+    "license": "BSD-3-Clause",
+    "author": {
+        "name": "JupyterLite Contributors",
+        "email": ""
+    },
+    "files": [
+        "lib/**/*.{d.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf}",
+        "style/**/*.{css,js,eot,gif,html,jpg,json,png,svg,woff2,ttf}",
+        "src/**/*.{ts,tsx}"
+    ],
+    "main": "lib/index.js",
+    "types": "lib/index.d.ts",
+    "style": "style/index.css",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/jupyterlite/terminal.git"
+    },
+    "scripts": {
+        "build": "jlpm build:lib && jlpm build:labextension:dev",
+        "build:prod": "jlpm clean && jlpm build:lib:prod && jlpm build:labextension",
+        "build:labextension": "jupyter labextension build .",
+        "build:labextension:dev": "jupyter labextension build --development True .",
+        "build:lib": "tsc --sourceMap",
+        "build:lib:prod": "tsc",
+        "clean": "jlpm clean:lib",
+        "clean:lib": "rimraf lib tsconfig.tsbuildinfo",
+        "clean:lintcache": "rimraf .eslintcache .stylelintcache",
+        "clean:labextension": "rimraf jupyterlite_terminal/labextension jupyterlite_terminal/_version.py",
+        "clean:all": "jlpm clean:lib && jlpm clean:labextension && jlpm clean:lintcache",
+        "eslint": "jlpm eslint:check --fix",
+        "eslint:check": "eslint . --cache --ext .ts,.tsx",
+        "install:extension": "jlpm build",
+        "lint": "jlpm stylelint && jlpm prettier && jlpm eslint",
+        "lint:check": "jlpm stylelint:check && jlpm prettier:check && jlpm eslint:check",
+        "prettier": "jlpm prettier:base --write --list-different",
+        "prettier:base": "prettier \"**/*{.ts,.tsx,.js,.jsx,.css,.json,.md}\"",
+        "prettier:check": "jlpm prettier:base --check",
+        "stylelint": "jlpm stylelint:check --fix",
+        "stylelint:check": "stylelint --cache \"style/**/*.css\"",
+        "test": "jest --coverage",
+        "watch": "run-p watch:src watch:labextension",
+        "watch:src": "tsc -w --sourceMap",
+        "watch:labextension": "jupyter labextension watch ."
+    },
+    "dependencies": {
+        "@jupyterlab/services": "^7.2.0",
+        "@jupyterlab/terminal": "^4.2.0",
+        "@jupyterlab/terminal-extension": "^4.2.0",
+        "@jupyterlite/cockle": "^0.0.3",
+        "@jupyterlite/server": "^0.3.0",
+        "@lumino/coreutils": "^2.1.2",
+        "mock-socket": "^9.3.1"
+    },
+    "devDependencies": {
+        "@jupyterlab/builder": "^4.0.0",
+        "@jupyterlab/testutils": "^4.0.0",
+        "@types/jest": "^29.2.0",
+        "@types/json-schema": "^7.0.11",
+        "@types/react": "^18.0.26",
+        "@types/react-addons-linked-state-mixin": "^0.14.22",
+        "@typescript-eslint/eslint-plugin": "^6.1.0",
+        "@typescript-eslint/parser": "^6.1.0",
+        "css-loader": "^6.7.1",
+        "eslint": "^8.36.0",
+        "eslint-config-prettier": "^8.8.0",
+        "eslint-plugin-prettier": "^5.0.0",
+        "jest": "^29.2.0",
+        "npm-run-all": "^4.1.5",
+        "prettier": "^3.0.0",
+        "rimraf": "^5.0.1",
+        "source-map-loader": "^1.0.2",
+        "style-loader": "^3.3.1",
+        "stylelint": "^15.10.1",
+        "stylelint-config-recommended": "^13.0.0",
+        "stylelint-config-standard": "^34.0.0",
+        "stylelint-csstree-validator": "^3.0.0",
+        "stylelint-prettier": "^4.0.0",
+        "typescript": "~5.0.2",
+        "yjs": "^13.5.0"
+    },
+    "sideEffects": [
+        "style/*.css",
+        "style/index.js"
+    ],
+    "styleModule": "style/index.js",
+    "publishConfig": {
+        "access": "public"
+    },
+    "jupyterlab": {
+        "extension": true,
+        "outputDir": "jupyterlite_terminal/labextension"
+    },
+    "jupyterlite": {
+        "liteExtension": true
+    },
+    "eslintIgnore": [
+        "node_modules",
+        "dist",
+        "coverage",
+        "**/*.d.ts",
+        "tests",
+        "**/__tests__",
+        "ui-tests"
+    ],
+    "eslintConfig": {
+        "extends": [
+            "eslint:recommended",
+            "plugin:@typescript-eslint/eslint-recommended",
+            "plugin:@typescript-eslint/recommended",
+            "plugin:prettier/recommended"
+        ],
+        "parser": "@typescript-eslint/parser",
+        "parserOptions": {
+            "project": "tsconfig.json",
+            "sourceType": "module"
+        },
+        "plugins": [
+            "@typescript-eslint"
+        ],
+        "rules": {
+            "@typescript-eslint/naming-convention": [
+                "error",
+                {
+                    "selector": "interface",
+                    "format": [
+                        "PascalCase"
+                    ],
+                    "custom": {
+                        "regex": "^I[A-Z]",
+                        "match": true
+                    }
+                }
+            ],
+            "@typescript-eslint/no-unused-vars": [
+                "warn",
+                {
+                    "args": "none"
+                }
+            ],
+            "@typescript-eslint/no-explicit-any": "off",
+            "@typescript-eslint/no-namespace": "off",
+            "@typescript-eslint/no-use-before-define": "off",
+            "@typescript-eslint/quotes": [
+                "error",
+                "single",
+                {
+                    "avoidEscape": true,
+                    "allowTemplateLiterals": false
+                }
+            ],
+            "curly": [
+                "error",
+                "all"
+            ],
+            "eqeqeq": "error",
+            "prefer-arrow-callback": "error"
+        }
+    },
+    "prettier": {
+        "singleQuote": true,
+        "trailingComma": "none",
+        "arrowParens": "avoid",
+        "endOfLine": "auto",
+        "overrides": [
+            {
+                "files": "package.json",
+                "options": {
+                    "tabWidth": 4
+                }
+            }
+        ]
+    },
+    "stylelint": {
+        "extends": [
+            "stylelint-config-recommended",
+            "stylelint-config-standard",
+            "stylelint-prettier/recommended"
+        ],
+        "plugins": [
+            "stylelint-csstree-validator"
+        ],
+        "rules": {
+            "csstree/validator": true,
+            "property-no-vendor-prefix": null,
+            "selector-class-pattern": "^([a-z][A-z\\d]*)(-[A-z\\d]+)*$",
+            "selector-no-vendor-prefix": null,
+            "value-no-vendor-prefix": null
+        }
+    }
+}

package/src/__tests__/jupyterlite_terminal.spec.ts

@@ -0,0 +1,9 @@
+/**
+ * Example of [Jest](https://jestjs.io/docs/getting-started) unit tests
+ */
+
+describe('jupyterlite-terminal', () => {
+  it('should be tested', () => {
+    expect(1 + 1).toEqual(2);
+  });
+});

package/src/index.ts

@@ -0,0 +1,69 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import {
+  JupyterLiteServer,
+  JupyterLiteServerPlugin,
+  Router
+} from '@jupyterlite/server';
+
+import { ITerminals } from './tokens';
+import { Terminals } from './terminals';
+
+/**
+ * The terminals service plugin.
+ */
+const terminalsPlugin: JupyterLiteServerPlugin<ITerminals> = {
+  id: '@jupyterlite/terminal:plugin',
+  description: 'A terminal for JupyterLite',
+  autoStart: true,
+  provides: ITerminals,
+  activate: async (app: JupyterLiteServer) => {
+    console.log(
+      'JupyterLab extension @jupyterlite/terminal:plugin is activated!'
+    );
+
+    const { serviceManager } = app;
+    const { contents, serverSettings, terminals } = serviceManager;
+    console.log('terminals available:', terminals.isAvailable());
+    console.log('terminals ready:', terminals.isReady); // Not ready
+    console.log('terminals active:', terminals.isActive);
+
+    // Not sure this is necessary?
+    await terminals.ready;
+    console.log('terminals ready after await:', terminals.isReady); // Ready
+
+    return new Terminals(serverSettings.wsUrl, contents);
+  }
+};
+
+/**
+ * A plugin providing the routes for the terminals service
+ */
+const terminalsRoutesPlugin: JupyterLiteServerPlugin<void> = {
+  id: '@jupyterlite/terminal:routes-plugin',
+  autoStart: true,
+  requires: [ITerminals],
+  activate: (app: JupyterLiteServer, terminals: ITerminals) => {
+    console.log(
+      'JupyterLab extension @jupyterlite/terminal:routes-plugin is activated!',
+      terminals
+    );
+
+    // GET /api/terminals - List the running terminals
+    app.router.get('/api/terminals', async (req: Router.IRequest) => {
+      const res = terminals.list();
+      // Should return last_activity for each too,
+      return new Response(JSON.stringify(res));
+    });
+
+    // POST /api/terminals - Start a terminal
+    app.router.post('/api/terminals', async (req: Router.IRequest) => {
+      const res = await terminals.startNew();
+      // Should return last_activity too.
+      return new Response(JSON.stringify(res));
+    });
+  }
+};
+
+export default [terminalsPlugin, terminalsRoutesPlugin];

package/src/terminal.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { JupyterFileSystem, Shell, IFileSystem } from '@jupyterlite/cockle';
+
+import { JSONPrimitive } from '@lumino/coreutils';
+
+import {
+  Server as WebSocketServer,
+  Client as WebSocketClient
+} from 'mock-socket';
+
+import { ITerminal } from './tokens';
+
+export class Terminal implements ITerminal {
+  /**
+   * Construct a new Terminal.
+   */
+  constructor(options: ITerminal.IOptions) {
+    this._name = options.name;
+    this._fs = new JupyterFileSystem(options.contentsManager);
+    console.log('==> new Terminal', this._name, this._fs);
+  }
+
+  /**
+   * Get the name of the terminal.
+   */
+  get name(): string {
+    return this._name;
+  }
+
+  async wsConnect(url: string) {
+    console.log('==> Terminal.wsConnect', url);
+
+    // const server = new WebSocketServer(url, { mock: false });
+    const server = new WebSocketServer(url);
+
+    server.on('connection', async (socket: WebSocketClient) => {
+      console.log('==> server connection', this, socket);
+
+      const outputCallback = async (output: string) => {
+        console.log('==> recv from shell:', output);
+        const ret = JSON.stringify(['stdout', output]);
+        socket.send(ret);
+      };
+
+      this._shell = new Shell(this._fs, outputCallback);
+      console.log('==> shell', this._shell);
+
+      socket.on('message', async (message: any) => {
+        const data = JSON.parse(message) as JSONPrimitive[];
+        console.log('==> socket message', data);
+        const message_type = data[0];
+        const content = data.slice(1);
+
+        if (message_type === 'stdin') {
+          await this._shell!.input(content[0] as string);
+        } else if (message_type === 'set_size') {
+          const rows = content[0] as number;
+          const columns = content[1] as number;
+          await this._shell!.setSize(rows, columns);
+        }
+      });
+
+      socket.on('close', async () => {
+        console.log('==> socket close');
+      });
+
+      socket.on('error', async () => {
+        console.log('==> socket error');
+      });
+
+      // Return handshake.
+      const res = JSON.stringify(['setup']);
+      console.log('==> Returning handshake via socket', res);
+      socket.send(res);
+
+      await this._shell!.start();
+    });
+  }
+
+  private _name: string;
+  private _fs: IFileSystem;
+  private _shell?: Shell;
+}

package/src/terminals.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Contents, TerminalAPI } from '@jupyterlab/services';
+
+import { Terminal } from './terminal';
+import { ITerminals } from './tokens';
+
+/**
+ * A class to handle requests to /api/terminals
+ */
+export class Terminals implements ITerminals {
+  /**
+   * Construct a new Terminals object.
+   */
+  constructor(wsUrl: string, contentsManager: Contents.IManager) {
+    this._wsUrl = wsUrl;
+    this._contentsManager = contentsManager;
+    console.log(
+      '==> Terminals.constructor',
+      this._wsUrl,
+      this._contentsManager
+    );
+  }
+
+  /**
+   * List the running terminals.
+   */
+  async list(): Promise<TerminalAPI.IModel[]> {
+    const ret = [...this._terminals.values()].map(terminal => ({
+      name: terminal.name
+    }));
+    console.log('==> Terminals.list', ret);
+    return ret;
+  }
+
+  /**
+   * Start a new kernel.
+   */
+  async startNew(): Promise<TerminalAPI.IModel> {
+    const name = this._nextAvailableName();
+    console.log('==> Terminals.new', name);
+    const term = new Terminal({ name, contentsManager: this._contentsManager });
+    this._terminals.set(name, term);
+
+    const url = `${this._wsUrl}terminals/websocket/${name}`;
+    await term.wsConnect(url);
+
+    return { name };
+  }
+
+  private _nextAvailableName(): string {
+    for (let i = 1; ; ++i) {
+      const name = `${i}`;
+      if (!this._terminals.has(name)) {
+        return name;
+      }
+    }
+  }
+
+  private _wsUrl: string;
+  private _contentsManager: Contents.IManager;
+  private _terminals: Map<string, Terminal> = new Map();
+}

package/src/tokens.ts

@@ -0,0 +1,55 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Contents, TerminalAPI } from '@jupyterlab/services';
+
+import { Token } from '@lumino/coreutils';
+
+/**
+ * The token for the Terminals service.
+ */
+export const ITerminals = new Token<ITerminals>(
+  '@jupyterlite/terminal:ITerminals'
+);
+
+/**
+ * An interface for the Terminals service.
+ */
+export interface ITerminals {
+  /**
+   * List the running terminals.
+   */
+  list: () => Promise<TerminalAPI.IModel[]>;
+
+  /**
+   * Start a new kernel.
+   */
+  startNew: () => Promise<TerminalAPI.IModel>;
+}
+
+/**
+ * An interface for a server-side terminal running in the browser.
+ */
+export interface ITerminal {
+  /**
+   * The name of the server-side terminal.
+   */
+  readonly name: string;
+}
+
+/**
+ * A namespace for ITerminal statics.
+ */
+export namespace ITerminal {
+  /**
+   * The instantiation options for an ITerminal.
+   */
+  export interface IOptions {
+    /**
+     * The name of the terminal.
+     */
+    name: string;
+
+    contentsManager: Contents.IManager;
+  }
+}

package/style/base.css

@@ -0,0 +1,5 @@
+/*
+    See the JupyterLab Developer Guide for useful CSS Patterns:
+
+    https://jupyterlab.readthedocs.io/en/stable/developer/css.html
+*/

package/style/index.css

@@ -0,0 +1 @@
+@import url('base.css');

package/style/index.js

@@ -0,0 +1 @@
+import './base.css';