@j-o-r/sh 0.0.1

package/src/ProcessPromise.js

@@ -0,0 +1,323 @@
+// Copyright 2021 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// 
+//
+// Original Source: zx
+// Link to Original Source: https://github.com/google/zx
+// Reason for Using This Code: 
+// The core functionality of this code is highly beneficial. However, certain parts of the original code 
+// were overwriting the global namespace with core libraries and variables. This was causing conflicts with 
+// other packages (for instance, fetch) and introducing unexpected elements into my code base.
+// Changes Made: 
+// - The code has been or is being reformatted to comply with ES2020 standards.
+// - Some methods were added and existing ones were modified to enhance usability.
+// - The namespace has been changed from '$' to 'SH'.
+// Modified by: jorrit.duin+sh[AT]gmail.com
+
+import { spawn } from 'node:child_process';
+import assert from 'node:assert';
+import { log, errnoMessage, exitCodeInfo, noop, parseDuration, psTree } from './utils.js';
+import ProcessOutput from './ProcessOutput.js';
+/** 
+* @typedef {Function} resolver
+* @param {ProcessOutput} value
+*/
+/** 
+* @typedef {Function} rejecter
+* @param {ProcessOutput} value
+*/
+/**
+* @typedef {Function} PromiseConstruct 
+* @param {resolver} resolve
+* @param {rejecter} reject
+*/
+
+class ProcessPromise extends Promise {
+	#command = '';
+	#from = '';
+	/** @type {resolver} */
+	#resolve = () => { };
+	/** @type {rejecter} */
+	#reject = () => { };
+	#snapshot = {};
+	#stdio = ['inherit', 'pipe', 'pipe'];
+	#nothrow = false;
+	#quiet = false;
+	#resolved = false;
+	#halted = false;
+	#piped = false;
+	#prerun = noop;
+	#postrun = noop;
+	/**
+	* @param {PromiseConstruct} p - A function that takes two arguments, resolve and reject.
+	*/
+	constructor(p) {
+    super(p)
+	}
+	/**
+	* Set the environment 
+	* and the 
+	* @param {string} cmd - Command to execute
+	* @param {string} from - Position in the codfe where this is triggred from
+	* @param {function} resolve - Promise resolve method
+	* @param {function} reject - Reject method
+	* @param {object} options - Settings (options default)
+	*/
+	_bind(cmd, from, resolve, reject, options) {
+		this.#command = cmd;
+		this.#from = from;
+		this.#resolve = resolve;
+		this.#reject = reject;
+		this.#snapshot = { ...options };
+	}
+	/**
+	* Run the promise
+	*/
+	run() {
+		const ENV = this.#snapshot;
+		if (this.child) return this; // The _run() can be called from a few places.
+		this.#prerun(); // In case $1.pipe($2), the $2 returned, and on $2._run() invoke $1._run().
+		log({
+			kind: 'cmd',
+			cmd: this.#command,
+			verbose: ENV.verbose && !this.#quiet,
+		});
+		const cwd = ENV['processCwd'];
+		this.child = spawn(ENV.prefix + this.#command, {
+			cwd,
+			// cwd: $.cwd ?? $[processCwd],
+			shell: typeof ENV.shell === 'string' ? ENV.shell : true,
+			stdio: this.#stdio,
+			windowsHide: true,
+			env: ENV.env,
+		});
+		this.child.on('close', (code, signal) => {
+			let message = `exit code: ${code}`;
+			if (code != 0 || signal != null) {
+				message = `${stderr || '\n'}    at ${this.#from}`;
+				message += `\n    exit code: ${code}${exitCodeInfo(code) ? ' (' + exitCodeInfo(code) + ')' : ''}`;
+				if (signal != null) {
+					message += `\n    signal: ${signal}`;
+				}
+			}
+			let output = new ProcessOutput(code, signal, stdout, stderr, combined, message);
+			if (code === 0 || this.#nothrow) {
+				this.#resolve(output);
+			}
+			else {
+				this.#reject(output);
+			}
+			this.#resolved = true;
+		});
+		this.child.on('error', (err) => {
+			const message = `${err.message}\n` +
+				`    errno: ${err.errno} (${errnoMessage(err.errno)})\n` +
+				`    code: ${err.code}\n` +
+				`    at ${this.#from}`;
+			this.#reject(new ProcessOutput(null, null, stdout, stderr, combined, message));
+			this.#resolved = true;
+		});
+		let stdout = '', stderr = '', combined = '';
+		/** @param {Blob} data */
+		const onStdout = (data) => {
+			log({ kind: 'stdout', data, verbose: ENV.verbose && !this.#quiet });
+			stdout += data;
+			combined += data;
+		};
+		/** @param {Blob} data */
+		const onStderr = (data) => {
+			log({ kind: 'stderr', data, verbose: ENV.verbose && !this.#quiet });
+			stderr += data;
+			combined += data;
+		};
+		if (!this.#piped)
+			this.child.stdout?.on('data', onStdout); // If process is piped, don't collect or print output.
+		this.child.stderr?.on('data', onStderr); // Stderr should be printed regardless of piping.
+		this.#postrun(); // In case $1.pipe($2), after both subprocesses are running, we can pipe $1.stdout to $2.stdin.
+		if (this._timeout && this._timeoutSignal) {
+			const t = setTimeout(() => this.kill(this._timeoutSignal), this._timeout);
+			this.finally(() => clearTimeout(t)).catch(noop);
+		}
+		return this;
+	}
+	/**
+	* stdin child stream
+	* @retruns {Writeable}
+	*/
+	get stdin() {
+		this.stdio('pipe');
+		this.run();
+		assert(this.child);
+		if (this.child.stdin == null)
+			throw new Error('The stdin of subprocess is null.');
+		return this.child.stdin;
+	}
+	/**
+	* stdout child stream
+	* @retruns {Readable}
+	*/
+	get stdout() {
+		this.run();
+		assert(this.child);
+		if (this.child.stdout == null)
+			throw new Error('The stdout of subprocess is null.');
+		return this.child.stdout;
+	}
+	/**
+	* stderr child stream
+	* @retruns {Readable}
+	*/
+	get stderr() {
+		this.run();
+		assert(this.child);
+		if (this.child.stderr == null)
+			throw new Error('The stderr of subprocess is null.');
+		return this.child.stderr;
+	}
+	/**
+	* process exit code
+	* @returns {Promise<number>}
+	*/
+	get exitCode() {
+		return this.then((p) => p.exitCode, (p) => p.exitCode);
+	}
+	then(onfulfilled, onrejected) {
+		if (this.isHalted && !this.child) {
+			throw new Error('The process is halted!');
+		}
+		return super.then(onfulfilled, onrejected);
+	}
+	catch(onrejected) {
+		return super.catch(onrejected);
+	}
+	/**
+	* Pipe the output to the input to the next Promise
+	* @example
+	* const res = await SH`ls -FLa`.pipe(SH`grep package.json`);
+	*/
+	pipe(dest) {
+		if (typeof dest == 'string')
+			throw new Error('The pipe() method does not take strings. Forgot SH?');
+		if (this.#resolved) {
+			if (dest instanceof ProcessPromise)
+				dest.stdin.end(); // In case of piped stdin, we may want to close stdin of dest as well.
+			throw new Error("The pipe() method shouldn't be called after promise is already resolved!");
+		}
+		this.#piped = true;
+		if (dest instanceof ProcessPromise) {
+			dest.stdio('pipe');
+			dest._prerun = this.run.bind(this);
+			dest._postrun = () => {
+				if (!dest.child)
+					throw new Error('Access to stdin of pipe destination without creation a subprocess.');
+				this.stdout.pipe(dest.stdin);
+			};
+			return dest;
+		}
+		else {
+			this._postrun = () => this.stdout.pipe(dest);
+			return this;
+		}
+	}
+	/**
+	* Send a KILL signal to the child process
+	*/
+	async kill(signal = 'SIGTERM') {
+		if (!this.child)
+			throw new Error('Trying to kill a process without creating one.');
+		if (!this.child.pid)
+			throw new Error('The process pid is undefined.');
+		let children = await psTree(this.child.pid);
+		for (const p of children) {
+			try {
+				process.kill(+p.PID, signal);
+			}
+			catch (e) { }
+		}
+		try {
+			process.kill(this.child.pid, signal);
+		}
+		catch (e) { }
+	}
+	stdio(stdin, stdout = 'pipe', stderr = 'pipe') {
+		this.#stdio = [stdin, stdout, stderr];
+		return this;
+	}
+	/**
+	* Do not throw
+	*/
+	nothrow() {
+		this.#nothrow = true;
+		return this;
+	}
+	/**
+	* supress log output
+	* SH.verbose = false; does the same
+	*/
+	quiet() {
+		this.#quiet = true;
+		return this;
+	}
+	/**
+	* Show log output in the console
+	*/
+	verbose() {
+		this._quiet = false;
+		return this;
+	}
+	/** 
+	* Set a timeout to kill a process
+	*
+	* @param {string} d - 10s, 1000ms
+	* @param {string} [signal] - default "SIGTERM" Signal to send to kill the proces
+	*/
+	timeout(d, signal = 'SIGTERM') {
+		this._timeout = parseDuration(d);
+		this._timeoutSignal = signal;
+		return this;
+	}
+  /**
+	* stop execution for the next step
+	*/
+	halt() {
+		this.#halted = true;
+		return this;
+	}
+	/** 
+	* @private
+	* Set a prerun action, internal use only
+	* @param {function} f
+	*/
+	set _prerun(f) {
+		// @ts-ignore
+		this.#prerun = f;
+	}
+	/** 
+	* @private
+	* Set a postrun action, internal use only
+	* @param {function} f
+	*/
+	set _postrun(f) {
+		// @ts-ignore
+		this.#postrun = f;
+	}
+  /**
+	* Is this promise halted?
+	* @returns {boolean}
+	*/
+	get isHalted() {
+		return this.#halted;
+	}
+}
+export default ProcessPromise;

package/src/sh.js

@@ -0,0 +1,261 @@
+// Copyright 2021 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// 
+//
+// Original Source: zx
+// Link to Original Source: https://github.com/google/zx
+// Reason for Using This Code: 
+// The core functionality of this code is highly beneficial. However, certain parts of the original code 
+// were overwriting the global namespace with core libraries and variables. This was causing conflicts with 
+// other packages (for instance, fetch) and introducing unexpected elements into my code base.
+// Changes Made: 
+// - The code has been or is being reformatted to comply with ES2020 standards.
+// - Some methods were added and existing ones were modified to enhance usability.
+// - The namespace has been changed from '$' to 'SH'.
+// Modified by: jorrit.duin+sh[AT]gmail.com
+
+import assert from 'node:assert';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import which from 'which';
+import { log, parseDuration, quote, quotePowerShell, } from './utils.js';
+import ProcessPromise from './ProcessPromise.js';
+// const processCwd = Symbol('processCwd');
+const storage = new AsyncLocalStorage();
+
+const defaults = {
+	processCwd: '',
+	verbose: false,
+	env: {},
+	shell: '',
+	prefix: '',
+};
+if (process.platform == 'win32') {
+	defaults.shell = which.sync('powershell.exe');
+} else {
+	defaults.shell = which.sync('bash');
+	defaults.prefix = 'set -euo pipefail;';
+}
+/**
+* Escape CLI arguments
+* @retruns {string}
+*/
+const sanitizeArg = (arg) => {
+	const s = `${arg}`;
+	if (process.platform == 'win32') {
+		return quotePowerShell(s)
+	}
+	return quote(s);
+}
+
+const getStore = () => {
+	return storage.getStore() || defaults;
+}
+
+/**
+* Creates a new ProcessPromise object that represents a command to be executed.
+*
+* @typedef {Function} Shell
+* @type {function}
+* @param {Array} pieces - An array of string literals from a template literal.
+* @param {...*} args - The values to be interpolated into the string literals.
+* @returns {ProcessPromise} A ProcessPromise object that represents the command.
+* @throws {Error} Throws an error if any of the string literals in `pieces` is undefined.
+*
+* @property {boolean} verbose
+*
+* @example
+* const command = await SH`echo 'Hello, world!'`;
+*/
+/** @type {Shell} */
+const SH = new Proxy(function(pieces, ...args) {
+	const from = new Error().stack.split(/^\s*at\s/m)[2].trim();
+	if (pieces.some((p) => p == undefined)) {
+		throw new Error(`Malformed command at ${from}`);
+	}
+	let cmd = pieces[0], i = 0;
+	while (i < args.length) {
+		let s;
+		if (Array.isArray(args[i])) {
+			s = args[i].map((x) => sanitizeArg(x)).join(' ');
+		}
+		else {
+			s = sanitizeArg(args[i]);
+		}
+		cmd += s + pieces[++i];
+	}
+	let resolve, reject;
+
+	const promise = new ProcessPromise((...args) => ([resolve, reject] = args));
+	// re-add the environment
+	defaults.processCwd = process.cwd();
+	defaults.env = process.env,
+		promise._bind(cmd, from, resolve, reject, getStore());
+	// Postpone run to allow promise configuration.
+	setImmediate(() => promise.isHalted || promise.run());
+	return promise;
+}, {
+	// this will get and set from:
+	// defaults OR storage (@see within());
+	set(_, key, value) {
+		const target = key in Function.prototype ? _ : getStore();
+		Reflect.set(target, key, value);
+		return true;
+	},
+	get(_, key) {
+		const target = key in Function.prototype ? _ : getStore();
+		return Reflect.get(target, key);
+	},
+});
+
+/**
+* Create a async context in an sync block
+* @param {function} callback - async function
+* @example
+* const p = within(async () => {
+*		const res = await Promise.all([
+*			SH`sleep 1; echo 1`,
+*			SH`sleep 2; echo 2`,
+*			sleep(2),
+*			SH`sleep 3; echo 3`
+*		]);
+*/
+const within = (callback) => {
+	// @ts-ignore
+	return storage.run({ ...getStore() }, callback);
+}
+/**
+* This function reads the standard input (stdin) for the current process.
+* It is used to get piped content into a script.
+* @example 
+* const content = await stdin();
+*/
+const stdin = async () => {
+	let buf = '';
+	process.stdin.setEncoding('utf8');
+	for await (const chunk of process.stdin) {
+		buf += chunk;
+	}
+	return buf;
+}
+/**
+* This function retries a command a specified number of times.
+* @example 
+* // Retry a command 3 times
+* const p = await retry(3, () => SH`curl -s https://flipwrsi`);
+* 
+* // Retry a command 3 times with an interval of 1 second between each try
+* const p = await retry(3, '1s', () => SH`curl -s https://flipwrsi`);
+* 
+* // Retry a command 3 times with irregular intervals using exponential backoff
+* const p = await retry(3, expBackoff(), () => SH`curl -s https://flipwrsi`);
+*/
+const retry = async (count, a, b) => {
+	const total = count;
+	let callback;
+	let delayStatic = 0;
+	let delayGen;
+	// @ts-ignore
+	const verbose = SH.verbose;
+	if (typeof a == 'function') {
+		callback = a;
+	}
+	else {
+		if (typeof a == 'object') {
+			delayGen = a;
+		}
+		else {
+			delayStatic = parseDuration(a);
+		}
+		// console.log(assert(b));
+		assert(b);
+		callback = b;
+	}
+	let lastErr;
+	let attempt = 0;
+	while (count-- > 0) {
+		attempt++;
+		try {
+			return await callback();
+		}
+		catch (err) {
+			let delay = 0;
+			if (delayStatic > 0)
+				delay = delayStatic;
+			if (delayGen) delay = delayGen.next().value;
+			log({
+				verbose,
+				kind: 'retry',
+				error: ' FAIL ' +
+					` Attempt: ${attempt}${total == Infinity ? '' : `/${total}`}` +
+					(delay > 0 ? `; next in ${delay}ms` : ''),
+			});
+			lastErr = err;
+			if (count == 0)
+				break;
+			if (delay)
+				await sleep(delay);
+		}
+	}
+	throw lastErr;
+}
+/**
+* This function pauses or "sleeps" code execution for a specified duration.
+* @param {string} duration - The duration to pause execution for, e.g., '100ms' or '3s'.
+* 
+* @example
+* 
+* const res = await Promise.all([
+* 	SH`sleep 2; echo 2`,  // Sleep for 2 seconds
+* 	sleep(2),             // Sleep for 2 seconds
+* 	SH`sleep 3; echo 3`   // Sleep for 3 seconds
+* ]);
+*/
+const sleep = (duration) => {
+	return new Promise((resolve) => {
+		setTimeout(resolve, parseDuration(duration));
+	});
+}
+/**
+* Change working directory
+* @param {string} dir
+*/
+const cd = (dir) => {
+	// @ts-ignore
+	const verbose = SH.verbose;
+	log({ kind: 'cd', dir, verbose });
+	process.chdir(dir);
+}
+function* expBackoff(max = '60s', rand = '100ms') {
+	const maxMs = parseDuration(max);
+	const randMs = parseDuration(rand);
+	let n = 1;
+	while (true) {
+		const ms = Math.floor(Math.random() * randMs);
+		yield Math.min(2 ** n++, maxMs) + ms;
+	}
+}
+// const syncCwd = () => {
+// 	if (SH['processCwd'] != process.cwd())
+// 		process.chdir(SH['processCwd']);
+// }
+export {
+	/** @type {Shell} */
+	SH,
+	cd,
+	sleep,
+	retry,
+	stdin,
+	within,
+	expBackoff,
+}