@zokugun/exec-lite 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2026-present Baptiste Augrain
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,52 +1,276 @@
-⚠️ Important Notice ⚠️
-----------------------
+[@zokugun/exec-lite](https://github.com/zokugun/node-exec-lite)
+===============================================================
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![NPM Version](https://img.shields.io/npm/v/@zokugun/exec-lite?color=brightgreen)](https://www.npmjs.com/package/@zokugun/exec-lite)
+[![NodeJS Version](https://img.shields.io/badge/node.js-%3E%3D%2018.20-green)](#requirements)
+[![Modules](https://img.shields.io/badge/modules-ESM%20%7C%20CJS-green)](#requirements)
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-f87171?logo=kofi&logoColor=white)](https://ko-fi.com/daiyam)
+[![Liberapay](https://img.shields.io/badge/Liberapay-facc15?logo=liberapay&logoColor=black)](https://liberapay.com/daiyam/donate)
+[![PayPal](https://img.shields.io/badge/PayPal-5277C3?logo=paypal&logoColor=white)](https://paypal.me/daiyam99)
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+> Run external commands and manage their output easily. You get simple success or failure objects containing exit codes, execution time, and all captured text from standard output and error streams.
 
-Purpose
--------
+Features
+--------
+
+- **Process Management**: Spawn and manage external commands with a clean API.
+- **Result Types**: Get structured success and failure objects for every run.
+- **Unified Output**: Combines stdout and stderr into a single stream for easier logging.
+- **Windows Normalization**: Automatically handles `cmd.exe` and path escaping for Windows.
+- **Automated Resolution**: Locate binaries automatically using PATH and file extensions.
+- **Process Piping**: Chain multiple commands together to pass data between them.
+- **Abort Support**: Cancel running processes using standard abort signals.
+- **Exit Tracking**: Capture precise exit codes and signal codes from tasks.
+- **Execution Timing**: Measure the exact duration of a command in milliseconds.
+
+Installation
+------------
+
+```bash
+npm add @zokugun/exec-lite
+```
+
+Requirements
+------------
+
+- **Node.js**: `v18.20` or higher
+- **Modules**: ECMAScript Modules (`ESM`) or CommonJS (`CJS`)
+
+Quick Start
+-----------
+
+### 1. Basic Execution
+
+Run a command and wait for the final output. Use this when you only need the end result.
+
+```typescript
+import { exec } from '@zokugun/exec-lite';
+
+async function runSimpleCommand(): Promise<void> {
+   const result = await exec('echo', ['hello world']);
+
+   if(result.fails) {
+      console.error(`Failed with exit code: ${result.value.exitCode}`);
+
+      return;
+   }
+
+   const { stdout } = result.value;
+
+   console.log(`Output: ${stdout}`);
+}
+```
+
+### 2. Streaming Output
+
+Iterate over the process output in real-time.
+
+```typescript
+import { exec } from '@zokugun/exec-lite';
+
+async function runPipedCommands(): Promise<void> {
+   const task = exec('npm', ['install']);
+
+   for await(const line of task) {
+      console.log(`Log: ${line}`);
+   }
+
+   if(task.failed) {
+      console.error(`Failed with exit code: ${task.exitCode}`);
+   }
+}
+```
+
+### 3. Piping Processes
+
+Chain multiple commands together using the `.pipe()` method. The output of the first process is passed as the input to the second.
+
+```typescript
+import { exec } from '@zokugun/exec-lite';
+
+async function runPipedCommands(): Promise<void> {
+   const result = await exec('cat', ['package.json']).pipe('grep', ['dependencies']);
+
+   if(result.fails) {
+      console.log('Pipeline failed');
+
+      return;
+   }
+
+   console.log(`Filtered output: ${result.value.stdout}`);
+}
+
+await runPipedCommands();
+```
+
+API Reference
+-------------
+
+### Functions
 
-This package exists to:
+#### `exec`
 
-1. Configure OIDC trusted publishing for the package name `@zokugun/exec-lite`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+```typescript
+export function exec(
+   command: string,
+   args?: readonly string[] | null,
+   options?: Partial<Options>,
+): Subprocess;
+```
 
-What Is OIDC Trusted Publishing?
---------------------------------
+Spawns a child process and returns a `Subprocess` instance. The process starts immediately on return.
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+**Caveats:**
 
-Setup Instructions
-------------------
+- `exec` does not throw. Errors surface through the `fails` flag of the `Result`.
+- On Windows, batch files (`.bat`, `.cmd`) are wrapped in `cmd.exe` with verbatim argument handling.
 
-To properly configure OIDC trusted publishing for this package:
+---
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+### Classes
 
-Do not Use This Package
------------------------
+#### `ExecProcess`
 
-This package is a placeholder for OIDC configuration only. It:
+```typescript
+class ExecProcess implements Subprocess { ... }
+```
 
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+The class behind every subprocess returned by `exec`. You rarely need to construct it directly — use `exec()` instead.
 
-More Information
-----------------
+**Key properties:**
 
-For more details about npm's trusted publishing feature, see:
+| Property      | Type                        | Description                                            |
+| ------------- | --------------------------- | ------------------------------------------------------ |
+| `.aborted`    | `boolean`                   | True if the process was aborted via signal             |
+| `.error`      | `Error \| undefined`        | The error that caused failure, if any                  |
+| `.exitCode`   | `number \| undefined`       | Exit code after the process closes                     |
+| `.failed`     | `boolean`                   | True if exit code is non-zero or a signal was received |
+| `.killed`     | `boolean`                   | True if `kill()` was called                            |
+| `.pid`        | `number \| undefined`       | OS process ID                                          |
+| `.process`    | `ChildProcess \| undefined` | The raw Node.js child process handle                   |
+| `.signalCode` | `string \| undefined`       | Signal code that terminated the process                |
 
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+**Key methods:**
+
+| Method                            | Returns      | Description                                                       |
+| --------------------------------- | ------------ | ----------------------------------------------------------------- |
+| `.kill(signal?)`                  | `boolean`    | Sends a signal to the process. Returns false if no handle exists. |
+| `.pipe(command, args?, options?)` | `Subprocess` | Chains another command, piping this stdout into its stdin.        |
+| `.spawn()`                        | `void`       | Starts the process. Called automatically by `exec()`.             |
+
+---
+
+### Types
+
+#### `ExecResult`
+
+A discriminated union wrapping success or failure:
+
+```typescript
+type ExecResult = Result<ExecSuccess, ExecFailure>;
+```
+
+---
+
+#### `ExecSuccess`
+
+Returned when the process exits with code 0 and no error occurred.
+
+```typescript
+type ExecSuccess = {
+   all: string;        // combined stdout + stderr
+   command: string;
+   durationMs: number;
+   exitCode: number;
+   stdout: string;
+   stderr: string;
+};
+```
+
+---
+
+#### `ExecFailure`
+
+Returned when the process errors, exits non-zero, or gets killed.
+
+```typescript
+type ExecFailure = {
+   all?: string;
+   canceled: boolean;  // true if aborted via signal
+   command: string;
+   durationMs: number;
+   error?: Error;
+   exitCode?: number;
+   signalCode?: string;
+   stderr?: string;
+   stdout?: string;
+};
+```
+
+---
+
+#### `Subprocess`
+
+The shape returned by `exec()`. It is:
+
+- A **promise-like** — resolves to `ExecResult` when awaited.
+- An **async iterable** — yields lines from stdout + stderr.
+- A **live handle** — inspect `.exitCode`, `.pid`, etc. at any time after spawn.
+
+```typescript
+type Subprocess = AsyncIterable<string> & PromiseLike<ExecResult> & { ... };
+```
+
+---
+
+#### `Options`
+
+Extended `SpawnOptions` with extra fields:
+
+| Field               | Type                                  | Default              | Description                           |
+| ------------------- | ------------------------------------- | -------------------- | ------------------------------------- |
+| `cwd`               | `string`                              | `process.cwd()`      | Working directory                     |
+| `env`               | `Record<string, string>`              | inherited + computed | Environment variables                 |
+| `localDir`          | `string`                              | `cwd`                | Directory to resolve local paths from |
+| `preferLocal`       | `boolean`                             | `false`              | Prepends `node_modules/.bin` to PATH  |
+| `signal`            | `AbortSignal`                         | none                 | Abort signal for cancellation         |
+| `stdin`             | `string \| Subprocess \| { process }` | `pipe`               | Input source                          |
+| `stdio`             |                                       | none                 | Standard I/O configurations.          |
+| `stdout` / `stderr` | `StdioOption`                         | none                 | Stream configuration                  |
+| `timeout`           | `number`                              | none                 | Auto-abort after N milliseconds       |
+
+Contributions
+-------------
+
+Contributions are most welcome. Please:
+
+- Open issues and feature requests under the repository discussions.
+- Follow the [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+Donations
+---------
+
+Support this project by becoming a financial contributor.
+
+<table>
+   <tr>
+      <td><img src="https://raw.githubusercontent.com/daiyam/assets/master/icons/256/funding_kofi.png" alt="Ko-fi" width="80px" height="80px"></td>
+      <td><a href="https://ko-fi.com/daiyam" target="_blank">ko-fi.com/daiyam</a></td>
+   </tr>
+   <tr>
+      <td><img src="https://raw.githubusercontent.com/daiyam/assets/master/icons/256/funding_liberapay.png" alt="Liberapay" width="80px" height="80px"></td>
+      <td><a href="https://liberapay.com/daiyam/donate" target="_blank">liberapay.com/daiyam/donate</a></td>
+   </tr>
+   <tr>
+      <td><img src="https://raw.githubusercontent.com/daiyam/assets/master/icons/256/funding_paypal.png" alt="PayPal" width="80px" height="80px"></td>
+      <td><a href="https://paypal.me/daiyam99" target="_blank">paypal.me/daiyam99</a></td>
+   </tr>
+</table>
+
+License
+-------
 
---------------------
+Copyright &copy; 2026-present Baptiste Augrain
 
-**Maintained for OIDC setup purposes only**
+Licensed under the [MIT license](https://opensource.org/licenses/MIT).

package/lib/cjs/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/combineSignals.d.cts

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

package/lib/cjs/exec-process.cjs

@@ -0,0 +1,221 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecProcess = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_readline_1 = __importDefault(require("node:readline"));
+const xtry_1 = require("@zokugun/xtry");
+const exec_js_1 = require("./exec.cjs");
+const normalizeCommand_js_1 = require("./utils/command/normalizeCommand.cjs");
+const normalizeOptions_js_1 = require("./utils/normalizeOptions.cjs");
+const combineStreams_js_1 = require("./utils/stream/combineStreams.cjs");
+const readStream_js_1 = require("./utils/stream/readStream.cjs");
+class ExecProcess {
+    _aborted = false;
+    _args;
+    _command;
+    _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 (0, exec_js_1.exec)(command, args, {
+            ...options,
+            stdin: this,
+        });
+    } // }}}
+    spawn() {
+        this._start = process.hrtime.bigint();
+        this.reset();
+        const normalizedOptions = (0, normalizeOptions_js_1.normalizeOptions)(this._options);
+        if (normalizedOptions.signal) {
+            this._signal = normalizedOptions.signal;
+        }
+        const { command: spawnCommand, args: spawnArgs, options: spawnOptions } = (0, normalizeCommand_js_1.normalizeCommand)(this._command, this._args, normalizedOptions);
+        let task;
+        try {
+            task = (0, node_child_process_1.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 = (0, combineStreams_js_1.combineStreams)(streams);
+        const rl = node_readline_1.default.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(onfulfilled, 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;
+        const result = {
+            all: '',
+            canceled: this._signal?.aborted ?? false,
+            command: this._command,
+            durationMs: Number(process.hrtime.bigint() - this._start) / 1e6,
+            error,
+            exitCode: this.exitCode,
+            signalCode: this.signalCode,
+        };
+        return result;
+    } // }}}
+    async toResult() {
+        if (this._thrownError) {
+            return (0, xtry_1.err)(this.toFailure(this._thrownError));
+        }
+        const task = this._process;
+        if (!task) {
+            return (0, xtry_1.err)(this.toFailure(new Error('No process was started')));
+        }
+        const context = { all: '' };
+        const [stdout, stderr] = await Promise.all([
+            this._streamOut ? (0, readStream_js_1.readStream)(this._streamOut, context) : '',
+            this._streamErr ? (0, readStream_js_1.readStream)(this._streamErr, context) : '',
+        ]);
+        await this._processClosed;
+        const { stdin } = this._options;
+        if (stdin && typeof stdin !== 'string') {
+            await stdin;
+        }
+        task.removeAllListeners();
+        if (this._thrownError) {
+            return (0, xtry_1.err)(this.toFailure(this._thrownError));
+        }
+        const result = {
+            all: context.all,
+            command: this._command,
+            durationMs: Number(process.hrtime.bigint() - this._start) / 1e6,
+            exitCode: this.exitCode,
+            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 (0, xtry_1.err)(failure);
+        }
+        return (0, xtry_1.ok)(result);
+    } // }}}
+}
+exports.ExecProcess = ExecProcess;

package/lib/cjs/exec-process.d.cts

@@ -0,0 +1,37 @@
+import type { ChildProcess } from 'node:child_process';
+import type { Readable } from 'node:stream';
+import type { ExecFailure, ExecResult, KillSignal, Options, Subprocess } from './types.cjs';
+export declare class ExecProcess implements Subprocess {
+    protected _aborted: boolean;
+    protected _args: readonly string[];
+    protected _command: string;
+    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(command: string, args?: readonly string[], options?: Partial<Options>): Subprocess;
+    spawn(): void;
+    [Symbol.asyncIterator](): AsyncIterator<string>;
+    then<TResult1 = ExecResult, TResult2 = never>(onfulfilled?: ((value: ExecResult) => 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): ExecFailure;
+    protected toResult(): Promise<ExecResult>;
+}

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,2 @@
+import type { Options, Subprocess } from './types.cjs';
+export declare function exec(command: string, args?: readonly string[] | null, options?: Partial<Options>): Subprocess;

package/lib/cjs/index.cjs

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exec = exports.ExecProcess = void 0;
+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,3 @@
+export { ExecProcess } from './exec-process.cjs';
+export { exec } from './exec.cjs';
+export { ExecFailure, ExecResult, ExecSuccess, KillSignal, Options, StdinOption, StdioOption, Subprocess, } from './types.cjs';

package/lib/cjs/types.cjs

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