README
JCore Script Tools
Helpers for common scripting tasks like modifying configuration files
Installation
npm install --save @jcoreio/script-tools
or
yarn add @jcoreio/script-tools
Standalone Functions
exec
Promisified version of child_process.exec
that also prints the command being called and
and includes the original command in any error message
const {exec} = require('@jcoreio/script-tools')
const stdout = (await exec('git pull')).stdout
execRemote
Executes a command on a remote host via SSH. Disables SSH host key checking by default.
To re-enable SSH host key checking, pass strictHostKeyChecking: true
.
Options:
host
: string, required: remote hostnameuser
: string, optional: username for remote loginkeyFile
: string, optional: location of the SSH key pair to access the remote hostcommand
: string, required: command to run on the remote hostprefix
: string, optional: optionally prefix piped output with the specified value. Disabled by default.spawnOpts:
sudo
: boolean, optional: true if the ssh command should be run with sudo. Defaults to false.captureStdio
: boolean, optional: true if the process's stdio should be captured for later use as well as being piped through to the parent process. Defaults to false.
const {execRemote} = require('@jcoreio/script-tools')
await execRemote({
host: 'remotehost.com',
user: 'ubuntu',
keyFile: '~/key.pem',
command: 'sudo reboot',
spawnOpts: {
captureStdio: true
}
})
lineInFile
Ensures that a line exists in a file. Optionally replaces a line matching a specified pattern.
Options:
file
: string, required: path of the destination fileline
: string, required: line to add or replacereplace
: string, optional: pattern of line to replaceinsertAfter
: string, optional: insert the line after the specified linenewLineAtEnd
: boolean, optional: true if the file should have a newline at the end. Defaults to true.sudo
: boolean, optional: true if sudo should be used when writing the file. Defaults to false.mode
: string, optional: file permissions to set, e.g.'775'
owner
: string, optional: file owner to setgroup
: string, optional: file group to set
const {lineInFile} = require('@jcoreio/script-tools')
await lineInFile({
file: '/etc/myPackage.conf',
line: 'maxWorkers = 2',
replace: 'maxWorkers',
sudo: true,
owner: 'root',
group: 'root',
})
spawn
Promisified version of child_process.spawn
that also prints the command being called and
pipes stdio to the parent process by default
Arguments:
command
: string, required: command to runarguments
: Array, optional: arguments options
: Object, optional:sudo
: boolean, optional: true if the ssh command should be run with sudo. Defaults to false.prefix
: string, optional: optional prefix to prepend to each line of stderr / stdout from the child processcaptureStdio
: boolean, optional: true if the process's stdio should be captured for later use as well as being piped through to the parent process. Defaults to false.
const {spawn} = require('@jcoreio/script-tools')
await spawn('git', ['clone', 'https://github.com/myorg/myrepo'], {
captureStdio: true
})
writeFile
Writes a file if its contents do not already match, and optionally sets the file's permissions
Arguments:
file
: string, required: file path to writecontents
: string, required: file contents to writeoptions
: Object, optional:sudo
: boolean, optional: true if sudo should be used when writing the file. Defaults to false.mode
: string, optional: file permissions to set, e.g.'775'
owner
: string, optional: file owner to setgroup
: string, optional: file group to set
const {writeFile} = require('@jcoreio/script-tools')
await writeFile('.gitignore', 'node_modules', {mode: '775', owner: 'root', group: 'root'})
class ProcessHandler
Ensures that child processes are terminated when the parent process exits
Constructor options:
maxProcesses
: number, optional: the maximum number of simultaneous running processes. Defaults to 100. If this limit is exceeded, an Error will be thrown when the next process is added.
const {ProcessHandler} = require('@jcoreio/script-tools')
const handler = new ProcessHandler({maxProcesses: 10})
await handler.exec('docker kill my-container')
await handler.spawn('git', ['pull'])
await handler.execRemote({
host: 'myhost.mycompany.com',
command: 'uptime'
})
const child = require('child_process').spawn('ls', ['-l'])
handler.killOnExit(child)
handler.killAll()
The following methods work the same as their standaline counterparts, and also return a process that will be terminated when the parent process exits:
exec
execRemote
spawn
killOnExit
Monitors an already-launched process and kills it when the parent process exits
Arguments:
process
: ChildProcess, required: process to kill when the parent process exits
killAll
Kills all processes that are being monitored. This action is run automatically when node is about to exit.