https://github.com/rangermauve/xterm-js-shell
Building block for CLI environments for xterm.js
https://github.com/rangermauve/xterm-js-shell
Last synced: 15 days ago
JSON representation
Building block for CLI environments for xterm.js
- Host: GitHub
- URL: https://github.com/rangermauve/xterm-js-shell
- Owner: RangerMauve
- License: mit
- Created: 2019-04-14T23:28:29.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2019-04-28T00:38:20.000Z (about 6 years ago)
- Last Synced: 2025-03-31T01:23:40.550Z (about 2 months ago)
- Language: JavaScript
- Size: 135 KB
- Stars: 17
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# xterm-js-shell
Building block for CLI environments for xterm.js
```
```
-- OR --
```
npm install --save xterm-js-shell
const XtermJSShell = require('xterm-js-shell/bundle.js')
```
```js
const terminal = new Terminal()
const shell = new XtermJSShell(terminal)
shell
.command('help', async (shell) => {
await shell.printLine(`
Try running one of these commands:
${shell.commands.map((command) => ` - ${command}`).join('\n')}
`)
})
.command('curl', async (shell, [ url ]) => {
const response = await fetch(url)
const text = await response.text()
await shell.print(text)
})
.command('echo', async (shell, args) => {
let message = null
if (args.length) await shell.printLine(args.join(' '))
// Loop until they hit enter without typing anything
while (message = await shell.readLine('')) {
await shell.printLine(message)
}
})
.command('confirm', async (shell) => {
const char = await shell.readChar('Y/n?')
await shell.printLine(char)
})
.command('ssh', async (shell, {url}) => {
// For use with https://github.com/RangerMauve/websocket-shell-service
if(!url) url = 'ws:localhost:8080'
const socket = new WebSocket(url)
let closed = false
socket.onclose = () => {
closed = true
shell.printLine(`Connection to ${url} closed`)
}
socket.onmessage = ({data}) => {
shell.print(data)
}
for await(let data of shell.readStream()) {
if(closed) break
socket.send(data)
}
})
// Start the Read-Eval-Print-Loop
shell.repl()
terminal.open(someElement)
```
Features:
- Takes an [`xterm.js` terminal](https://xtermjs.org/) instance
- Keyboard navigation, history, tab completion [using local-echo](https://github.com/wavesoft/local-echo)
- Able to define commands with a name and an [async function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) or an [async generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of#Iterating_over_async_generators)
- Commands take a `shell` instance, and `args` array
- Commands should be able to `readLine`, `readChar` from the shell
- Commands can `yield` data from the generator for output, or invoke `print` / `printLine`
- Commands should be abele to read raw data from the terminal as a stream
- After a command resolves or rejects, it's `shell` should throw whenever there's input
- Commands should be able to "take over" the terminal to prevent default processing
- Useful for stuff like SSH
- Shell will take back control after the program exits
- Able to `detach` shell from the terminal