@zokugun/exec-lite 0.0.0-stage → 0.2.0

package/lib/esm/types.d.mts

@@ -0,0 +1,56 @@
+import type { ChildProcess, SpawnOptions as ProcessSpawnOptions } from 'node:child_process';
+import type { Result } from '@zokugun/xtry';
+export type ExecFailure = {
+    all?: string;
+    canceled: boolean;
+    command: string;
+    durationMs: number;
+    error?: Error;
+    exitCode?: number;
+    pipedFrom?: ExecResult;
+    signalCode?: string;
+    stderr?: string;
+    stdout?: string;
+};
+export type ExecResult = Result<ExecSuccess, ExecFailure>;
+export type ExecSuccess = {
+    all: string;
+    command: string;
+    durationMs: number;
+    error?: undefined;
+    exitCode: number;
+    pipedFrom?: ExecResult;
+    stderr: string;
+    stdout: string;
+};
+export type KillSignal = Parameters<ChildProcess['kill']>[0];
+export type Options = Omit<ProcessSpawnOptions, 'cwd' | 'env' | 'stdio'> & Readonly<Partial<{
+    cwd?: string;
+    env: Readonly<Partial<Record<string, string>>>;
+    localDir: string;
+    preferLocal: boolean;
+    signal: AbortSignal;
+    stderr: StdioOption;
+    stdin: ExecResult | StdinOption | Subprocess;
+    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 = AsyncIterable<string> & PromiseLike<ExecResult> & {
+    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: (command: string, args?: readonly string[], options?: Partial<Options>) => Subprocess;
+    get process(): ChildProcess | undefined;
+    get signalCode(): string | undefined;
+};

package/lib/esm/types.mjs

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

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, 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 = {
+    all: 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.all += String(chunk);
+        }
+    }
+    catch {
+        // suppress errors, child process probably failed to spawn
+    }
+    return output;
+}

package/package.json

@@ -1,6 +1,124 @@
 {
-  "name": "@zokugun/exec-lite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@zokugun/exec-lite",
+	"description": "A lightweight tool for running shell commands and reading their output easily.",
+	"version": "0.2.0",
+	"author": {
+		"name": "Baptiste Augrain",
+		"email": "daiyam@zokugun.org"
+	},
+	"license": "MIT",
+	"homepage": "https://github.com/zokugun/node-exec-lite",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/zokugun/node-exec-lite.git"
+	},
+	"bugs": {
+		"url": "https://github.com/zokugun/node-exec-lite/discussions/categories/issue-triage"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"import": "./lib/esm/index.mjs",
+			"require": "./lib/cjs/index.cjs"
+		}
+	},
+	"main": "lib/cjs/index.cjs",
+	"module": "lib/esm/index.mjs",
+	"typesVersions": {
+		"*": {
+			".": [
+				"./lib/cjs/index.d.cts"
+			]
+		}
+	},
+	"scripts": {
+		"audit:fix": "npm audit fix --min-release-age=0",
+		"build": "npm run clean && npm run build:out",
+		"build:out": "tsc-leda generate",
+		"build:package": "tsc-leda update-package && npm run lint:package",
+		"ci:lint": "zizmor .",
+		"ci:lint:fix": "zizmor . --fix=all",
+		"clean": "rimraf .src .test lib",
+		"compile:src": "tsc -p src",
+		"compile:test": "tsc -p test",
+		"lint": "eslint",
+		"lint:all": "npm run lint:package && npm audit && npm run ci:lint",
+		"lint:fix": "eslint --fix",
+		"lint:package": "fixpack || true",
+		"prepack": "npm run build",
+		"prepare": "husky; npm run lint:package",
+		"test": "vitest run --reporter tree",
+		"test:coverage": "vitest run --reporter tree --coverage --coverage.reporter text",
+		"test:ui": "vitest --ui --coverage",
+		"test:watch": "vitest",
+		"update:artifacts": "artifact update",
+		"update:ci": "pinact run -min-age 7 -update",
+		"update:deps": "taze --all",
+		"watch:build": "tsc-watch -p src --onSuccess 'npm run build'",
+		"watch:src": "tsc-watch -p src",
+		"watch:test": "tsc-watch -p test"
+	},
+	"dependencies": {
+		"@zokugun/xtry": "0.12.2"
+	},
+	"devDependencies": {
+		"@commitlint/cli": "20.5.3",
+		"@commitlint/config-conventional": "20.5.3",
+		"@types/node": "20.19.43",
+		"@vitest/coverage-v8": "4.1.12",
+		"@vitest/ui": "4.1.12",
+		"@zokugun/eslint-config": "0.2.1",
+		"@zokugun/eslint-config-data": "0.2.1",
+		"@zokugun/eslint-config-glossary": "0.2.0",
+		"@zokugun/eslint-config-js": "0.2.1",
+		"@zokugun/eslint-config-md": "0.4.1",
+		"@zokugun/eslint-config-nodejs": "0.2.0",
+		"@zokugun/eslint-config-style": "0.3.1",
+		"@zokugun/eslint-config-test": "0.2.0",
+		"@zokugun/eslint-config-ts": "0.3.2",
+		"@zokugun/fs-extra-plus": "0.7.0",
+		"@zokugun/tsc-leda": "0.9.4",
+		"eslint": "10.13.0",
+		"fixpack": "4.0.0",
+		"get-node": "15.0.4",
+		"husky": "9.1.7",
+		"lint-staged": "16.4.0",
+		"rimraf": "6.1.4",
+		"taze": "19.17.2",
+		"tsc-watch": "7.2.1",
+		"typescript": "5.9.3",
+		"vitest": "4.1.12",
+		"yaml": "2.9.1"
+	},
+	"overrides": {
+		"@eslint/config-array": {
+			"minimatch": "11.0.1"
+		},
+		"@typescript-eslint/typescript-estree": {
+			"minimatch": "11.0.1"
+		},
+		"eslint": {
+			"minimatch": "11.0.1"
+		},
+		"eslint-plugin-import-x": {
+			"minimatch": "11.0.1"
+		},
+		"micromark-extension-math": {
+			"katex": "0.18.2"
+		}
+	},
+	"allowScripts": {
+		"fsevents": true,
+		"unrs-resolver": true
+	},
+	"keywords": [
+		"child_process",
+		"command",
+		"exec",
+		"execute",
+		"process",
+		"shell",
+		"spawn",
+		"subprocess"
+	]
+}