visual-exec 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { VisualExec, VisualExecOptions, ExecOutput, ExecErrorContext, VisualExecError, parsers, jsonLinesParser, keyValueParser } from "./visual-exec.js";
+export { VisualExec, type VisualExecOptions, type ExecOutput, type ExecErrorContext, type 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/visual-exec.d.ts

@@ -1,4 +1,4 @@
-import VisualLogger from "visual-logger";
+import VisualLogger, { type ItemOptions } 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;
@@ -40,7 +40,7 @@ export interface VisualExecOptions {
     /** Visual logger instance to use */
     visualLogger?: VisualLogger;
     /** Spinner style to use */
-    spinner?: any;
+    spinner?: ItemOptions["spinner"];
     /** Title displayed during execution */
     displayTitle?: string;
     /** Label used in log messages */
@@ -126,6 +126,27 @@ export declare const parsers: {
     jsonLines: typeof jsonLinesParser;
     keyValue: typeof keyValueParser;
 };
+export interface SanitizeOptions {
+    /** "space" collapses tabs (single-line contexts), "keep" preserves them (dumps) */
+    tabs?: "space" | "keep";
+    /** what to do with a lone \r - "drop", or "newline" to keep progress redraws readable */
+    cr?: "drop" | "newline";
+    /** append an SGR reset when the text emitted colour, so it cannot bleed into later output */
+    resetAtEnd?: boolean;
+}
+/**
+ * Strip terminal control sequences from child output, keeping colour. Never use this for
+ * output written to a file or handed to a callback - those should get the bytes untouched.
+ */
+export declare function sanitizeText(text: string, options?: SanitizeOptions): string;
+/** Profile for text squeezed into a single progress line. */
+export declare function sanitizeForDisplay(text: string): string;
+/**
+ * Profile for a multi-line transcript written into scrollback: tabs are real formatting,
+ * carriage returns become line breaks so progress redraws stay readable, and a trailing
+ * reset stops an unterminated child colour bleeding into later output.
+ */
+export declare function sanitizeForOutput(text: string): string;
 export declare class VisualExec {
     private _title;
     private _logLabel;
@@ -171,7 +192,14 @@ export declare class VisualExec {
     abort(signal?: string): void;
     /** Alias for abort() */
     kill(signal?: string): void;
-    show(child: ChildProcess): Promise<ExecOutput | unknown>;
+    /**
+     * Attach to an already-started child and render its output.
+     *
+     * Resolves with the command's `ExecOutput`, unless an `onComplete` callback returned a
+     * value - that value is passed through instead. `T` names what the caller expects back;
+     * it defaults to `ExecOutput`, which is what a run without an `onComplete` produces.
+     */
+    show<T = ExecOutput>(child: ChildProcess): Promise<T>;
     logResult(err: VisualExecError | null, output?: ExecOutput): void;
     checkForErrors(text: string): RegExpMatchArray | null;
     /**
@@ -179,6 +207,12 @@ export declare class VisualExec {
      * Set to a no-op function to suppress output logging.
      */
     logFinalOutput(err: VisualExecError | null, output: ExecOutput): void;
-    execute(command?: string): Promise<ExecOutput | unknown>;
+    /**
+     * Run the command and render its output.
+     *
+     * Resolves with `ExecOutput`, or with whatever an `onComplete` callback returned in its
+     * place. `T` defaults to `ExecOutput` so the common case needs no cast at the call site.
+     */
+    execute<T = ExecOutput>(command?: string): Promise<T>;
 }
 export default VisualExec;

package/dist/visual-exec.js

@@ -3,7 +3,7 @@ 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 VisualLogger, {} from "visual-logger";
 import hasAnsi from "has-ansi";
 import stripAnsi from "strip-ansi";
 // Set xsh to use native Promise
@@ -70,6 +70,70 @@ export const parsers = {
     jsonLines: jsonLinesParser,
     keyValue: keyValueParser
 };
+//
+// Child output is captured from a pipe and rendered back into this process's terminal. It
+// can carry the child's own control sequences - a nested fyn renders its own visual logger
+// and emits eraseLine/cursorUp runs. Those are zero-width to string-width, so line
+// accounting stays correct while the terminal still *executes* them, walking the cursor up
+// and erasing committed output.
+//
+// Keep SGR (colour); drop anything that can move the cursor, erase, scroll, switch charset,
+// set the window title, or write the clipboard.
+//
+// The escape grammar, in the order the alternation must test it:
+//   CSI                ESC [ params intermediates final
+//   OSC/DCS/PM/APC/SOS ESC ] P ^ _ X ... terminated by BEL or ST (or truncated at end)
+//   nF                 ESC intermediates(0x20-0x2F)+ final    e.g. ESC(0, ESC#8, ESC%G
+//   Fp/Fe/Fs           ESC single(0x30-0x7E)                  e.g. ESC7, ESCc, ESC M
+//
+const ESCAPE_SEQUENCE = new RegExp("\u001B(?:" +
+    "\\[[0-?]*[ -/]*[@-~]" +
+    "|[\\]P^_X][\\s\\S]*?(?:\\u0007|\u001B\\\\|$)" +
+    "|[ -/]+[0-~]" +
+    "|[0-~]" +
+    ")", "g");
+const SGR_SEQUENCE = new RegExp("^\u001B\\[[0-?]*[ -/]*m$");
+const HAS_SGR = new RegExp("\u001B\\[[0-?]*[ -/]*m");
+const SGR_RESET = "\u001B[0m";
+// 8-bit C1 controls: escapes without the ESC byte. 0x9B is an 8-bit CSI and 0x9D/0x90 are
+// 8-bit OSC/DCS, so consume their payload too - dropping only the introducer would leave the
+// parameters behind as inert but visible junk. Anything left is stripped bare.
+const C1_SEQUENCE = /[\u009B][0-?]*[ -/]*[@-~]|[\u009D\u0090\u009E\u009F][\s\S]*?(?:\u0007|\u009C|$)/g;
+const C1_CONTROL = /[\u0080-\u009F]/g;
+// C0 controls that move the cursor or clear the screen. \n and \t are left to the profile,
+// and \u001B is left alone - the only ones remaining are inside kept SGR sequences.
+// eslint-disable-next-line no-control-regex
+const UNSAFE_CONTROL = /[\u0000-\u0008\u000B-\u001A\u001C-\u001F\u007F]/g;
+/**
+ * Strip terminal control sequences from child output, keeping colour. Never use this for
+ * output written to a file or handed to a callback - those should get the bytes untouched.
+ */
+export function sanitizeText(text, options = {}) {
+    const { tabs = "space", cr = "drop", resetAtEnd = false } = options;
+    let out = text.replace(ESCAPE_SEQUENCE, seq => (SGR_SEQUENCE.test(seq) ? seq : ""));
+    // must run before UNSAFE_CONTROL, which would otherwise swallow the \r
+    if (cr === "newline") {
+        out = out.replace(/\r\n?/g, "\n");
+    }
+    out = out
+        .replace(/\t/g, tabs === "keep" ? "\t" : " ")
+        .replace(C1_SEQUENCE, "")
+        .replace(C1_CONTROL, "")
+        .replace(UNSAFE_CONTROL, "");
+    return resetAtEnd && HAS_SGR.test(out) ? out + SGR_RESET : out;
+}
+/** Profile for text squeezed into a single progress line. */
+export function sanitizeForDisplay(text) {
+    return sanitizeText(text, { tabs: "space", cr: "drop" });
+}
+/**
+ * Profile for a multi-line transcript written into scrollback: tabs are real formatting,
+ * carriage returns become line breaks so progress redraws stay readable, and a trailing
+ * reset stops an unterminated child colour bleeding into later output.
+ */
+export function sanitizeForOutput(text) {
+    return sanitizeText(text, { tabs: "keep", cr: "newline", resetAtEnd: true });
+}
 export class VisualExec {
     constructor(options) {
         this._aborted = false;
@@ -157,7 +221,9 @@ export class VisualExec {
             this._onProgress(progress);
     }
     _updateDigest(item, buf) {
-        const newBuf = item.buf + buf;
+        // sanitize at the boundary so every downstream use - lines, item.buf, the item message -
+        // is already inert. Raw output still reaches onOutput/outputFile via _createDataHandler.
+        const newBuf = item.buf + sanitizeForDisplay(buf);
         const lines = newBuf
             .split("\n")
             .map(x => x && x.trim())
@@ -228,6 +294,13 @@ export class VisualExec {
     kill(signal) {
         this.abort(signal);
     }
+    /**
+     * Attach to an already-started child and render its output.
+     *
+     * Resolves with the command's `ExecOutput`, unless an `onComplete` callback returned a
+     * value - that value is passed through instead. `T` names what the caller expects back;
+     * it defaults to `ExecOutput`, which is what a run without an `onComplete` produces.
+     */
     show(child) {
         this._stdoutKey = Symbol("visual-exec-stdout");
         this._stderrKey = Symbol("visual-exec-stderr");
@@ -270,10 +343,11 @@ export class VisualExec {
         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);
+            var _a;
+            var _b, _c, _d;
+            const output = (_b = err.output) !== null && _b !== void 0 ? _b : { stdout: "", stderr: "" };
+            const exitCode = (_d = (_c = err.exitCode) !== null && _c !== void 0 ? _c : err.code) !== null && _d !== void 0 ? _d : 1;
+            (_a = this._onComplete) === null || _a === void 0 ? void 0 : _a.call(this, output, exitCode);
             this.logResult(err);
             throw err;
         })
@@ -352,6 +426,8 @@ export class VisualExec {
             });
             execPromise = Promise.race([execPromise, abortPromise]);
         }
+        // The runtime value is `ExecOutput` unless `onComplete` substituted its own; only the
+        // caller knows which, so the promise is handed back as the `T` they asked for.
         return execPromise.finally(cleanup);
     }
     logResult(err, output) {
@@ -393,7 +469,12 @@ export class VisualExec {
             this._logger[level](`${chalk.green("No output")} from ${this._outputLabel}`);
             return;
         }
-        const colorize = (t) => t.replace(/ERR!/g, chalk.red("ERR!"));
+        //
+        // The child's bytes end up on this terminal and in the saved log data, so scrub the
+        // control sequences out first - an error report that erases the lines above it is worse
+        // than useless. sanitizeForOutput runs before colorize, which only adds SGR.
+        //
+        const colorize = (t) => sanitizeForOutput(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)}`);
@@ -404,6 +485,12 @@ export class VisualExec {
         logs.push(chalk.blue("\n<<<"), `End of output from ${this._outputLabel} ---`);
         this._logger.prefix(false)[level](...logs);
     }
+    /**
+     * Run the command and render its output.
+     *
+     * Resolves with `ExecOutput`, or with whatever an `onComplete` callback returned in its
+     * place. `T` defaults to `ExecOutput` so the common case needs no cast at the call site.
+     */
     execute(command) {
         this._startTime = Date.now();
         this._aborted = false;
@@ -421,22 +508,20 @@ export class VisualExec {
             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)
-            });
-        };
+        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;
+            var _a;
+            var _b, _c, _d, _e;
+            const output = (_b = err.output) !== null && _b !== void 0 ? _b : { stdout: "", stderr: "" };
+            const exitCode = (_c = err.code) !== null && _c !== void 0 ? _c : 1;
+            const signal = (_e = (_d = err.signal) !== null && _d !== void 0 ? _d : (((_a = result.child) === null || _a === void 0 ? void 0 : _a.killed) ? "SIGTERM" : null)) !== null && _e !== void 0 ? _e : null;
             const context = {
                 ...baseContext(output),
                 exitCode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visual-exec",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "homepage": "https://github.com/jchip/fynjs/tree/main/packages/visual-exec",
   "description": "Visual shell exec with spinners and progress display",
   "type": "module",
@@ -14,12 +14,12 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=22.18.0"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
     "test": "vitest run",
-    "ci:check": "tsc --noEmit -p tsconfig.json && npm test",
+    "ci:check": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json && npm test",
     "test:watch": "vitest",
     "prepublishOnly": "xrun --serial build test",
     "postpack": "publish-util-postpack"
@@ -49,8 +49,8 @@
     "ci-info": "^4.4.0",
     "has-ansi": "^6.0.2",
     "strip-ansi": "^7.2.0",
-    "visual-logger": "^2.0.0",
-    "xsh": "^1.0.1"
+    "visual-logger": "^2.1.0",
+    "xsh": "^1.1.0"
   },
   "sideEffects": false
 }