@zokugun/exec-lite 0.0.0 → 0.3.0

package/lib/cjs/exec.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exec = exec;
+const exec_process_js_1 = require("./exec-process.cjs");
+function exec(command, args, options) {
+    const subprocess = new exec_process_js_1.ExecProcess(command, args, options);
+    subprocess.spawn();
+    return subprocess;
+}

package/lib/cjs/exec.d.cts

@@ -0,0 +1,3 @@
+import type { Options, ResultMode, Subprocess } from './types.cjs';
+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/cjs/index.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exec = exports.ExecProcess = exports.createCommand = void 0;
+var create_command_js_1 = require("./create-command.cjs");
+Object.defineProperty(exports, "createCommand", { enumerable: true, get: function () { return create_command_js_1.createCommand; } });
+var exec_process_js_1 = require("./exec-process.cjs");
+Object.defineProperty(exports, "ExecProcess", { enumerable: true, get: function () { return exec_process_js_1.ExecProcess; } });
+var exec_js_1 = require("./exec.cjs");
+Object.defineProperty(exports, "exec", { enumerable: true, get: function () { return exec_js_1.exec; } });

package/lib/cjs/index.d.cts

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

package/lib/cjs/types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/types.d.cts

@@ -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/cjs/utils/combineSignals.cjs

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.combineSignals = combineSignals;
+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/cjs/utils/combineSignals.d.cts

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

package/lib/cjs/utils/command/detectShebang.cjs

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectShebang = detectShebang;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = require("node:path");
+const SHEBANG_REGEX = /^#!\s*(.+)/;
+const SIZE = 150;
+function detectShebang(file) {
+    const buffer = Buffer.alloc(SIZE);
+    let fd = null;
+    try {
+        fd = node_fs_1.default.openSync(file, 'r');
+        node_fs_1.default.readSync(fd, buffer, 0, SIZE, 0);
+    }
+    catch {
+        // do nothing, we'll just assume it's not a shebang
+    }
+    finally {
+        if (fd !== null) {
+            node_fs_1.default.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 = (0, node_path_1.basename)(path);
+    return binary === 'env' ? argument || null : binary;
+}

package/lib/cjs/utils/command/detectShebang.d.cts

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

package/lib/cjs/utils/command/normalizeCommand.cjs

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCommand = normalizeCommand;
+const node_path_1 = __importDefault(require("node:path"));
+const detectShebang_js_1 = require("./detectShebang.cjs");
+const resolveCommand_js_1 = require("./resolveCommand.cjs");
+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;
+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 = (0, resolveCommand_js_1.resolveCommand)(command, options);
+    if (file !== null) {
+        const shebang = (0, detectShebang_js_1.detectShebang)(file);
+        if (shebang !== null) {
+            args = [file, ...args];
+            command = shebang;
+            file = (0, resolveCommand_js_1.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 = node_path_1.default.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/cjs/utils/command/normalizeCommand.d.cts

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

package/lib/cjs/utils/command/resolveCommand.cjs

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCommand = resolveCommand;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const getPathFromEnv_js_1 = require("../env/getPathFromEnv.cjs");
+const CACHE = Object.create(null);
+const DEFAULT_PATH_EXT = ['.EXE', '.CMD', '.BAT', '.COM'];
+function resolveCommand(command, options) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const pathEnv = (0, getPathFromEnv_js_1.getPathFromEnv)(env).value;
+    const key = `${command}%%%%${pathEnv}`;
+    if (CACHE[key] !== undefined) {
+        return CACHE[key];
+    }
+    const parts = command.includes('/') || command.includes('\\') ? [''] : [cwd, ...pathEnv.split(node_path_1.default.delimiter)];
+    let pathExt = env.PATHEXT ? env.PATHEXT.split(node_path_1.default.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 = node_path_1.default.resolve(cwd, unquoted, command);
+        for (const ext of [...pathExt, '']) {
+            const destWithExt = dest + ext;
+            try {
+                if (node_fs_1.default.statSync(destWithExt).isFile()) {
+                    CACHE[key] = destWithExt;
+                    return destWithExt;
+                }
+            }
+            catch {
+                // do nothing, it didn't exist
+            }
+        }
+    }
+    CACHE[key] = null;
+    return null;
+}

package/lib/cjs/utils/command/resolveCommand.d.cts

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

package/lib/cjs/utils/env/addNodeBinToPath.cjs

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addNodeBinToPath = addNodeBinToPath;
+const node_path_1 = __importDefault(require("node:path"));
+function addNodeBinToPath(cwd, { value, key }) {
+    const parts = value.split(node_path_1.default.delimiter);
+    const nodeBinPaths = [];
+    let currentPath = cwd;
+    let lastPath;
+    do {
+        nodeBinPaths.push(node_path_1.default.resolve(currentPath, 'node_modules', '.bin'));
+        lastPath = currentPath;
+        currentPath = node_path_1.default.dirname(currentPath);
+    } while (currentPath !== lastPath);
+    nodeBinPaths.push(node_path_1.default.dirname(process.execPath));
+    const newValue = nodeBinPaths.concat(parts).join(node_path_1.default.delimiter);
+    return {
+        key,
+        value: newValue,
+    };
+}

package/lib/cjs/utils/env/addNodeBinToPath.d.cts

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

package/lib/cjs/utils/env/computeEnv.cjs

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeEnv = computeEnv;
+const addNodeBinToPath_js_1 = require("./addNodeBinToPath.cjs");
+const getPathFromEnv_js_1 = require("./getPathFromEnv.cjs");
+function computeEnv(env, preferLocal, localDir) {
+    const computedEnv = {
+        ...process.env,
+        ...env,
+    };
+    if (!preferLocal) {
+        return computedEnv;
+    }
+    const pathEnvInfo = (0, addNodeBinToPath_js_1.addNodeBinToPath)(localDir, (0, getPathFromEnv_js_1.getPathFromEnv)(computedEnv));
+    computedEnv[pathEnvInfo.key] = pathEnvInfo.value;
+    return computedEnv;
+}

package/lib/cjs/utils/env/computeEnv.d.cts

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

package/lib/cjs/utils/env/getPathFromEnv.cjs

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPathFromEnv = getPathFromEnv;
+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/cjs/utils/env/getPathFromEnv.d.cts

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

package/lib/cjs/utils/env/types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/utils/env/types.d.cts

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

package/lib/cjs/utils/normalizeOptions.cjs

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOptions = normalizeOptions;
+const node_path_1 = __importDefault(require("node:path"));
+const computeEnv_js_1 = require("./env/computeEnv.cjs");
+const combineSignals_js_1 = require("./combineSignals.cjs");
+function normalizeOptions(options) {
+    const { cwd, env, preferLocal, resultMode: _resultMode, signal, stderr, stdin, stdio: stdioOption, stdout, ...restOptions } = options;
+    const spawnOptions = restOptions;
+    spawnOptions.cwd = node_path_1.default.resolve(cwd ?? process.cwd());
+    spawnOptions.env = (0, computeEnv_js_1.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 = (0, combineSignals_js_1.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/cjs/utils/normalizeOptions.d.cts

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

package/lib/cjs/utils/stream/combineStreams.cjs

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.combineStreams = combineStreams;
+const node_stream_1 = require("node:stream");
+const promises_1 = require("node:stream/promises");
+function combineStreams(streams) {
+    let streamCount = streams.length;
+    const combined = new node_stream_1.PassThrough();
+    if (streamCount === 0) {
+        combined.end();
+        return combined;
+    }
+    const maybeEmitEnd = () => {
+        streamCount -= 1;
+        if (streamCount === 0) {
+            combined.end();
+        }
+    };
+    for (const stream of streams) {
+        (0, promises_1.pipeline)(stream, combined, { end: false })
+            .then(maybeEmitEnd)
+            .catch(maybeEmitEnd);
+    }
+    return combined;
+}

package/lib/cjs/utils/stream/combineStreams.d.cts

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

package/lib/cjs/utils/stream/readStream.cjs

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readStream = readStream;
+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;
+}

package/lib/cjs/utils/stream/readStream.d.cts

@@ -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/create-command.d.mts

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

package/lib/esm/create-command.mjs

@@ -0,0 +1,17 @@
+import { exec } from './exec.mjs';
+function createCommand(command, args = [], options = {}) {
+    const create = (options) => {
+        const run = ((runArgs, runOptions) => {
+            return exec(command, [...(args ?? []), ...(runArgs ?? [])], {
+                ...options,
+                ...runOptions,
+            });
+        });
+        run.withOptions = (overrides) => create({ ...options, ...overrides });
+        run.toCwdFirst = () => ((cwd, ...runArgs) => run(runArgs, { cwd }));
+        run.toFlatArgs = () => ((...runArgs) => run(runArgs));
+        return run;
+    };
+    return create(options);
+}
+export { createCommand, };

package/lib/esm/exec-process.d.mts

@@ -0,0 +1,41 @@
+import type { ChildProcess } from 'node:child_process';
+import type { Readable } from 'node:stream';
+import type { ExecFailure, ExecResult, ExecSuccess, KillSignal, Options, ResultMode, Subprocess } from './types.mjs';
+declare class ExecProcess implements Subprocess<ResultMode> {
+    protected _aborted: boolean;
+    protected _args: readonly string[];
+    protected _command: string;
+    protected _cwd: string | undefined;
+    protected _failed: boolean;
+    protected _options: Partial<Options>;
+    protected _process?: ChildProcess;
+    protected _processClosed: Promise<void>;
+    protected _resolveClose?: () => void;
+    protected _signal?: AbortSignal;
+    protected _start?: bigint;
+    protected _streamErr?: Readable;
+    protected _streamOut?: Readable;
+    protected _thrownError?: Error;
+    constructor(command: string, args?: readonly string[] | null, options?: Partial<Options>);
+    get aborted(): boolean;
+    get error(): Error | undefined;
+    get exitCode(): number | undefined;
+    get failed(): boolean;
+    get killed(): boolean;
+    get pid(): number | undefined;
+    get process(): ChildProcess | undefined;
+    get signalCode(): string | undefined;
+    kill(signal?: KillSignal): boolean;
+    pipe<N extends ResultMode = 'result'>(command: string, args?: readonly string[], options?: Partial<Options> & {
+        resultMode?: N;
+    }): Subprocess<N>;
+    spawn(): void;
+    [Symbol.asyncIterator](): AsyncIterator<string>;
+    then<TResult1 = ExecResult<ResultMode>, TResult2 = never>(onfulfilled?: ((value: ExecResult<ResultMode>) => PromiseLike<TResult1> | TResult1) | null, onrejected?: ((reason: unknown) => PromiseLike<TResult2> | TResult2) | null): Promise<TResult1 | TResult2>;
+    protected onClose(): void;
+    protected onError(error: Error): void;
+    protected reset(): void;
+    protected toFailure(error: Error): ExecResult<ResultMode>;
+    protected toResult(): Promise<ExecResult<ResultMode>>;
+}
+export { type ExecFailure, type ExecResult, type ExecSuccess, type KillSignal, type Options, type ResultMode, type Subprocess, ExecProcess, };