terminatorator v1.0.2

Terminatorator

A convincingly realistic fake terminal for your webapp (demo).

How to use

Add a div to your web page hold the terminal:

<div id="terminal"></div>

Create the terminal:

import {
  createTerminal
} from 'terminatorator'

createTerminal(document.getElementById('terminal'), {
  welcome: 'hello world', // will be printed on start
  theme: 'interlaced', // || 'modern' || 'white' - can be changed at runtime
    // using the `theme` command
  commands: {}, // see `Adding custom commands` below
  files: {}, // see `Files` below
  history: 'cli-history', // the localStorage key used to store terminal history
  user: 'alex' // which user to be logged in as
})

Adding custom commands

const myCommand = {
  handler: (args, session) => {
    // Do something with args and return either:
    //  - nothing
    //  - a string
    //  - a promise of a string
    //  - an Iterable of strings (e.g. an Array or other Symbol.iterator)
    //  - an async iterable of strings
  },
  args: {
    // The optional args object will be passed as the `opts` argument to yargs-parser.
    // See https://www.npmjs.com/package/yargs-parser#requireyargs-parserargs-opts
  }
}

createTerminal(document.getElementById('terminal'), {
  commands: {
    // the key is where in the fs the command should be mounted, the value is
    // the command as defined above
    '/usr/local/bin/my-command': myCommand
  }
})

Command handlers take two arguments - args and session.

Files

You can pre-create any files in the filesystem:

createTerminal(document.getElementById('terminal'), {
  files: {
    // the key is where in the fs the file should be, the value is
    // the attributes of the file. All keys are optional.
    '~/Documents/foo.txt': {
      content: 'hello world', // defaults to an empty string
      owner: 'root' // defaults to the current user
    }
  }
})

args

This is the output of yargs-parser.

session

A object contains the following keys:

{
  env: {
    // key=value of environmental variables
  },
  commands: {
    // path=command of all available commands
  },
  api: {
    exec: (line, { hidden: false }), // call this function with a line of shell
      // input to execute commands, pass hidden: true if you do not wish the
      // command to be echoed to the screen or added to the history
    print: (line) // call this function to add output to the screen
  },
  fs: {
    // call functions here to manpiulate the filesystem directly
    getNode: (path, session), // return a fs node
    mkdir: (path, session, { uid, gid, perms, parents }), // create a directory
      // node with the passed uid, gid and perms - parents: true will created
      // intermediate directories
    write: (path, content, session, { uid, gid, perms, parents }), // create a
      // file node with the passed uid, gid and perms - parents: true will
      // created intermediate directories
    read: (path, session), // read file contents
    rm: (path, session, { recursive }) // remove an fs node
  }
}

Acknowledgements

• Based on dom-terminal by @sasadjolic

What's in a name?

Big up Green Lungs and the Arachnid Egg Sac Crew in Isleworth, easy. Big up Baron Bin Man, easy. Keep it locked on, Ursa Minor, easy. Big up the Terminatorator, easy. Big to Susan and Timothy in Barnes, easy. Boi, you know it! I can't stop! T-WOG$ RIP.