BRowserSHell (brsh)

An extensible shell written in Javascript with an accompanying terminal emulator

Demo

What is it?

A Unix like Shell backend and Terminal Emulator that allows you top create a Terminal within you webapp.

Why?

No idea, you tell me

Known Issues

• Input on android is not working
• scripting isn't complete yet, if, while etc not implemented
• commands can't currently stream output, it is only returned once the app process finishes

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