visual-exec 0.1.14 → 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Joel Chen
+
+   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
+
+       http://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.

package/README.md

@@ -1,3 +1,99 @@
-# Visual Exec
+[![NPM version][npm-image]][npm-url] [![Build Status][build-image]][build-url]
 
-Execute shell command and show output with in place logging and spinner.
+# visual-exec
+
+Run a shell command and show it as a live spinner line instead of a wall of output.
+
+Output is captured while the command runs and the terminal shows a single updating line; on failure the captured output is logged so you can see what went wrong. The default logger detects CI and turns the in-place items off there, so build logs stay plain. Built on [visual-logger] and [xsh].
+
+## Install
+
+```bash
+npm install visual-exec
+```
+
+## Usage
+
+```js
+import VisualExec from "visual-exec";
+
+const ve = new VisualExec({
+  command: "npm install",
+  cwd: "/path/to/project",
+  displayTitle: "installing dependencies"
+});
+
+const { stdout, stderr } = await ve.execute();
+```
+
+## API
+
+### `new VisualExec(options)`
+
+**Command**
+
+| option | description |
+| --- | --- |
+| `command` | the command to run (required) |
+| `cwd` | working directory |
+| `maxBuffer` | max stdout/stderr buffer, default 10MB |
+
+**Display**
+
+| option | description |
+| --- | --- |
+| `displayTitle` | text shown on the spinner line while running |
+| `logLabel` / `outputLabel` | labels used in log and output messages |
+| `outputLevel` | log level for captured output, default `verbose` |
+| `visualLogger` | a [visual-logger] instance to log through |
+| `spinner` | spinner style |
+
+**Failure handling**
+
+| option | description |
+| --- | --- |
+| `forceStderr` | log stderr as error, default true |
+| `checkStdoutError` | boolean or regex - treat matching stdout as an error, default true |
+
+**Cancellation**
+
+| option | description |
+| --- | --- |
+| `timeout` | milliseconds before the process is killed |
+| `timeoutGrace` | ms between SIGTERM and SIGKILL, default 5000 |
+| `onTimeout` | called just before killing |
+| `signal` | an `AbortSignal` to cancel with |
+
+**Consuming output**
+
+| option | description |
+| --- | --- |
+| `onOutput(data, stream)` | called on each stdout/stderr chunk |
+| `onComplete(output, exitCode)` | called when finished; its return value becomes `execute()`'s result on success |
+| `outputFile` / `outputFileOptions` | stream output to a file (`append`, `includeStderr`, `timestamps`) |
+| `progress` / `onProgress` | extract progress from output by regex or custom function |
+| `matchers` | `[{ pattern, onMatch }]` run against output lines |
+
+### Methods
+
+- **`execute(command?)`** - run it; resolves to `{ stdout, stderr }`, or to `onComplete`'s return value when one is given
+- **`abort()`** / **`kill(signal?)`** - stop a running command
+
+### Errors
+
+A failure throws a `VisualExecError` carrying `exitCode`, `signal`, `cwd`, `command`, `duration`, `lastLines`, `stdout` and `stderr`.
+
+### Also exported
+
+`getDefaultLogger()`, and the output parsers `parsers`, `jsonLinesParser`, `keyValueParser`.
+
+## License
+
+Licensed under the [Apache License, Version 2.0](./LICENSE).
+
+[visual-logger]: https://github.com/jchip/fynjs/tree/main/packages/visual-logger
+[xsh]: https://github.com/jchip/fynjs/tree/main/packages/xsh
+[npm-image]: https://badge.fury.io/js/visual-exec.svg
+[npm-url]: https://npmjs.org/package/visual-exec
+[build-image]: https://github.com/jchip/fynjs/actions/workflows/ci.yml/badge.svg
+[build-url]: https://github.com/jchip/fynjs/actions/workflows/ci.yml

package/dist/get-default-logger.d.ts

@@ -0,0 +1,3 @@
+import VisualLogger from "visual-logger";
+export declare function getDefaultLogger(): VisualLogger;
+export default getDefaultLogger;

package/dist/get-default-logger.js

@@ -0,0 +1,14 @@
+import VisualLogger from "visual-logger";
+import { isCI } from "ci-info";
+let logger = null;
+export function getDefaultLogger() {
+    if (!logger) {
+        logger = new VisualLogger();
+        if (isCI) {
+            logger.info("visual-exec: CI env detected");
+            logger.setItemType("none");
+        }
+    }
+    return logger;
+}
+export default getDefaultLogger;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { VisualExec, VisualExecOptions, ExecOutput, ExecErrorContext, VisualExecError, parsers, jsonLinesParser, keyValueParser } from "./visual-exec.js";
+export type { OnOutputCallback, OnCompleteCallback, OutputFileOptions, ProgressExtractor, OutputMatcher } from "./visual-exec.js";
+export { getDefaultLogger } from "./get-default-logger.js";
+export { VisualExec as default } from "./visual-exec.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { VisualExec, parsers, jsonLinesParser, keyValueParser } from "./visual-exec.js";
+export { getDefaultLogger } from "./get-default-logger.js";
+export { VisualExec as default } from "./visual-exec.js";

package/dist/visual-exec.d.ts

@@ -0,0 +1,184 @@
+import VisualLogger from "visual-logger";
+export type OutputStream = "stdout" | "stderr";
+/** Called on each chunk of stdout/stderr during execution */
+export type OnOutputCallback = (data: string, stream: OutputStream) => void;
+/** Called after command completes. Can return structured result passed through to execute() */
+export type OnCompleteCallback = (output: ExecOutput, exitCode: number) => unknown;
+export interface OutputFileOptions {
+    /** Append to existing file (default: false) */
+    append?: boolean;
+    /** Include stderr in output (default: true) */
+    includeStderr?: boolean;
+    /** Add timestamps per line (default: false) */
+    timestamps?: boolean;
+}
+export interface ProgressExtractor {
+    /** Regex with named groups: (?<current>\d+)/(?<total>\d+) or (?<percent>\d+)% */
+    pattern?: RegExp;
+    /** Custom extractor function */
+    extract?: (line: string) => {
+        current?: number;
+        total?: number;
+        percent?: number;
+    } | null;
+    /** Display format for progress */
+    format?: (p: {
+        current?: number;
+        total?: number;
+        percent?: number;
+    }) => string;
+}
+export interface OutputMatcher {
+    pattern: RegExp;
+    onMatch: (match: RegExpMatchArray) => void;
+}
+export interface VisualExecOptions {
+    /** The command to execute */
+    command: string;
+    /** Working directory for the command */
+    cwd?: string;
+    /** Visual logger instance to use */
+    visualLogger?: VisualLogger;
+    /** Spinner style to use */
+    spinner?: any;
+    /** Title displayed during execution */
+    displayTitle?: string;
+    /** Label used in log messages */
+    logLabel?: string;
+    /** Label used in output messages */
+    outputLabel?: string;
+    /** Log level for output (default: "verbose") */
+    outputLevel?: string;
+    /** Maximum buffer size for stdout/stderr (default: 10MB) */
+    maxBuffer?: number;
+    /** Force stderr output to be logged as error (default: true) */
+    forceStderr?: boolean;
+    /** Regex or boolean to check stdout for error patterns (default: true) */
+    checkStdoutError?: boolean | RegExp;
+    /** Timeout in milliseconds. Process killed if exceeded. */
+    timeout?: number;
+    /** Grace period in ms before SIGKILL after SIGTERM (default: 5000) */
+    timeoutGrace?: number;
+    /** Callback before killing on timeout */
+    onTimeout?: () => void;
+    /** Called on each chunk of stdout/stderr during execution */
+    onOutput?: OnOutputCallback;
+    /** Called after command completes. Return value passed through to execute() when exitCode is 0 */
+    onComplete?: OnCompleteCallback;
+    /** Stream output to file (path or stream) */
+    outputFile?: string | NodeJS.WritableStream;
+    /** Options for outputFile when path string */
+    outputFileOptions?: OutputFileOptions;
+    /** AbortSignal for cancellation (e.g. from AbortController) */
+    signal?: AbortSignal;
+    /** Progress extraction config */
+    progress?: ProgressExtractor;
+    /** Called when progress is extracted */
+    onProgress?: (progress: {
+        current?: number;
+        total?: number;
+        percent?: number;
+    }) => void;
+    /** Regex matchers for output lines */
+    matchers?: OutputMatcher[];
+}
+export interface ExecOutput {
+    stdout: string;
+    stderr: string;
+}
+export interface ExecErrorContext {
+    exitCode: number;
+    signal: string | null;
+    cwd: string;
+    command: string;
+    duration: number;
+    lastLines: string[];
+    stdout: string;
+    stderr: string;
+}
+export interface VisualExecError extends Error {
+    output?: ExecOutput;
+    code?: number;
+    exitCode?: number;
+    signal?: string | null;
+    cwd?: string;
+    command?: string;
+    duration?: number;
+    lastLines?: string[];
+    stdout?: string;
+    stderr?: string;
+    context?: ExecErrorContext;
+}
+interface ChildProcess {
+    stdout: NodeJS.ReadableStream;
+    stderr: NodeJS.ReadableStream;
+    promise: Promise<ExecOutput>;
+    child?: {
+        kill(signal?: string): boolean;
+        pid?: number;
+    };
+}
+/** JSON Lines parser - parses each line as JSON */
+export declare function jsonLinesParser(line: string): unknown | null;
+/** Key-value parser for key=value or key: value patterns */
+export declare function keyValueParser(line: string): Record<string, string> | null;
+export declare const parsers: {
+    jsonLines: typeof jsonLinesParser;
+    keyValue: typeof keyValueParser;
+};
+export declare class VisualExec {
+    private _title;
+    private _logLabel;
+    private _outputLabel;
+    private _command;
+    private _cwd;
+    private _logger;
+    private _outputLevel;
+    private _spinner;
+    private _maxBuffer;
+    private _forceStderr;
+    private _checkStdoutError;
+    private _startTime;
+    private _timeout?;
+    private _timeoutGrace;
+    private _onTimeout?;
+    private _onOutput?;
+    private _onComplete?;
+    private _outputFile?;
+    private _outputFileOptions;
+    private _signal?;
+    private _progress?;
+    private _onProgress?;
+    private _matchers?;
+    private _stdoutKey?;
+    private _stderrKey?;
+    private _updateStdout?;
+    private _updateStderr?;
+    private _child?;
+    private _rawChild?;
+    private _outputStream?;
+    private _aborted;
+    private _onStdoutData?;
+    private _onStderrData?;
+    constructor(options: VisualExecOptions);
+    private _makeTitle;
+    private _createOutputFileStream;
+    private _writeToOutputFile;
+    private _extractProgress;
+    private _updateDigest;
+    private _createDataHandler;
+    /** Abort/kill the running command */
+    abort(signal?: string): void;
+    /** Alias for abort() */
+    kill(signal?: string): void;
+    show(child: ChildProcess): Promise<ExecOutput | unknown>;
+    logResult(err: VisualExecError | null, output?: ExecOutput): void;
+    checkForErrors(text: string): RegExpMatchArray | null;
+    /**
+     * Log the final output. Can be overridden to customize output handling.
+     * Set to a no-op function to suppress output logging.
+     */
+    logFinalOutput(err: VisualExecError | null, output: ExecOutput): void;
+    execute(command?: string): Promise<ExecOutput | unknown>;
+}
+export default VisualExec;

package/dist/visual-exec.js

@@ -0,0 +1,456 @@
+import xsh from "xsh";
+import chalk from "chalk";
+import * as fs from "fs";
+import * as path from "path";
+import { getDefaultLogger } from "./get-default-logger.js";
+import VisualLogger from "visual-logger";
+import hasAnsi from "has-ansi";
+import stripAnsi from "strip-ansi";
+// Set xsh to use native Promise
+xsh.Promise = Promise;
+const ONE_MB = 1024 * 1024;
+const TEN_MB = 10 * ONE_MB;
+const DEFAULT_TIMEOUT_GRACE = 5000;
+const DEFAULT_LAST_LINES = 10;
+const MAX_OUTPUT_IN_ERROR = 50000;
+function createTimeoutError(context, elapsed) {
+    const err = new Error(`Command timed out after ${elapsed}ms: ${context.command}`);
+    err.name = "TimeoutError";
+    err.context = { ...context, duration: elapsed };
+    return err;
+}
+function createAbortError(context) {
+    const err = new Error(`Command aborted: ${context.command}`);
+    err.name = "AbortError";
+    err.context = context;
+    return err;
+}
+function lastLines(text, n) {
+    if (!text)
+        return [];
+    const lines = text.split("\n").filter(Boolean);
+    return lines.slice(-n);
+}
+function enhanceError(err, context) {
+    err.exitCode = context.exitCode;
+    err.signal = context.signal;
+    err.cwd = context.cwd;
+    err.command = context.command;
+    err.duration = context.duration;
+    err.lastLines = context.lastLines;
+    err.context = context;
+    err.stdout = context.stdout.length > MAX_OUTPUT_IN_ERROR
+        ? context.stdout.slice(-MAX_OUTPUT_IN_ERROR)
+        : context.stdout;
+    err.stderr = context.stderr.length > MAX_OUTPUT_IN_ERROR
+        ? context.stderr.slice(-MAX_OUTPUT_IN_ERROR)
+        : context.stderr;
+    return err;
+}
+/** JSON Lines parser - parses each line as JSON */
+export function jsonLinesParser(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("//"))
+        return null;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/** Key-value parser for key=value or key: value patterns */
+export function keyValueParser(line) {
+    const match = line.match(/^([^=:]+)[=:]\s*(.*)$/);
+    if (!match)
+        return null;
+    return { [match[1].trim()]: match[2].trim() };
+}
+export const parsers = {
+    jsonLines: jsonLinesParser,
+    keyValue: keyValueParser
+};
+export class VisualExec {
+    constructor(options) {
+        this._aborted = false;
+        const { command, cwd = process.cwd(), visualLogger, spinner = VisualLogger.spinners[1], displayTitle, logLabel, outputLabel, outputLevel = "verbose", maxBuffer = TEN_MB, forceStderr = true, checkStdoutError = true, timeout, timeoutGrace = DEFAULT_TIMEOUT_GRACE, onTimeout, onOutput, onComplete, outputFile, outputFileOptions = {}, signal, progress, onProgress, matchers } = options;
+        this._title = displayTitle || this._makeTitle(command);
+        this._logLabel = logLabel || this._title;
+        this._outputLabel = outputLabel || this._title;
+        this._command = command;
+        this._cwd = cwd || process.cwd();
+        this._logger = visualLogger || getDefaultLogger();
+        this._outputLevel = outputLevel;
+        this._spinner = spinner;
+        this._maxBuffer = maxBuffer;
+        this._forceStderr = forceStderr;
+        this._checkStdoutError =
+            checkStdoutError === true
+                ? /error|warn|fatal|unhandled|reject|exception|failure|fail|failed/i
+                : checkStdoutError;
+        this._startTime = Date.now();
+        this._timeout = timeout;
+        this._timeoutGrace = timeoutGrace;
+        this._onTimeout = onTimeout;
+        this._onOutput = onOutput;
+        this._onComplete = onComplete;
+        this._outputFile = outputFile;
+        this._outputFileOptions = {
+            append: false,
+            includeStderr: true,
+            timestamps: false,
+            ...outputFileOptions
+        };
+        this._signal = signal;
+        this._progress = progress;
+        this._onProgress = onProgress;
+        this._matchers = matchers;
+    }
+    _makeTitle(command) {
+        if (typeof command !== "string") {
+            command = "user command";
+        }
+        return `Running ${command}`;
+    }
+    _createOutputFileStream() {
+        if (typeof this._outputFile !== "string")
+            return undefined;
+        const flags = this._outputFileOptions.append ? "a" : "w";
+        const dir = path.dirname(this._outputFile);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        return fs.createWriteStream(this._outputFile, { flags });
+    }
+    _writeToOutputFile(data, stream) {
+        var _a;
+        const streamOpt = this._outputFileOptions.includeStderr;
+        if (stream === "stderr" && !streamOpt)
+            return;
+        const line = this._outputFileOptions.timestamps
+            ? `[${new Date().toISOString()}] ${data}`
+            : data;
+        const out = (_a = this._outputStream) !== null && _a !== void 0 ? _a : (typeof this._outputFile === "object" ? this._outputFile : null);
+        if (out && typeof out.write === "function") {
+            out.write(line);
+        }
+    }
+    _extractProgress(line) {
+        const cfg = this._progress;
+        if (!cfg || !this._onProgress)
+            return;
+        let progress = null;
+        if (cfg.extract) {
+            progress = cfg.extract(line);
+        }
+        else if (cfg.pattern) {
+            const m = line.match(cfg.pattern);
+            if (m && m.groups) {
+                progress = {
+                    current: m.groups.current ? parseInt(m.groups.current, 10) : undefined,
+                    total: m.groups.total ? parseInt(m.groups.total, 10) : undefined,
+                    percent: m.groups.percent ? parseInt(m.groups.percent, 10) : undefined
+                };
+            }
+        }
+        if (progress)
+            this._onProgress(progress);
+    }
+    _updateDigest(item, buf) {
+        const newBuf = item.buf + buf;
+        const lines = newBuf
+            .split("\n")
+            .map(x => x && x.trim())
+            .filter(x => x);
+        const stripLines = lines.map(x => (hasAnsi(x) ? stripAnsi(x) : x));
+        let length = 0;
+        let ix = stripLines.length - 1;
+        for (; ix >= 0; ix--) {
+            const line = stripLines[ix];
+            if (line) {
+                if (length + line.length < 100) {
+                    length += line.length;
+                }
+                else {
+                    break;
+                }
+            }
+        }
+        let msgs = ix >= 0 ? lines.slice(ix + 1) : lines;
+        if (msgs.length === 0) {
+            item.buf = lines[lines.length - 1] || "";
+            if (item.buf.length > 120) {
+                item.buf = stripLines[stripLines.length - 1].substr(0, 100);
+            }
+            msgs = [item.buf];
+        }
+        else {
+            item.buf = msgs.join("\n");
+        }
+        if (buf.endsWith("\n")) {
+            item.buf += "\n";
+        }
+        this._logger.updateItem(item.name, {
+            msg: msgs.join(chalk.blue.inverse("\\n")),
+            _save: false,
+            _render: false
+        });
+    }
+    _createDataHandler(stream) {
+        return (buf) => {
+            var _a;
+            const data = typeof buf === "string" ? buf : buf.toString();
+            if (this._onOutput)
+                this._onOutput(data, stream);
+            if (this._outputFile || this._outputStream)
+                this._writeToOutputFile(data, stream);
+            for (const line of data.split("\n")) {
+                if (line) {
+                    this._extractProgress(line);
+                    for (const m of (_a = this._matchers) !== null && _a !== void 0 ? _a : []) {
+                        const match = line.match(m.pattern);
+                        if (match)
+                            m.onMatch(match);
+                    }
+                }
+            }
+        };
+    }
+    /** Abort/kill the running command */
+    abort(signal = "SIGTERM") {
+        var _a;
+        this._aborted = true;
+        if ((_a = this._rawChild) === null || _a === void 0 ? void 0 : _a.pid) {
+            this._rawChild.kill(signal);
+        }
+    }
+    /** Alias for abort() */
+    kill(signal) {
+        this.abort(signal);
+    }
+    show(child) {
+        this._stdoutKey = Symbol("visual-exec-stdout");
+        this._stderrKey = Symbol("visual-exec-stderr");
+        this._rawChild = child.child;
+        this._logger.addItem({
+            name: this._stdoutKey,
+            color: "green",
+            display: `=== ${this._title}\nstdout`,
+            spinner: this._spinner
+        });
+        this._logger.addItem({
+            name: this._stderrKey,
+            color: "red",
+            display: `stderr`
+        });
+        const stdoutDigest = { name: this._stdoutKey, buf: "" };
+        const stderrDigest = { name: this._stderrKey, buf: "" };
+        this._updateStdout = (buf) => this._updateDigest(stdoutDigest, buf);
+        this._updateStderr = (buf) => this._updateDigest(stderrDigest, buf);
+        this._onStdoutData = (buf) => {
+            const data = typeof buf === "string" ? buf : buf.toString();
+            this._updateStdout(data);
+            this._createDataHandler("stdout")(buf);
+        };
+        this._onStderrData = (buf) => {
+            const data = typeof buf === "string" ? buf : buf.toString();
+            this._updateStderr(data);
+            this._createDataHandler("stderr")(buf);
+        };
+        child.stdout.on("data", this._onStdoutData);
+        child.stderr.on("data", this._onStderrData);
+        this._child = child;
+        if (typeof this._outputFile === "string") {
+            this._outputStream = this._createOutputFileStream();
+        }
+        else if (this._outputFile) {
+            this._outputStream = undefined;
+        }
+        let timeoutId;
+        const startTime = Date.now();
+        let execPromise = child.promise
+            .catch((err) => {
+            var _a, _b, _c, _d;
+            const output = (_a = err.output) !== null && _a !== void 0 ? _a : { stdout: "", stderr: "" };
+            const exitCode = (_c = (_b = err.exitCode) !== null && _b !== void 0 ? _b : err.code) !== null && _c !== void 0 ? _c : 1;
+            (_d = this._onComplete) === null || _d === void 0 ? void 0 : _d.call(this, output, exitCode);
+            this.logResult(err);
+            throw err;
+        })
+            .then((output) => {
+            var _a;
+            this.logResult(null, output);
+            const result = (_a = this._onComplete) === null || _a === void 0 ? void 0 : _a.call(this, output, 0);
+            return result !== undefined ? result : output;
+        });
+        if (this._timeout) {
+            const timeoutPromise = new Promise((_, reject) => {
+                timeoutId = setTimeout(() => {
+                    var _a, _b, _c, _d;
+                    if (this._aborted)
+                        return;
+                    (_a = this._onTimeout) === null || _a === void 0 ? void 0 : _a.call(this);
+                    if ((_b = this._rawChild) === null || _b === void 0 ? void 0 : _b.pid) {
+                        this._rawChild.kill("SIGTERM");
+                        const grace = setTimeout(() => {
+                            var _a;
+                            if ((_a = this._rawChild) === null || _a === void 0 ? void 0 : _a.pid)
+                                this._rawChild.kill("SIGKILL");
+                        }, this._timeoutGrace);
+                        (_d = (_c = grace).unref) === null || _d === void 0 ? void 0 : _d.call(_c);
+                    }
+                    reject(createTimeoutError({ command: this._command, cwd: this._cwd, exitCode: -1, signal: "SIGTERM" }, this._timeout));
+                }, this._timeout);
+            });
+            execPromise = Promise.race([execPromise, timeoutPromise]);
+        }
+        const cleanup = () => {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            const stream = this._outputStream;
+            this._outputStream = undefined;
+            // Only streams we opened are ours to close - a caller-supplied one stays open.
+            if (!(stream === null || stream === void 0 ? void 0 : stream.end)) {
+                return undefined;
+            }
+            // Already gone - a stream that errored destroys itself, and `close` will not fire a
+            // second time, so waiting on it here would hang execute() forever.
+            if (stream.destroyed || stream.closed) {
+                return undefined;
+            }
+            //
+            // `end()` starts the flush, it does not finish it, and `createWriteStream` opens the
+            // file asynchronously too. Resolving execute() without waiting meant a caller that
+            // awaited it could read a file that was still empty, or not yet created at all - the
+            // outputFile test failed with ENOENT under CI load while passing on a quiet machine.
+            //
+            return new Promise((resolve) => {
+                stream.once("close", () => resolve());
+                // a stream that errors still has to let execute() settle
+                stream.once("error", () => resolve());
+                stream.end();
+            });
+        };
+        if (this._signal) {
+            const abortPromise = new Promise((_, reject) => {
+                const handleAbort = () => {
+                    this.abort();
+                    reject(createAbortError({
+                        command: this._command,
+                        cwd: this._cwd,
+                        exitCode: -1,
+                        signal: "SIGTERM",
+                        duration: Date.now() - startTime
+                    }));
+                };
+                if (this._signal.aborted) {
+                    handleAbort();
+                }
+                else {
+                    this._signal.addEventListener("abort", handleAbort);
+                }
+            });
+            execPromise = Promise.race([execPromise, abortPromise]);
+        }
+        return execPromise.finally(cleanup);
+    }
+    logResult(err, output) {
+        const child = this._child;
+        this._logger.removeItem(this._stdoutKey);
+        this._logger.removeItem(this._stderrKey);
+        if (this._onStdoutData)
+            child.stdout.removeListener("data", this._onStdoutData);
+        if (this._onStderrData)
+            child.stderr.removeListener("data", this._onStderrData);
+        if (err) {
+            this._logger.error(`${chalk.red("Failed")} ${this._logLabel} - ${chalk.red(err.message)}`);
+            output = err.output;
+        }
+        else {
+            const time = ((Date.now() - this._startTime) / 1000).toFixed(2);
+            const dispTime = `${chalk.magenta(time)}secs`;
+            this._logger.info(`Done ${this._logLabel} ${dispTime} ${chalk.green("exit code 0")}`);
+        }
+        this.logFinalOutput(err, output);
+    }
+    checkForErrors(text) {
+        if (!this._checkStdoutError || !text)
+            return null;
+        if (this._checkStdoutError instanceof RegExp) {
+            return text.match(this._checkStdoutError);
+        }
+        return null;
+    }
+    /**
+     * Log the final output. Can be overridden to customize output handling.
+     * Set to a no-op function to suppress output logging.
+     */
+    logFinalOutput(err, output) {
+        const level = err || (this._forceStderr && (output === null || output === void 0 ? void 0 : output.stderr)) || this.checkForErrors((output === null || output === void 0 ? void 0 : output.stdout) || "")
+            ? "error"
+            : this._outputLevel;
+        if (!output || (!output.stdout && !output.stderr)) {
+            this._logger[level](`${chalk.green("No output")} from ${this._outputLabel}`);
+            return;
+        }
+        const colorize = (t) => t.replace(/ERR!/g, chalk.red("ERR!"));
+        const logs = [chalk.green(">>>"), `Start of output from ${this._outputLabel} ===`];
+        if (output.stdout) {
+            logs.push(`\n${colorize(output.stdout)}`);
+        }
+        if (output.stderr) {
+            logs.push(chalk.red("\n=== stderr ===\n") + colorize(output.stderr));
+        }
+        logs.push(chalk.blue("\n<<<"), `End of output from ${this._outputLabel} ---`);
+        this._logger.prefix(false)[level](...logs);
+    }
+    execute(command) {
+        this._startTime = Date.now();
+        this._aborted = false;
+        const cmd = command || this._command;
+        const result = xsh.exec({
+            silent: true,
+            cwd: this._cwd,
+            env: Object.assign({}, process.env, { PWD: this._cwd }),
+            maxBuffer: this._maxBuffer
+        }, cmd);
+        const child = {
+            stdout: result.stdout,
+            stderr: result.stderr,
+            promise: result.promise,
+            child: result.child
+        };
+        const duration = () => Date.now() - this._startTime;
+        const baseContext = (output) => {
+            var _a, _b, _c, _d;
+            return ({
+                command: cmd,
+                cwd: this._cwd,
+                duration: duration(),
+                stdout: (_a = output === null || output === void 0 ? void 0 : output.stdout) !== null && _a !== void 0 ? _a : "",
+                stderr: (_b = output === null || output === void 0 ? void 0 : output.stderr) !== null && _b !== void 0 ? _b : "",
+                lastLines: lastLines([...((_c = output === null || output === void 0 ? void 0 : output.stdout) !== null && _c !== void 0 ? _c : "").split("\n"), ...((_d = output === null || output === void 0 ? void 0 : output.stderr) !== null && _d !== void 0 ? _d : "").split("\n")].join("\n"), DEFAULT_LAST_LINES)
+            });
+        };
+        child.promise = child.promise.catch((err) => {
+            var _a, _b, _c, _d, _e;
+            const output = (_a = err.output) !== null && _a !== void 0 ? _a : { stdout: "", stderr: "" };
+            const exitCode = (_b = err.code) !== null && _b !== void 0 ? _b : 1;
+            const signal = (_e = (_c = err.signal) !== null && _c !== void 0 ? _c : (((_d = result.child) === null || _d === void 0 ? void 0 : _d.killed) ? "SIGTERM" : null)) !== null && _e !== void 0 ? _e : null;
+            const context = {
+                ...baseContext(output),
+                exitCode,
+                signal,
+                cwd: this._cwd,
+                command: cmd,
+                duration: duration(),
+                lastLines: lastLines([...output.stdout.split("\n"), ...output.stderr.split("\n")].join("\n"), DEFAULT_LAST_LINES),
+                stdout: output.stdout,
+                stderr: output.stderr
+            };
+            return Promise.reject(enhanceError(err, context));
+        });
+        return this.show(child);
+    }
+}
+export default VisualExec;

package/package.json

@@ -1,34 +1,56 @@
 {
   "name": "visual-exec",
-  "version": "0.1.14",
-  "description": "Visual shell exec",
-  "main": "lib/visual-exec.js",
-  "scripts": {},
+  "version": "1.0.0",
+  "homepage": "https://github.com/jchip/fynjs/tree/main/packages/visual-exec",
+  "description": "Visual shell exec with spinners and progress display",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "ci:check": "tsc --noEmit -p tsconfig.json && npm test",
+    "test:watch": "vitest",
+    "prepublishOnly": "xrun --serial build test",
+    "postpack": "publish-util-postpack"
+  },
+  "bugs": {
+    "url": "https://github.com/jchip/fynjs/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/jchip/visual-exec.git"
+    "url": "git+https://github.com/jchip/fynjs.git",
+    "directory": "packages/visual-exec"
   },
   "keywords": [
     "visual",
     "shell",
-    "exec"
+    "exec",
+    "spinner",
+    "progress"
   ],
   "files": [
-    "lib"
+    "dist"
   ],
   "author": "Joel Chen <joel123@gmail.com>",
   "license": "Apache-2.0",
   "dependencies": {
-    "chalk": "^4.1.2",
-    "ci-info": "^3.2.0",
-    "has-ansi": "^4.0.1",
-    "strip-ansi": "^6.0.0",
-    "visual-logger": "^1.1.3",
-    "xsh": "^0.4.5"
+    "chalk": "^6.0.0",
+    "ci-info": "^4.4.0",
+    "has-ansi": "^6.0.2",
+    "strip-ansi": "^7.2.0",
+    "visual-logger": "^2.0.0",
+    "xsh": "^1.0.0"
   },
-  "prettier": {
-    "printWidth": 100,
-    "trailingComma": "none",
-    "arrowParens": "avoid"
-  }
+  "sideEffects": false
 }

package/lib/get-default-logger.js

@@ -1,19 +0,0 @@
-"use strict";
-
-const VisualLogger = require("visual-logger");
-const { isCI } = require("ci-info");
-
-let logger;
-const getLogger = () => {
-  if (!logger) {
-    logger = new VisualLogger();
-
-    if (isCI) {
-      logger.info("visual-exec: CI env detected");
-      logger.setItemType("none");
-    }
-  }
-  return logger;
-};
-
-module.exports = getLogger;

package/lib/visual-exec.js

@@ -1,213 +0,0 @@
-"use strict";
-
-/* eslint-disable no-magic-numbers,no-eval,prefer-template */
-
-const xsh = require("xsh");
-const chalk = require("chalk");
-const getDefaultLogger = require("./get-default-logger");
-const VisualLogger = require("visual-logger");
-const hasAnsi = require("has-ansi");
-const stripAnsi = require("strip-ansi");
-
-xsh.Promise = Promise;
-
-const ONE_MB = 1024 * 1024;
-const TEN_MB = 10 * ONE_MB;
-
-class VisualExec {
-  constructor({
-    command,
-    cwd = process.cwd(),
-    visualLogger,
-    spinner = VisualLogger.spinners[1],
-    displayTitle = undefined,
-    logLabel = undefined,
-    outputLabel = undefined,
-    outputLevel = "verbose",
-    maxBuffer = TEN_MB,
-    forceStderr = true,
-    checkStdoutError = true
-  }) {
-    this._title = displayTitle || this._makeTitle(command);
-    this._logLabel = logLabel || this._title;
-    this._outputLabel = outputLabel || this._title;
-    this._command = command;
-    this._cwd = cwd || process.cwd();
-    this._logger = visualLogger || getDefaultLogger();
-    this._outputLevel = outputLevel;
-    this._spinner = spinner;
-    this._maxBuffer = maxBuffer;
-    this._forceStderr = forceStderr;
-    this._checkStdoutError =
-      checkStdoutError === true
-        ? /error|warn|fatal|unhandled|reject|exception|failure|fail|failed/i
-        : checkStdoutError;
-    this._startTime = Date.now();
-  }
-
-  _makeTitle(command) {
-    if (typeof command !== "string") {
-      command = "user command";
-    }
-
-    return `Running ${command}`;
-  }
-
-  /* eslint-disable max-statements */
-  _updateDigest(item, buf) {
-    const newBuf = item.buf + buf;
-
-    const lines = newBuf
-      .split("\n")
-      .map(x => x && x.trim())
-      .filter(x => x);
-
-    const stripLines = lines.map(x => (hasAnsi(x) ? stripAnsi(x) : x));
-
-    let length = 0;
-
-    // gather as many lines from the end as possible that will fit in a single line, using
-    // strings without ansi code to get real length
-    let ix = stripLines.length - 1;
-    for (; ix >= 0; ix--) {
-      const line = stripLines[ix];
-      if (line) {
-        if (length + line.length < 100) {
-          length += line.length;
-        } else {
-          break;
-        }
-      }
-    }
-
-    let msgs = ix >= 0 ? lines.slice(ix + 1) : lines;
-    if (msgs.length === 0) {
-      // even the last line is too long, save it, and display last line as is
-      item.buf = lines[lines.length - 1] || "";
-      // set some reasonable limit to avoid visual digest getting clobberred
-      if (item.buf.length > 120) {
-        // truncte stripped line only to avoid breaking ansi code
-        item.buf = stripLines[stripLines.length - 1].substr(0, 100);
-      }
-      msgs = [item.buf];
-    } else {
-      item.buf = msgs.join("\n");
-    }
-
-    if (buf.endsWith("\n")) {
-      item.buf += "\n";
-    }
-
-    this._logger.updateItem(item.name, {
-      msg: msgs.join(chalk.blue.inverse("\\n")),
-      _save: false,
-      _render: false
-    });
-  }
-
-  show(child) {
-    this._stdoutKey = Symbol("visual-exec-stdout");
-    this._stderrKey = Symbol("visual-exec-stderr");
-
-    this._logger.addItem({
-      name: this._stdoutKey,
-      color: "green",
-      display: `=== ${this._title}\nstdout`,
-      spinner: this._spinner
-    });
-
-    this._logger.addItem({
-      name: this._stderrKey,
-      color: "red",
-      display: `stderr`
-    });
-
-    const stdoutDigest = { name: this._stdoutKey, buf: "" };
-    const stderrDigest = { name: this._stderrKey, buf: "" };
-    this._updateStdout = buf => this._updateDigest(stdoutDigest, buf);
-    this._updateStderr = buf => this._updateDigest(stderrDigest, buf);
-
-    child.stdout.on("data", this._updateStdout);
-    child.stderr.on("data", this._updateStderr);
-
-    this._child = child;
-
-    return child.promise
-      .catch(err => {
-        this.logResult(err);
-        throw err;
-      })
-      .then(output => {
-        this.logResult(null, output);
-        return output;
-      });
-  }
-
-  logResult(err, output) {
-    const child = this._child;
-
-    this._logger.removeItem(this._stdoutKey);
-    this._logger.removeItem(this._stderrKey);
-    child.stdout.removeListener("data", this._updateStdout);
-    child.stderr.removeListener("data", this._updateStderr);
-
-    if (err) {
-      this._logger.error(`${chalk.red("Failed")} ${this._logLabel} - ${chalk.red(err.message)}`);
-      output = err.output;
-    } else {
-      const time = ((Date.now() - this._startTime) / 1000).toFixed(2);
-      const dispTime = `${chalk.magenta(time)}secs`;
-      this._logger.info(`Done ${this._logLabel} ${dispTime} ${chalk.green("exit code 0")}`);
-    }
-
-    this.logFinalOutput(err, output);
-  }
-
-  checkForErrors(text) {
-    return this._checkStdoutError && text && text.match(this._checkStdoutError);
-  }
-
-  logFinalOutput(err, output) {
-    const level =
-      err || (this._forceStderr && output.stderr) || this.checkForErrors(output.stdout)
-        ? "error"
-        : this._outputLevel;
-
-    if (!output || (!output.stdout && !output.stderr)) {
-      this._logger[level](`${chalk.green("No output")} from ${this._outputLabel}`);
-      return;
-    }
-
-    const colorize = t => t.replace(/ERR!/g, chalk.red("ERR!"));
-
-    const logs = [chalk.green(">>>"), `Start of output from ${this._outputLabel} ===`];
-
-    if (output.stdout) {
-      logs.push(`\n${colorize(output.stdout)}`);
-    }
-
-    if (output.stderr) {
-      logs.push(chalk.red("\n=== stderr ===\n") + colorize(output.stderr));
-    }
-
-    logs.push(chalk.blue("\n<<<"), `End of output from ${this._outputLabel} ---`);
-    this._logger.prefix(false)[level](...logs);
-  }
-
-  execute(command) {
-    this._startTime = Date.now();
-    const child = xsh.exec(
-      {
-        silent: true,
-        cwd: this._cwd,
-        env: Object.assign({}, process.env, { PWD: this._cwd }),
-        maxBuffer: this._maxBuffer
-      },
-      command || this._command
-    );
-
-    return this.show(child);
-  }
-}
-
-module.exports = VisualExec;