stmux

stmux
=====

Simple Terminal Multiplexing for Node Environments

Abstract
--------

This is a simple terminal multiplexing utility for Node.js
environments. It is inspired by the awesome and unreachable
tmux native Unix utility. The stmux utility
is intended to provide just a very tiny subset of the original
tmux functionality, but in a portable way for
bare Node.js environments and with some special features for application
build environments. Most notably, stmux has a built-time error
detection and notification feature, can automatically restart terminated commands,
and can automatically close or wait after all spawned commands have
successfully or unsuccessfully terminated.

Internally, stmux is based on the awesome
Blessed screen rendering environment
and emulates full XTerm-compatible pseudo-terminals
to the spawned programs with the help of Blessed XTerm
and the underlying XTerm.js terminal rendering
and node-pty pseudo-terminal
integration modules.

Example
-------

The following command...

``
$ stmux -- [ [ -s 1/3 bash .. vim ] : mc ]
`

...leads to the following particular terminal multiplexing environment,
where GNU bash, Vim and Midnight Commander are running side-by-side
inside their own XTerm emulating terminal widget (and, just for fun,
CTRL+a ? was pressed to open up the stmux help window):

!stmux usage

Intention
---------

This utility is primarily intended to be used from within a
package.json script to easily side-by-side run various NPM-based
commands in a Node.js build-time environment. Sample package.json
entries from a top-level NPM-based project follows, which on npm run
dev allows one to conveniently run the commands of two sub-projects.
First, the build-time of the frontend user interface (UI) project.
Second, the build-time of the backend server (SV) project. Third, the
run-time of the backend server project.

`js
{
...
"dependencies": {
"stmux": "*"
},
"scripts": {
"install": "npm run install:ui && npm run install:sv",
"install:ui": "cd ui && npm install",
"install:sv": "cd sv && npm install",

"build": "npm run build:ui && npm run build:sv",
"build:ui": "cd ui && npm run build",
"build:sv": "cd sv && npm run build",

"start": "cd sv && npm start",

"clean": "npm run clean:ui && npm run clean:sv",
"clean:ui": "cd ui && npm run clean",
"clean:sv": "cd sv && npm run clean",

"dev": "stmux -w always -e ERROR -m beep,system -- [ [ \"npm run dev:ui\" .. \"npm run dev:sv\" ] : -s 1/3 -f \"npm start\" ]",
"dev:ui": "cd ui && npm run build:watch",
"dev:sv": "cd sv && npm run build:watch"
}
}
`

In case of a build-time error in the frontend user interface (SV), the
result might be similar to the following one:

!stmux example

Installation
------------

`
$ npm install -g stmux
`

$3

The dependencies of stmux transitively include
node-pty which must be
built with node-gyp
during npm install. Please check out the documentation of
node-gyp on how to provide the
necessary C/C++ compiler environment on your operating system.

* macOS: install the "Command Line Tools" under
"Preferences > Downloads" in Xcode.
* Windows: open an elevated cmd.exe and run the commands
npm install --global windows-build-tools and
npm config set msvs_version 2015 --global
* Windows Subsystem for Linux (WSL), Ubuntu distribution: run the commands
sudo apt-get update and
sudo apt-get install -y python make build-essential
* Under Linux or FreeBSD you usually don't have to do anything.

Usage
-----

The following command line arguments are supported:

`
$ stmux [-h] [-V] [-w ] [-a ] [-t