{"id":22382355,"url":"https://github.com/jcoreio/script-tools","last_synced_at":"2025-03-26T19:40:45.519Z","repository":{"id":33636507,"uuid":"159084207","full_name":"jcoreio/script-tools","owner":"jcoreio","description":"Helpers for common scripting tasks like modifying configuration files","archived":false,"fork":false,"pushed_at":"2023-08-03T21:56:14.000Z","size":2624,"stargazers_count":0,"open_issues_count":20,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-01T18:38:15.093Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jcoreio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-25T23:23:27.000Z","updated_at":"2023-07-25T19:30:06.000Z","dependencies_parsed_at":"2025-02-01T01:51:25.460Z","dependency_job_id":null,"html_url":"https://github.com/jcoreio/script-tools","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fscript-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fscript-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fscript-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fscript-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcoreio","download_url":"https://codeload.github.com/jcoreio/script-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245726708,"owners_count":20662544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-05T00:12:41.163Z","updated_at":"2025-03-26T19:40:45.492Z","avatar_url":"https://github.com/jcoreio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JCore Script Tools\n\nHelpers for common scripting tasks like modifying configuration files\n\n## Installation\n\n`pnpm install --save @jcoreio/script-tools`\n\nor\n\n`yarn add @jcoreio/script-tools`\n\n## Standalone Functions\n\n####`exec`\n\nPromisified version of `child_process.exec` that also prints the command being called and\nand includes the original command in any error message\n\n```js\nconst { exec } = require('@jcoreio/script-tools')\n\nconst stdout = (await exec('git pull')).stdout\n```\n\n####`execRemote`\n\nExecutes a command on a remote host via SSH. Disables SSH host key checking by default.\nTo re-enable SSH host key checking, pass `strictHostKeyChecking: true`.\n\nOptions:\n\n- `host`: string, required: remote hostname\n- `user`: string, optional: username for remote login\n- `keyFile`: string, optional: location of the SSH key pair to access the remote host\n- `command`: string, required: command to run on the remote host\n- `prefix`: string, optional: optionally prefix piped output with the specified value. Disabled by default.\n- `spawnOpts:`\n  - `sudo`: boolean, optional: true if the ssh command should be run with sudo. Defaults to false.\n  - `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.\n\n```js\nconst { execRemote } = require('@jcoreio/script-tools')\n\nawait execRemote({\n  host: 'remotehost.com',\n  user: 'ubuntu',\n  keyFile: '~/key.pem',\n  command: 'sudo reboot',\n  spawnOpts: {\n    captureStdio: true,\n  },\n})\n```\n\n####`lineInFile`\n\nEnsures that a line exists in a file. Optionally replaces a line matching a specified pattern.\n\nOptions:\n\n- `file`: string, required: path of the destination file\n- `line`: string, required: line to add or replace\n- `replace`: string, optional: pattern of line to replace\n- `insertAfter`: string, optional: insert the line after the specified line\n- `newLineAtEnd`: boolean, optional: true if the file should have a newline at the end. Defaults to true.\n- `sudo`: boolean, optional: true if sudo should be used when writing the file. Defaults to false.\n- `mode`: string, optional: file permissions to set, e.g. `'775'`\n- `owner`: string, optional: file owner to set\n- `group`: string, optional: file group to set\n\n```js\nconst { lineInFile } = require('@jcoreio/script-tools')\n\nawait lineInFile({\n  file: '/etc/myPackage.conf',\n  line: 'maxWorkers = 2',\n  replace: 'maxWorkers',\n  sudo: true,\n  owner: 'root',\n  group: 'root',\n})\n```\n\n####`spawn`\n\nPromisified version of `child_process.spawn` that also prints the command being called and\npipes stdio to the parent process by default\n\nArguments:\n\n- `command`: string, required: command to run\n- `arguments`: Array\u003cstring\u003e, optional: arguments\n- `options`: Object, optional:\n  - `sudo`: boolean, optional: true if the ssh command should be run with sudo. Defaults to false.\n  - `prefix`: string, optional: optional prefix to prepend to each line of stderr / stdout from the child process\n  - `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.\n\n```js\nconst { spawn } = require('@jcoreio/script-tools')\n\nawait spawn('git', ['clone', 'https://github.com/myorg/myrepo'], {\n  captureStdio: true,\n})\n```\n\n####`writeFile`\n\nWrites a file if its contents do not already match, and optionally sets the file's permissions\n\nArguments:\n\n- `file`: string, required: file path to write\n- `contents`: string, required: file contents to write\n- `options`: Object, optional:\n  - `sudo`: boolean, optional: true if sudo should be used when writing the file. Defaults to false.\n  - `mode`: string, optional: file permissions to set, e.g. `'775'`\n  - `owner`: string, optional: file owner to set\n  - `group`: string, optional: file group to set\n\n```js\nconst { writeFile } = require('@jcoreio/script-tools')\n\nawait writeFile('.gitignore', 'node_modules', {\n  mode: '775',\n  owner: 'root',\n  group: 'root',\n})\n```\n\n## `ProcessHandler` class\n\nEnsures that child processes are terminated when the parent process exits\n\nConstructor options:\n\n- `maxProcesses`: number, optional: the maximum number of simultaneous running processes. Defaults to 100. If this\n  limit is exceeded, an Error will be thrown when the next process is added.\n\n```js\nconst { ProcessHandler } = require('@jcoreio/script-tools')\n\nconst handler = new ProcessHandler({ maxProcesses: 10 })\n\nawait handler.exec('docker kill my-container')\n\nawait handler.spawn('git', ['pull'])\n\nawait handler.execRemote({\n  host: 'myhost.mycompany.com',\n  command: 'uptime',\n})\n\nconst child = require('child_process').spawn('ls', ['-l'])\nhandler.killOnExit(child)\n\nhandler.killAll()\n```\n\nThe following methods work the same as their standaline counterparts, and also return\na process that will be terminated when the parent process exits:\n\n- `exec`\n- `execRemote`\n- `spawn`\n\n#####`killOnExit`\n\nMonitors an already-launched process and kills it when the parent process exits\n\nArguments:\n\n- `process`: ChildProcess, required: process to kill when the parent process exits\n\n#####`killAll`\n\nKills all processes that are being monitored. This action is run automatically when\nnode is about to exit.\n\n## License\n\n[Apache-2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcoreio%2Fscript-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcoreio%2Fscript-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcoreio%2Fscript-tools/lists"}