cockle

In-browser bash-like shell implemented in a combination of TypeScript and WebAssembly.

Used in the JupyterLite terminal extension.

Try it out outside of JupyterLite on GitHub Pages at https://jupyterlite.github.io/cockle.

Commands of the following types are supported:

1. Built-in TypeScript commands such as history. The source code for these is within this repo.
2. WebAssembly commands, from C/C++ source code, compiled into .js and .wasm files. These are usually built by Emscripten-forge although they can be manually built, and are added to a deployment during the deployment build process.
3. JavaScript commands that are loaded and run in the same as WebAssembly commands except they have a .js file and no .wasm file. There is an example of creating a JavaScript command from TypeScript source code for use in the Jupyterlite terminal in the terminal-javascript-command repo.
4. External commands which are TypeScript commands that run in the main browser UI thread rather than the WebWorker that the cockle shell runs in. These are registered when a cockle Shell is constructed. There is an example of an external command which is packaged as a JupyterLite extension in the terminal-external-command repo.

Emscripten-forge packages containing WebAssembly commands that are currently supported and tested are as follows. Each package contains a single commmand with the same name as the package unless otherwise specified:

• coreutils: multiple core commands including cat, cp, echo, ls, mkdir, mv, rm, touch, uname, and wc
• git2cpp: a git implementation
• grep
• less
• lua
• nano
• sed
• tree
• vim

Version compatibility

The filesystem used in cockle is built using a specific version of Emscripten, and for maximum compatibility the WebAssembly commands used in cockle should be built using the same version of Emscripten. WebAssembly commands built on Emscripten-forge are hosted on different prefix.dev channels depending on the Emscripten version.

| cockle version | emscripten version | prefix.dev channel | | ------------------- | -------------------- | ---------------------- | | >= 1.4.0 | 4.0.9 | emscripten-forge-4x | | >= 0.1.14, <= 1.3.0 | 3.1.73 | emscripten-forge-dev |

Build

micromamba env create -f environment-dev.yml
micromamba activate cockle
npm install
npm run build
npm run lint:check

You can use conda, mamba or pixi instead of micromamba here. A copy of micromamba is installed into the cockle environment; this is needed to support the emscripten-wasm32 platform in the demo and tests.

Demo

The cockle repository includes a demo so that you can easily try it out interactively in a web browser. Once you have built cockle, build the demo using:

cd demo
npm install
npm run build

and then serve he demo using:

npm run serve

and open a browser at the specified URL:

The demo is served with cross-origin headers so that is supports synchronous stdin via both SharedArrayBuffer and ServiceWorker. Use cockle-config stdin to check the current settings, and cockle-config stdin sw to switch to using the ServiceWorker.

The demo can also be served with a local CORS proxy which is useful for trying out git clone of remote repositories. For this use:

npm run serve-with-cors

Testing

The test directory contains unit tests and playwright integration tests which can be built and run as follows:

cd test
npm install
npx playwright install --with-deps chromium
npm run build
npm run test

You can interactively run individual playwright tests using npm run test:integration:ui. The testing framework serves its own CORS proxy using cors-anywhere so that git clone of github repositories can be tested without using an external CORS proxy that may be rate limited or otherwise restricted.

In addition, the demo directory contains separate visual tests that can be run in the same way. Only Linux screenshots are stored within the repository.