BRowserSHell (brsh)

An extensible POSIX Like shell written in Javascript with an accompanying terminal emulator

Demo

What is it?

A POSIX Like Shell backend and Terminal Emulator that lets you embed a working terminal in a webapp, or run an interactive shell against the real filesystem in Node.

Why?

No idea, you tell me

Known Issues

• Input on android is not working

How?

To create a new terminal first add both Terminal and Shell to your page:

<script src="//unpkg.com/brsh@2/dist/shell.min.js"></script>
<script src="//unpkg.com/brsh@2/dist/terminal.min.js"></script>

You may also use it as a node module. Install via npm:

npm i brsh

Import the terminal in your code:

// ESM
import Terminal from 'brsh/terminal';
// CJS
const Terminal = require('brsh/terminal');

You may then implement the terminal like so:

const term = new Terminal({
    el: document.body,
    profile: '/test/.profile',
    cwd: '/test',
    filesystem: { test: { '.profile': 'echo "hi there!"' } },
    cursor: 'blink',
    outputAnimation: 'type',
    animateSpeed: 2
});

The Terminal constructor options extend those of the Shell:

Terminal Specific options

All Shell options are also accepted and forwarded directly to the Shell instance.

| option | required | default | description | | ------ | -------- | ------- | ----------- | | el | Yes | | A HTMLElement to fill with the terminal emulator | | font | No | Roboto Mono | Name of a Google Webfont to use for the console font; a monospace font is recommended | | cursor | No | none | One of: none, block, blink. If block or blink, a cursor block character is shown at the end of the current line | | outputAnimation | No | none | One of: none, type. If type, each character is appended in order for a retro typing effect | | animateSpeed | No | 1 | Characters per browser frame for the type animation. Higher is faster | | onExit | No | null | Function called when the shell session is destroyed. Without this, typing exit will leave the terminal in an ended state | | mobileInput | No | click | One of none or click. Set to click to enable tap-to-focus (and show the on-screen keyboard on mobile) | | lineWrap | No | false | When true, long lines wrap to the next line instead of overflowing |

Shell options

| option | required | default | description | | ------ | -------- | ------- | ----------- | | path | No | '/bin' | Path in which to look for (and register) built-in binaries | | profile | No | | A script to run before user interactivity (see scripts) | | hostname | No | 'browser' | Hostname shown in the prompt | | filesystem | No | {} | Object representing the virtual file system. Classes extending Command are treated as executables. Use exportFileSystem to generate this from a real directory | | permissions | No | {} | Map of virtual absolute paths to Unix mode bits (e.g. { '/bin/myscript.sh': 0o755 }). Files without an entry default to 0o644; function/class entries default to 0o755 | | cwd | No | '/' | Starting working directory | | onFsChange | No | null | Callback fired whenever the virtual filesystem changes (e.g. after a write or delete). Useful for persisting filesystem state | | useRealFilesystem | No | false | When true, uses the real Node.js filesystem instead of the virtual one. Intended for CLI use |

Running an interactive shell in Node

npm run shell starts an interactive brsh session against the real filesystem, with tab completion:

npm run shell

To use it programmatically:

const Shell = require('brsh');

const shell = new Shell({
    useRealFilesystem: true,
    cwd: process.cwd(),
    hostname: 'myapp'
});

Shell Public Methods

| Method | Arguments | Description | | ------ | --------- | ----------- | | onCommand | String command | Run a command string in the shell, e.g. ls -al ./root. Returns a Promise | | tabCompletion | String partial | Returns { path, options } with completion candidates, or null if there are none | | getPrompt | | Returns the current hostname and cwd formatted as a prompt string | | destroy | Number code (optional) | Destroys the shell instance and emits the exit event | | clear | | Emits the clear event |

Shell Events

| Event | Arguments | Description | | ------ | --------- | ----------- | | stdOut | String line | A line of standard output to display to the user | | stdErr | String line | A line of standard error to display to the user | | exitCode | Number code | Exit code of the most recently completed command | | status | String status | Shell status. Shell.STATUS_READY means a new command can be accepted; Shell.STATUS_WORKING means a command is running | | clear | | Fired when the terminal should clear the screen | | exit | Number code | Fired when the shell is destroyed. code is the final exit code |

An example CLI implementation can be found in bin/brsh-shell.js.

Built-in and Local commands

These are simplified versions of standard Unix commands.

Built-ins (always available, no filesystem lookup):

• cat
• echo
• false
• grep
• ls
• printf
• test / [
• true

Local commands:

• alias
• cd
• chmod
• clear
• cp
• curl
• . (dot) / source
• exit
• export
• jsfunction
• ln
• mkdir
• mv
• pwd
• read
• rm
• set
• stat
• touch
• which

Adding new commands

Create a class that extends Command. You can access it via Shell.Command:

class MyCommand extends Shell.Command {
    get name() { return 'mycommand'; }

    run() {
        this.stdOut = 'Hello!';
        return Promise.resolve();
    }
}

Or import Command directly:

// ESM
import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const Command = require('brsh/lib/Command');

For more on writing commands see the lib docs.

Streaming output

Commands can emit output in real time before they finish by calling this.flush():

class ProgressCommand extends Shell.Command {
    get name() { return 'progress'; }

    run() {
        this.stdOut = 'Starting...';
        this.flush();                     // emits stdOut immediately
        return doWork().then(result => result);
    }
}

Writing Scripts

Scripts must start with the shebang #!/sh.js:

#!/sh.js
echo "Hello from a script"

Scripts run in a sub-shell and do not share context with the parent. To persist context changes use source.

Note: when using exportFileSystem, do not give scripts a .js extension — that causes them to be loaded as JavaScript modules rather than script strings.

More Examples

On my website I have extended the functionality adding some simple extra utilities such as an ANSI image viewer and a markdown parser based on open-source node CLI utilities.

See the site in action here

GitHub source code here

How?

To create a new terminal first add both Terminal and Shell to your page like so:

<script src="//unpkg.com/brsh@1/dist/shell.min.js"></script>
<script src="//unpkg.com/brsh@1/dist/terminal.min.js"></script>

You man also use terminal as a node module if you are bundling your code with something like browserify etc Install the module via NPM:

npm i brsh

require the module in your code:

const Terminal = require('brsh/lib/Terminal');

you may then implement the terminal like so:

const term = new Terminal({
    el: document.body,
    profile: '/test/.profile',
    cwd: '/test',
    filesystem: {"test": {".profile": "echo \"hi there!\""}},
    cursor: 'blink',
    outputAnimation: 'type',
    animateSpeed: 2
});

The Terminal constructor Options extend those of the Shell:

Terminal Specific options

| option | required | default | description | | ------ | -------- | ------- | ----------- | | el | Yes | | a HTMLElement to fill with the terminal emulator | | font | No | Roboto Mono | the name of a google webfont to load for the emulators console font, a monospace font is recommended | | cursor | No | none | One of: none, block, bink if block or blink a cursor block character will show at the end of the current line, if bink this will animate with a simple blink | | outputAnimation | No | none | Out of: none, type if type is set each character will be appended in order as to animate a more retro style of console output | | animateSpeed | No | 1 | number of frames to append per browser frame, the higher this number the faster the animation, i would recommend setting this higher than the default value of 1 | | onExit | No | null | function to run should the Shell session be destroyed, whist no required, if this is not set and the user types exit, the terminal will then hang in an ended state | | mobileInput | No | click | One of none or click, set to click to enable focus on the terminal (and show the onscreen keyboard on mobile |

Shell options

| option | required | default | description | | ------ | -------- | ------- | ----------- | | path | No | '/bin' | path in which to look for (and add default entries) binaries | | profile | No | | a script to run before user interactivity (see scripts) | | hostname | No | 'browser' | the hostname of the instance, by default the included terminal emulator shows this as the prompt text| | filesystem | No | {} | an object to represent the file system, any classes that extend Command will be treated as binaries it is probably best to use the included exportFileSystem cli application to convert a directory to a filesystem object | | cwd | No | '/' | the starting CWD for the shell, this affects relative paths to files, binaries and directories just like in any other shell |

you may also wish to implement your own terminal emulator, are use the Shell directly within node CLI in which case you can use just Shell by requiring:

const Shell = require('brsh');

the Shell class can be implemented like so:

const shell = new Shell({
    profile: '/root/.profile',
    cwd: '/root',
    filesystem: require('./filesystem')
});

the following methods and Events are available to interact with the shell instance

Shell Public Methods

| Method | variables | description | | ------ | --------- | ----------- | | onCommand | String command | a command to run in the shell e.g. ls -al ./root | | tabCompletion | String completion candidate | a candidate for completion, for instance ./test/compl, an array will be returned of possible completion strings | | getPrompt | | returns the current hostname and cwd | | destroy | | destroys the instance of the Shell | | clear | | cases the clear event to fire |

Shell Events

| Event | variables | description | | ------ | --------- | ----------- | | stdOut | String line | a single line of standard output from the shell to display to the user | | stdErr | String line | a single line of standard error from the shell to display to the user | | exitCode | Number code | the exit code of any command run in the shell | | status | String Status | Shell status, this should be listened to to check if commands can be accepted, state can be one of: Shell.STATUS_READY or Shell.STATUS_WORKING = 'WORKING', listen for Shell.STATUS_READY to show a prompt to use the user | clear | | this event is fired to tell the Terminal emulator to clear the screen | | exit | Number code | this event if fired when the terminal is destroyed, the code contains the final status code from the shell instance |

an example implementation of this shell running as a CLI can be found here

Builtin and Local commands

these are in general simplified versions of what you will find in a standard unix shell

• cat

• echo

• ls

• alias

• cd

• clear

• export

• source

• which

• exit

adding new commands:

new commands can be added by creating a class that extends Command, you can either access command as a Static property of Shell:

class Test extends Shell.Command {
    ...
}

or Require Command directly:

const Command = require('shell.js/lib/Command');

class Test extends Command {
    ...
}

for more on writing commands see the docs here

Writing Scripts

to create a script you must first set the Shebang interpreter to #!/sh.js as the first line of the file

you may then run any commands in the system which will run as part of the script.

it is important to note that scripts run in a sub-shell and do not share context, if you wish from context changes from your script to persist you will need to use the source command like in Unix.

a final note, if you are using exportFileSystem you must not set the file extension of a script to .js as this will cause to to be interpreted as javascript rather than a script string

More Examples

On my website I have extended the functionality adding some simple extra utilities such as an ANSI image viewer and a markdown parser based on opensource node cli utilites.

See the Site in action here

Github Source Code here