@zokugun/exec-lite 0.0.0 → 0.3.0

package/lib/esm/exec-process.mjs

@@ -0,0 +1,235 @@
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+import { err, ok, stringifyError } from '@zokugun/xtry';
+import { exec } from './exec.mjs';
+import { normalizeCommand } from './utils/command/normalizeCommand.mjs';
+import { normalizeOptions } from './utils/normalizeOptions.mjs';
+import { combineStreams } from './utils/stream/combineStreams.mjs';
+import { readStream } from './utils/stream/readStream.mjs';
+class ExecProcess {
+    _aborted = false;
+    _args;
+    _command;
+    _cwd;
+    _failed = false;
+    _options;
+    _process;
+    _processClosed;
+    _resolveClose;
+    _signal;
+    _start;
+    _streamErr;
+    _streamOut;
+    _thrownError;
+    constructor(command, args, options) {
+        this._options = {
+            timeout: undefined,
+            windowsHide: true,
+            ...options,
+        };
+        this._command = command;
+        this._args = args ?? [];
+        this._processClosed = new Promise((resolve) => {
+            this._resolveClose = resolve;
+        });
+    } // }}}
+    get aborted() {
+        return this._aborted;
+    } // }}}
+    get error() {
+        return this._thrownError;
+    } // }}}
+    get exitCode() {
+        return this._process?.exitCode ?? undefined;
+    } // }}}
+    get failed() {
+        return this._failed;
+    } // }}}
+    get killed() {
+        return this._process?.killed === true;
+    } // }}}
+    get pid() {
+        return this._process?.pid;
+    } // }}}
+    get process() {
+        return this._process;
+    } // }}}
+    get signalCode() {
+        return this._process?.signalCode ?? undefined;
+    } // }}}
+    kill(signal) {
+        return this._process?.kill(signal) === true;
+    } // }}}
+    pipe(command, args, options) {
+        return exec(command, args, {
+            ...options,
+            stdin: this,
+        });
+    } // }}}
+    spawn() {
+        this._start = process.hrtime.bigint();
+        this.reset();
+        const normalizedOptions = normalizeOptions(this._options);
+        this._cwd = normalizedOptions.cwd;
+        if (normalizedOptions.signal) {
+            this._signal = normalizedOptions.signal;
+        }
+        const { command: spawnCommand, args: spawnArgs, options: spawnOptions } = normalizeCommand(this._command, this._args, normalizedOptions);
+        let task;
+        try {
+            task = spawn(spawnCommand, spawnArgs, spawnOptions);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this._thrownError = error;
+            }
+            else {
+                this._thrownError = new Error(String(error));
+            }
+            return;
+        }
+        if (task.stderr) {
+            this._streamErr = task.stderr;
+        }
+        if (task.stdout) {
+            this._streamOut = task.stdout;
+        }
+        this._process = task;
+        task.once('error', this.onError.bind(this));
+        task.once('close', this.onClose.bind(this));
+        if (task.stdin) {
+            const { stdin } = this._options;
+            if (typeof stdin === 'string') {
+                task.stdin.end(stdin);
+            }
+            else if (typeof stdin === 'object' && stdin !== null && 'process' in stdin) {
+                stdin.process?.stdout?.pipe(task.stdin);
+            }
+        }
+    } // }}}
+    // eslint-disable-next-line ts/explicit-member-accessibility
+    async *[Symbol.asyncIterator]() {
+        const handle = this._process;
+        if (!handle) {
+            return;
+        }
+        const streams = [];
+        if (this._streamErr) {
+            streams.push(this._streamErr);
+        }
+        if (this._streamOut) {
+            streams.push(this._streamOut);
+        }
+        const streamCombined = combineStreams(streams);
+        const rl = readline.createInterface({ input: streamCombined });
+        for await (const chunk of rl) {
+            // eslint-disable-next-line ts/no-unnecessary-type-conversion
+            yield chunk.toString();
+        }
+        await this._processClosed;
+        handle.removeAllListeners();
+        if (this._thrownError || (this.exitCode !== 0 && this.exitCode !== undefined) || this.signalCode !== undefined) {
+            this._failed = true;
+        }
+    } // }}}
+    // eslint-disable-next-line ts/promise-function-async
+    then(onfulfilled, onrejected) {
+        return this.toResult().then((result) => {
+            if (onfulfilled) {
+                return onfulfilled(result);
+            }
+            return result;
+        }, onrejected);
+    } // }}}
+    onClose() {
+        if (this._resolveClose) {
+            this._resolveClose();
+        }
+    } // }}}
+    onError(error) {
+        if (error.name === 'AbortError' && (!(error.cause instanceof Error) || error.cause.name !== 'TimeoutError')) {
+            this._aborted = true;
+            return;
+        }
+        this._thrownError = error;
+    } // }}}
+    reset() {
+        this._aborted = false;
+        this._process = undefined;
+        this._processClosed = new Promise((resolve) => {
+            this._resolveClose = resolve;
+        });
+        this._signal = undefined;
+        this._streamErr = undefined;
+        this._streamOut = undefined;
+        this._thrownError = undefined;
+    } // }}}
+    toFailure(error) {
+        this._failed = true;
+        if (this._options.resultMode === 'merged') {
+            return stringifyError(error);
+        }
+        const result = {
+            args: this._args,
+            canceled: this._signal?.aborted ?? false,
+            command: this._command,
+            cwd: this._cwd,
+            durationMs: Number(process.hrtime.bigint() - this._start) / 1e6,
+            error,
+            exitCode: this.exitCode,
+            merged: '',
+            signalCode: this.signalCode,
+        };
+        return err(result);
+    } // }}}
+    async toResult() {
+        if (this._thrownError) {
+            return this.toFailure(this._thrownError);
+        }
+        const task = this._process;
+        if (!task) {
+            return this.toFailure(new Error('No process was started'));
+        }
+        const context = { merged: '' };
+        const [stdout, stderr] = await Promise.all([
+            this._streamOut ? readStream(this._streamOut, context) : '',
+            this._streamErr ? readStream(this._streamErr, context) : '',
+        ]);
+        await this._processClosed;
+        const { stdin } = this._options;
+        if (stdin && typeof stdin !== 'string') {
+            await stdin;
+        }
+        task.removeAllListeners();
+        if (this._thrownError) {
+            return this.toFailure(this._thrownError);
+        }
+        if (this._options.resultMode === 'merged') {
+            if ((this.exitCode !== 0 && this.exitCode !== undefined) || this.signalCode !== undefined) {
+                this._failed = true;
+            }
+            return context.merged;
+        }
+        const result = {
+            args: this._args,
+            command: this._command,
+            cwd: this._cwd,
+            durationMs: Number(process.hrtime.bigint() - this._start) / 1e6,
+            exitCode: this.exitCode,
+            merged: context.merged,
+            stderr,
+            stdout,
+        };
+        // if(this._options.stdin instanceof ExecProcess) {
+        // 	result.pipedFrom = this._options.stdin;
+        // }
+        if ((this.exitCode !== 0 && this.exitCode !== undefined) || this.signalCode !== undefined) {
+            this._failed = true;
+            const failure = result;
+            failure.signalCode = this.signalCode;
+            return err(failure);
+        }
+        return ok(result);
+    } // }}}
+}
+export { ExecProcess, };

package/lib/esm/exec.d.mts

@@ -0,0 +1,3 @@
+import type { Options, ResultMode, Subprocess } from './types.mjs';
+declare function exec<M extends ResultMode = 'result'>(command: string, args?: readonly string[] | null, options?: Partial<Options<M>>): Subprocess<M>;
+export { type Options, type ResultMode, type Subprocess, exec, };

package/lib/esm/exec.mjs

@@ -0,0 +1,7 @@
+import { ExecProcess } from './exec-process.mjs';
+function exec(command, args, options) {
+    const subprocess = new ExecProcess(command, args, options);
+    subprocess.spawn();
+    return subprocess;
+}
+export { exec, };

package/lib/esm/index.d.mts

@@ -0,0 +1,4 @@
+export type { Command, ExecFailure, ExecResult, ExecSuccess, KillSignal, Options, ResultMode, StdinOption, StdioOption, Subprocess, } from './types.mjs';
+export { createCommand } from './create-command.mjs';
+export { ExecProcess } from './exec-process.mjs';
+export { exec } from './exec.mjs';

package/lib/esm/index.mjs

@@ -0,0 +1,3 @@
+export { createCommand } from './create-command.mjs';
+export { ExecProcess } from './exec-process.mjs';
+export { exec } from './exec.mjs';

package/lib/esm/types.d.mts

@@ -0,0 +1,70 @@
+import type { ChildProcess, SpawnOptions as ProcessSpawnOptions } from 'node:child_process';
+import type { Result } from '@zokugun/xtry';
+export type Command<M extends ResultMode = 'result'> = {
+    (args?: readonly string[] | null, options?: Partial<Options<M>>): Subprocess<M>;
+    toCwdFirst(): (cwd: string, ...args: string[]) => Subprocess<M>;
+    toFlatArgs(): (...args: string[]) => Subprocess<M>;
+    withOptions(options: Partial<Options<M>>): Command<M>;
+};
+export type ExecFailure = {
+    args: readonly string[];
+    canceled: boolean;
+    cwd?: string;
+    command: string;
+    durationMs: number;
+    error?: Error;
+    exitCode?: number;
+    merged?: string;
+    pipedFrom?: ExecResult;
+    signalCode?: string;
+    stderr?: string;
+    stdout?: string;
+};
+export type ResultMode = 'merged' | 'result';
+export type ExecResult<M extends ResultMode = 'result'> = M extends 'merged' ? string : Result<ExecSuccess, ExecFailure>;
+export type ExecSuccess = {
+    args: readonly string[];
+    command: string;
+    cwd: string;
+    durationMs: number;
+    error?: undefined;
+    exitCode: number;
+    merged: string;
+    pipedFrom?: ExecResult;
+    stderr: string;
+    stdout: string;
+};
+export type KillSignal = Parameters<ChildProcess['kill']>[0];
+export type Options<M extends ResultMode = ResultMode> = Omit<ProcessSpawnOptions, 'cwd' | 'env' | 'stdio'> & Readonly<Partial<{
+    cwd?: string;
+    env: Readonly<Partial<Record<string, string>>>;
+    localDir: string;
+    preferLocal: boolean;
+    resultMode: M;
+    signal: AbortSignal;
+    stderr: StdioOption;
+    stdin: ExecResult | StdinOption | Subprocess<ResultMode>;
+    stdio: readonly [StdinOption, ...readonly StdioOption[]] | SpawnOptions['stdio'];
+    stdout: StdioOption;
+}>>;
+export type SpawnOptions = {
+    cwd: string;
+} & Omit<ProcessSpawnOptions, 'cwd'>;
+export type StdinOption = StdioOption | {
+    readonly string?: string;
+};
+export type StdioOption = Readonly<Exclude<SpawnOptions['stdio'], undefined>[number]>;
+export type Subprocess<M extends ResultMode = 'result'> = AsyncIterable<string> & PromiseLike<ExecResult<M>> & {
+    get aborted(): boolean;
+    get error(): Error | undefined;
+    get exitCode(): number | undefined;
+    get failed(): boolean;
+    kill: (signal?: KillSignal) => boolean;
+    get killed(): boolean;
+    get pid(): number | undefined;
+    pipe: <N extends ResultMode = 'result'>(command: string, args?: readonly string[], options?: Partial<Options> & {
+        resultMode?: N;
+    }) => Subprocess<N>;
+    get process(): ChildProcess | undefined;
+    get signalCode(): string | undefined;
+};

package/lib/esm/types.mjs

@@ -0,0 +1 @@
+export {};

package/lib/esm/utils/combineSignals.d.mts

@@ -0,0 +1 @@
+export declare function combineSignals(signals: AbortSignal[]): AbortSignal;

package/lib/esm/utils/combineSignals.mjs

@@ -0,0 +1,16 @@
+export function combineSignals(signals) {
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort();
+            return signal;
+        }
+        const onAbort = () => {
+            controller.abort(signal.reason);
+        };
+        signal.addEventListener('abort', onAbort, {
+            signal: controller.signal,
+        });
+    }
+    return controller.signal;
+}

package/lib/esm/utils/command/detectShebang.d.mts

@@ -0,0 +1 @@
+export declare function detectShebang(file: string): string | null;

package/lib/esm/utils/command/detectShebang.mjs

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import { basename } from 'node:path';
+const SHEBANG_REGEX = /^#!\s*(.+)/;
+const SIZE = 150;
+export function detectShebang(file) {
+    const buffer = Buffer.alloc(SIZE);
+    let fd = null;
+    try {
+        fd = fs.openSync(file, 'r');
+        fs.readSync(fd, buffer, 0, SIZE, 0);
+    }
+    catch {
+        // do nothing, we'll just assume it's not a shebang
+    }
+    finally {
+        if (fd !== null) {
+            fs.closeSync(fd);
+        }
+    }
+    const match = SHEBANG_REGEX.exec(buffer.toString());
+    if (match === null) {
+        return null;
+    }
+    const line = match[1].trim();
+    const separatorIndex = line.indexOf(' ');
+    const path = separatorIndex !== -1 ? line.slice(0, separatorIndex) : line;
+    const argument = separatorIndex !== -1 ? line.slice(separatorIndex + 1) : '';
+    const binary = basename(path);
+    return binary === 'env' ? argument || null : binary;
+}

package/lib/esm/utils/command/normalizeCommand.d.mts

@@ -0,0 +1,6 @@
+import type { SpawnOptions } from '../../types.mjs';
+export declare function normalizeCommand(command: string, args: readonly string[], options: SpawnOptions): {
+    args: readonly string[];
+    command: string;
+    options: SpawnOptions;
+};

package/lib/esm/utils/command/normalizeCommand.mjs

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import { detectShebang } from './detectShebang.mjs';
+import { resolveCommand } from './resolveCommand.mjs';
+const IS_BATCH_FILE_REGEX = /\.(?:bat|cmd)$/i;
+const IS_EXECUTABLE_REGEX = /\.(?:com|exe)$/i;
+const IS_WINDOWS = process.platform === 'win32';
+const META_CHARS_REGEX = /([ !"%&()*,;<>?[\]^`|])/g;
+export function normalizeCommand(command, args, options) {
+    if (['node', 'node.exe'].includes(command.toLowerCase())) {
+        command = process.execPath;
+        args = [...process.execArgv.filter((flag) => !flag.startsWith('--inspect')), ...args];
+    }
+    if (options.shell === true || !IS_WINDOWS) {
+        return {
+            command,
+            args,
+            options,
+        };
+    }
+    let file = resolveCommand(command, options);
+    if (file !== null) {
+        const shebang = detectShebang(file);
+        if (shebang !== null) {
+            args = [file, ...args];
+            command = shebang;
+            file = resolveCommand(command, options);
+        }
+    }
+    if (file !== null && IS_EXECUTABLE_REGEX.test(file)) {
+        return {
+            command,
+            args,
+            options,
+        };
+    }
+    const needsDoubleEscape = file !== null && IS_BATCH_FILE_REGEX.test(file);
+    const normalizedCommand = path.normalize(command).replace(META_CHARS_REGEX, '^$1');
+    const normalizedArgs = [];
+    for (let arg of args) {
+        arg = arg.replace(/(?=(\\+?))\1(?:"|$)/g, '$1$1\\"');
+        arg = `"${arg}"`;
+        arg = arg.replace(META_CHARS_REGEX, '^$1');
+        if (needsDoubleEscape) {
+            arg = arg.replace(META_CHARS_REGEX, '^$1');
+        }
+        normalizedArgs.push(arg);
+    }
+    return {
+        command: options.env?.comspec ?? 'cmd.exe',
+        args: ['/d', '/s', '/c', `"${[normalizedCommand, ...normalizedArgs].join(' ')}"`],
+        options: { ...options, windowsVerbatimArguments: true },
+    };
+}

package/lib/esm/utils/command/resolveCommand.d.mts

@@ -0,0 +1,2 @@
+import type { SpawnOptions } from '../../types.mjs';
+export declare function resolveCommand(command: string, options: SpawnOptions): string | null;

package/lib/esm/utils/command/resolveCommand.mjs

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getPathFromEnv } from '../env/getPathFromEnv.mjs';
+const CACHE = Object.create(null);
+const DEFAULT_PATH_EXT = ['.EXE', '.CMD', '.BAT', '.COM'];
+export function resolveCommand(command, options) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const pathEnv = getPathFromEnv(env).value;
+    const key = `${command}%%%%${pathEnv}`;
+    if (CACHE[key] !== undefined) {
+        return CACHE[key];
+    }
+    const parts = command.includes('/') || command.includes('\\') ? [''] : [cwd, ...pathEnv.split(path.delimiter)];
+    let pathExt = env.PATHEXT ? env.PATHEXT.split(path.delimiter) : DEFAULT_PATH_EXT;
+    if (command.includes('.') && pathExt[0] !== '') {
+        pathExt = ['', ...pathExt];
+    }
+    for (const part of parts) {
+        const unquoted = part.startsWith('"') && part.endsWith('"') && part.length > 1 ? part.slice(1, -1) : part;
+        const dest = path.resolve(cwd, unquoted, command);
+        for (const ext of [...pathExt, '']) {
+            const destWithExt = dest + ext;
+            try {
+                if (fs.statSync(destWithExt).isFile()) {
+                    CACHE[key] = destWithExt;
+                    return destWithExt;
+                }
+            }
+            catch {
+                // do nothing, it didn't exist
+            }
+        }
+    }
+    CACHE[key] = null;
+    return null;
+}

package/lib/esm/utils/env/addNodeBinToPath.d.mts

@@ -0,0 +1,2 @@
+import type { EnvPathInfo } from './types.mjs';
+export declare function addNodeBinToPath(cwd: string, { value, key }: EnvPathInfo): EnvPathInfo;

package/lib/esm/utils/env/addNodeBinToPath.mjs

@@ -0,0 +1,18 @@
+import path from 'node:path';
+export function addNodeBinToPath(cwd, { value, key }) {
+    const parts = value.split(path.delimiter);
+    const nodeBinPaths = [];
+    let currentPath = cwd;
+    let lastPath;
+    do {
+        nodeBinPaths.push(path.resolve(currentPath, 'node_modules', '.bin'));
+        lastPath = currentPath;
+        currentPath = path.dirname(currentPath);
+    } while (currentPath !== lastPath);
+    nodeBinPaths.push(path.dirname(process.execPath));
+    const newValue = nodeBinPaths.concat(parts).join(path.delimiter);
+    return {
+        key,
+        value: newValue,
+    };
+}

package/lib/esm/utils/env/computeEnv.d.mts

@@ -0,0 +1,2 @@
+import type { EnvLike } from './types.mjs';
+export declare function computeEnv(env: Readonly<EnvLike> | undefined, preferLocal: boolean, localDir: string): Readonly<EnvLike>;

package/lib/esm/utils/env/computeEnv.mjs

@@ -0,0 +1,14 @@
+import { addNodeBinToPath } from './addNodeBinToPath.mjs';
+import { getPathFromEnv } from './getPathFromEnv.mjs';
+export function computeEnv(env, preferLocal, localDir) {
+    const computedEnv = {
+        ...process.env,
+        ...env,
+    };
+    if (!preferLocal) {
+        return computedEnv;
+    }
+    const pathEnvInfo = addNodeBinToPath(localDir, getPathFromEnv(computedEnv));
+    computedEnv[pathEnvInfo.key] = pathEnvInfo.value;
+    return computedEnv;
+}

package/lib/esm/utils/env/getPathFromEnv.d.mts

@@ -0,0 +1,2 @@
+import type { EnvLike, EnvPathInfo } from './types.mjs';
+export declare function getPathFromEnv(env: EnvLike): EnvPathInfo;

package/lib/esm/utils/env/getPathFromEnv.mjs

@@ -0,0 +1,19 @@
+export function getPathFromEnv(env) {
+    for (const key in env) {
+        if (key.toLowerCase() !== 'path') {
+            continue;
+        }
+        const value = env[key];
+        if (!value) {
+            return {
+                key: 'PATH',
+                value: '',
+            };
+        }
+        return { key, value };
+    }
+    return {
+        key: 'PATH',
+        value: '',
+    };
+}

package/lib/esm/utils/env/types.d.mts

@@ -0,0 +1,5 @@
+export type EnvLike = (typeof process)['env'];
+export type EnvPathInfo = {
+    key: string;
+    value: string;
+};

package/lib/esm/utils/env/types.mjs

@@ -0,0 +1 @@
+export {};

package/lib/esm/utils/normalizeOptions.d.mts

@@ -0,0 +1,2 @@
+import type { Options, SpawnOptions } from '../types.mjs';
+export declare function normalizeOptions(options: Options): SpawnOptions;

package/lib/esm/utils/normalizeOptions.mjs

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import { computeEnv } from './env/computeEnv.mjs';
+import { combineSignals } from './combineSignals.mjs';
+export function normalizeOptions(options) {
+    const { cwd, env, preferLocal, resultMode: _resultMode, signal, stderr, stdin, stdio: stdioOption, stdout, ...restOptions } = options;
+    const spawnOptions = restOptions;
+    spawnOptions.cwd = path.resolve(cwd ?? process.cwd());
+    spawnOptions.env = computeEnv(env, preferLocal ?? false, options.localDir ?? spawnOptions.cwd);
+    const signals = [];
+    if (options.timeout !== undefined) {
+        signals.push(AbortSignal.timeout(options.timeout));
+    }
+    if (signal !== undefined) {
+        signals.push(signal);
+    }
+    if (signals.length > 0) {
+        spawnOptions.signal = combineSignals(signals);
+    }
+    const stdio = stdioOption ?? [undefined, stdout, stderr];
+    if (Array.isArray(stdio) && !(typeof stdin === 'string' || (typeof stdin === 'object' && stdin !== null && 'process' in stdin))) {
+        stdio[0] = 'pipe';
+    }
+    spawnOptions.stdio = stdio;
+    return spawnOptions;
+}

package/lib/esm/utils/stream/combineStreams.d.mts

@@ -0,0 +1,2 @@
+import type { Readable } from 'node:stream';
+export declare function combineStreams(streams: Readable[]): Readable;

package/lib/esm/utils/stream/combineStreams.mjs

@@ -0,0 +1,22 @@
+import { PassThrough } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+export function combineStreams(streams) {
+    let streamCount = streams.length;
+    const combined = new PassThrough();
+    if (streamCount === 0) {
+        combined.end();
+        return combined;
+    }
+    const maybeEmitEnd = () => {
+        streamCount -= 1;
+        if (streamCount === 0) {
+            combined.end();
+        }
+    };
+    for (const stream of streams) {
+        pipeline(stream, combined, { end: false })
+            .then(maybeEmitEnd)
+            .catch(maybeEmitEnd);
+    }
+    return combined;
+}

package/lib/esm/utils/stream/readStream.d.mts

@@ -0,0 +1,5 @@
+import type { Readable } from 'node:stream';
+export type StreamContext = {
+    merged: string;
+};
+export declare function readStream(stream: Readable, context: StreamContext): Promise<string>;

package/lib/esm/utils/stream/readStream.mjs

@@ -0,0 +1,13 @@
+export async function readStream(stream, context) {
+    let output = '';
+    try {
+        for await (const chunk of stream) {
+            output += String(chunk);
+            context.merged += String(chunk);
+        }
+    }
+    catch {
+        // suppress errors, child process probably failed to spawn
+    }
+    return output;
+}