visual-exec 1.0.0 → 1.0.2

package/dist/visual-exec.d.ts

@@ -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;

package/dist/visual-exec.js

@@ -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())
@@ -393,7 +459,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)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visual-exec",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "homepage": "https://github.com/jchip/fynjs/tree/main/packages/visual-exec",
   "description": "Visual shell exec with spinners and progress display",
   "type": "module",
@@ -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.0"
+    "visual-logger": "^2.0.1",
+    "xsh": "^1.0.1"
   },
   "sideEffects": false
 }