JSsh

Contents

• About
• Features
• Development
• Updating
• Installation
• Documentation
• Finally

JavaScript is God’s scripting language. Why not use it as your shell too?

About

jssh is a REPL shell built on QuickJS.
It gives you a Unix-style shell prompt, but everything you type is JavaScript.
Need cat? It’s a JS function. Want echo? Same deal.

Because who doesn’t want their shell to throw exceptions instead of exit codes?

Features

• Run JavaScript interactively at a prompt.
• Unix commands are now JS functions.
• Supports as many colors as your terminal provides.
• Extensible: drop JS files into a commands directory and extend your shell.
• Make it your own by editing the configuration file at ~/.jssh_env.
• Don't like adding ("") after commands? Press tab after writing a command like ls for autocomplete!
• Basic syntax highlighting for JS in the shell.
• Written in C, powered by QuickJS.
• Update the shell after code modifications with a single command.
• Zero shame in declaring JavaScript the one true language.

Installation

1. Clone this repo:

   git clone https://github.com/NatromeTex/jssh.git
   cd jssh

   or

   git clone https://github.com/NatromeTex/jssh.git --recursive 
   cd jssh

   to get the quickjs submodule directly.

   For manual installation: Get the QuickJS source files (version 2020-11-08 recommended). Extract them into /src so you have the quickjs files in /src.

2. Add readline dependencies

   sudo apt-get install libreadline-dev libssh-dev

   This will install the readline library which is required for command history

3. Build with make:

    make

   This will compile JSsh with the core utils and produce the binary at bin/jssh. To add modules like network or fs, run

    sudo make MODULES=network
    sudo make MODULES="network", "fs"

   Note that to install the network dependencies, make will require root privleges to allocate the appropriate permissions. The core dependencies do not require root privleges.

4. Usage

   Run the shell:

   ./bin/jssh

   You will get a prompt like:

   username@hostname:/current/directory$

   From here you can type JavaScript directly:

   1 + 2
   // => 3
   
   echo("hello world")
   // prints "hello world"

   Use CTRL+D to exit.

Updating

After editing the code of the project, just run update() from the root of the project in JSsh and JSsh will handle the rest for you and jump into the new binary.
If there are any errors in the compilation, JSsh will print the debug stack and await edits.

Development

All code is present in /src, entry is in main.c
Built-ins like cat and echo live in utils.c or func.c.
Some base level access like read and write file need to be given to JS using C
Extend by adding more JS-callable functions in C, or by loading .js modules.

Documentation

Most OS primitive functions will be exposed to JS in C APIs, once enough syscalls are available in JS, command integration will move to pure JS.
Refer to DOCS.md for a comprehensive list on the supported functions.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). You are free to run, study, share, and modify this software, but derivative works must also be licensed under the GPL.

See the full text in LICENSE

Closing Words

Use JSsh. Because a TypeError stack trace at the prompt is way more fun than command not found.

Built with ❤️