@socketsecurity/lib 0.0.0 → 1.0.0

package/dist/stdio/footer.js

@@ -0,0 +1,96 @@
+/* Socket Lib - Built with esbuild */
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var footer_exports = {};
+__export(footer_exports, {
+  createFooter: () => createFooter,
+  createSummaryFooter: () => createSummaryFooter
+});
+module.exports = __toCommonJS(footer_exports);
+var import_yoctocolors_cjs = __toESM(require("../external/yoctocolors-cjs"));
+var import_strings = require("../strings");
+function createFooter(message, options) {
+  const {
+    borderChar = "=",
+    color = "gray",
+    showDuration = false,
+    showTimestamp = false,
+    startTime,
+    width = 80
+  } = { __proto__: null, ...options };
+  const border = (0, import_strings.repeatString)(borderChar, width);
+  const lines = [];
+  if (message) {
+    const colorFn = color && import_yoctocolors_cjs.default[color] ? import_yoctocolors_cjs.default[color] : (s) => s;
+    lines.push(colorFn(message));
+  }
+  if (showTimestamp) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    lines.push(import_yoctocolors_cjs.default.gray(`Completed at: ${timestamp}`));
+  }
+  if (showDuration && startTime) {
+    const duration = Date.now() - startTime;
+    const seconds = (duration / 1e3).toFixed(2);
+    lines.push(import_yoctocolors_cjs.default.gray(`Duration: ${seconds}s`));
+  }
+  lines.push(border);
+  return lines.join("\n");
+}
+function createSummaryFooter(stats, options) {
+  const parts = [];
+  if (stats.total !== void 0) {
+    parts.push(`Total: ${stats.total}`);
+  }
+  if (stats.success !== void 0) {
+    parts.push(import_yoctocolors_cjs.default.green(`\u2713 ${stats.success} passed`));
+  }
+  if (stats.failed !== void 0 && stats.failed > 0) {
+    parts.push(import_yoctocolors_cjs.default.red(`\u2717 ${stats.failed} failed`));
+  }
+  if (stats.skipped !== void 0 && stats.skipped > 0) {
+    parts.push(import_yoctocolors_cjs.default.yellow(`\u25CB ${stats.skipped} skipped`));
+  }
+  if (stats.warnings !== void 0 && stats.warnings > 0) {
+    parts.push(import_yoctocolors_cjs.default.yellow(`\u26A0 ${stats.warnings} warnings`));
+  }
+  if (stats.errors !== void 0 && stats.errors > 0) {
+    parts.push(import_yoctocolors_cjs.default.red(`\u2717 ${stats.errors} errors`));
+  }
+  const message = parts.join(" | ");
+  return createFooter(message, {
+    ...options,
+    showDuration: stats.duration !== void 0,
+    ...stats.duration !== void 0 && { startTime: stats.duration }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createFooter,
+  createSummaryFooter
+});
+//# sourceMappingURL=footer.js.map

package/dist/stdio/footer.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/stdio/footer.ts"],
+  "sourcesContent": ["/**\n * Console footer/summary formatting utilities.\n * Provides consistent footer and summary formatting for CLI applications.\n */\n\nimport colors from '../external/yoctocolors-cjs'\nimport { repeatString } from '../strings'\n\nexport interface FooterOptions {\n  width?: number | undefined\n  borderChar?: string | undefined\n  showTimestamp?: boolean | undefined\n  showDuration?: boolean | undefined\n  startTime?: number | undefined\n  color?:\n    | 'cyan'\n    | 'green'\n    | 'yellow'\n    | 'blue'\n    | 'magenta'\n    | 'red'\n    | 'gray'\n    | undefined\n}\n\nexport interface SummaryStats {\n  total?: number | undefined\n  success?: number | undefined\n  failed?: number | undefined\n  skipped?: number | undefined\n  warnings?: number | undefined\n  errors?: number | undefined\n  duration?: number | undefined\n}\n\n/**\n * Create a formatted footer.\n */\nexport function createFooter(\n  message?: string,\n  options?: FooterOptions,\n): string {\n  const {\n    borderChar = '=',\n    color = 'gray',\n    showDuration = false,\n    showTimestamp = false,\n    startTime,\n    width = 80,\n  } = { __proto__: null, ...options } as FooterOptions\n\n  const border = repeatString(borderChar, width)\n  const lines: string[] = []\n\n  if (message) {\n    const colorFn = color && colors[color] ? colors[color] : (s: string) => s\n    lines.push(colorFn(message))\n  }\n\n  if (showTimestamp) {\n    const timestamp = new Date().toISOString()\n    lines.push(colors.gray(`Completed at: ${timestamp}`))\n  }\n\n  if (showDuration && startTime) {\n    const duration = Date.now() - startTime\n    const seconds = (duration / 1000).toFixed(2)\n    lines.push(colors.gray(`Duration: ${seconds}s`))\n  }\n\n  lines.push(border)\n  return lines.join('\\n')\n}\n\n/**\n * Create a summary footer with statistics.\n */\nexport function createSummaryFooter(\n  stats: SummaryStats,\n  options?: FooterOptions,\n): string {\n  const parts: string[] = []\n\n  if (stats.total !== undefined) {\n    parts.push(`Total: ${stats.total}`)\n  }\n\n  if (stats.success !== undefined) {\n    parts.push(colors.green(`\u2713 ${stats.success} passed`))\n  }\n\n  if (stats.failed !== undefined && stats.failed > 0) {\n    parts.push(colors.red(`\u2717 ${stats.failed} failed`))\n  }\n\n  if (stats.skipped !== undefined && stats.skipped > 0) {\n    parts.push(colors.yellow(`\u25CB ${stats.skipped} skipped`))\n  }\n\n  if (stats.warnings !== undefined && stats.warnings > 0) {\n    parts.push(colors.yellow(`\u26A0 ${stats.warnings} warnings`))\n  }\n\n  if (stats.errors !== undefined && stats.errors > 0) {\n    parts.push(colors.red(`\u2717 ${stats.errors} errors`))\n  }\n\n  const message = parts.join(' | ')\n  return createFooter(message, {\n    ...options,\n    showDuration: stats.duration !== undefined,\n    ...(stats.duration !== undefined && { startTime: stats.duration }),\n  })\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,6BAAmB;AACnB,qBAA6B;AAgCtB,SAAS,aACd,SACA,SACQ;AACR,QAAM;AAAA,IACJ,aAAa;AAAA,IACb,QAAQ;AAAA,IACR,eAAe;AAAA,IACf,gBAAgB;AAAA,IAChB;AAAA,IACA,QAAQ;AAAA,EACV,IAAI,EAAE,WAAW,MAAM,GAAG,QAAQ;AAElC,QAAM,aAAS,6BAAa,YAAY,KAAK;AAC7C,QAAM,QAAkB,CAAC;AAEzB,MAAI,SAAS;AACX,UAAM,UAAU,SAAS,uBAAAA,QAAO,KAAK,IAAI,uBAAAA,QAAO,KAAK,IAAI,CAAC,MAAc;AACxE,UAAM,KAAK,QAAQ,OAAO,CAAC;AAAA,EAC7B;AAEA,MAAI,eAAe;AACjB,UAAM,aAAY,oBAAI,KAAK,GAAE,YAAY;AACzC,UAAM,KAAK,uBAAAA,QAAO,KAAK,iBAAiB,SAAS,EAAE,CAAC;AAAA,EACtD;AAEA,MAAI,gBAAgB,WAAW;AAC7B,UAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,UAAM,WAAW,WAAW,KAAM,QAAQ,CAAC;AAC3C,UAAM,KAAK,uBAAAA,QAAO,KAAK,aAAa,OAAO,GAAG,CAAC;AAAA,EACjD;AAEA,QAAM,KAAK,MAAM;AACjB,SAAO,MAAM,KAAK,IAAI;AACxB;AAKO,SAAS,oBACd,OACA,SACQ;AACR,QAAM,QAAkB,CAAC;AAEzB,MAAI,MAAM,UAAU,QAAW;AAC7B,UAAM,KAAK,UAAU,MAAM,KAAK,EAAE;AAAA,EACpC;AAEA,MAAI,MAAM,YAAY,QAAW;AAC/B,UAAM,KAAK,uBAAAA,QAAO,MAAM,UAAK,MAAM,OAAO,SAAS,CAAC;AAAA,EACtD;AAEA,MAAI,MAAM,WAAW,UAAa,MAAM,SAAS,GAAG;AAClD,UAAM,KAAK,uBAAAA,QAAO,IAAI,UAAK,MAAM,MAAM,SAAS,CAAC;AAAA,EACnD;AAEA,MAAI,MAAM,YAAY,UAAa,MAAM,UAAU,GAAG;AACpD,UAAM,KAAK,uBAAAA,QAAO,OAAO,UAAK,MAAM,OAAO,UAAU,CAAC;AAAA,EACxD;AAEA,MAAI,MAAM,aAAa,UAAa,MAAM,WAAW,GAAG;AACtD,UAAM,KAAK,uBAAAA,QAAO,OAAO,UAAK,MAAM,QAAQ,WAAW,CAAC;AAAA,EAC1D;AAEA,MAAI,MAAM,WAAW,UAAa,MAAM,SAAS,GAAG;AAClD,UAAM,KAAK,uBAAAA,QAAO,IAAI,UAAK,MAAM,MAAM,SAAS,CAAC;AAAA,EACnD;AAEA,QAAM,UAAU,MAAM,KAAK,KAAK;AAChC,SAAO,aAAa,SAAS;AAAA,IAC3B,GAAG;AAAA,IACH,cAAc,MAAM,aAAa;AAAA,IACjC,GAAI,MAAM,aAAa,UAAa,EAAE,WAAW,MAAM,SAAS;AAAA,EAClE,CAAC;AACH;",
+  "names": ["colors"]
+}

package/dist/stdio/header.d.ts

@@ -0,0 +1,25 @@
+export interface HeaderOptions {
+    width?: number;
+    borderChar?: string;
+    padding?: number;
+    color?: 'cyan' | 'green' | 'yellow' | 'blue' | 'magenta' | 'red' | 'gray';
+    bold?: boolean;
+}
+/**
+ * Create a formatted header/banner.
+ */
+export declare function createHeader(title: string, options?: HeaderOptions): string;
+/**
+ * Create a simple section header.
+ */
+export declare function createSectionHeader(title: string, options?: HeaderOptions): string;
+/**
+ * Print a header directly to stdout.
+ * Standard formatting: 55 chars wide with ═ borders.
+ */
+export declare function printHeader(title: string): void;
+/**
+ * Print a footer with optional message.
+ * Uses ─ as the border character.
+ */
+export declare function printFooter(message?: string): void;

package/dist/stdio/header.js

@@ -0,0 +1,102 @@
+/* Socket Lib - Built with esbuild */
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var header_exports = {};
+__export(header_exports, {
+  createHeader: () => createHeader,
+  createSectionHeader: () => createSectionHeader,
+  printFooter: () => printFooter,
+  printHeader: () => printHeader
+});
+module.exports = __toCommonJS(header_exports);
+var import_yoctocolors_cjs = __toESM(require("../external/yoctocolors-cjs"));
+var import_strings = require("../strings");
+function createHeader(title, options) {
+  const {
+    bold = true,
+    borderChar = "=",
+    color = "cyan",
+    padding = 1,
+    width = 80
+  } = { __proto__: null, ...options };
+  const border = (0, import_strings.repeatString)(borderChar, width);
+  let formattedTitle = title;
+  if (color && import_yoctocolors_cjs.default[color]) {
+    formattedTitle = import_yoctocolors_cjs.default[color](formattedTitle);
+  }
+  if (bold && import_yoctocolors_cjs.default.bold) {
+    formattedTitle = import_yoctocolors_cjs.default.bold(formattedTitle);
+  }
+  const centeredTitle = (0, import_strings.centerText)(formattedTitle, width);
+  const paddingLine = (0, import_strings.repeatString)(" ", width);
+  const lines = [border];
+  for (let i = 0; i < padding; i++) {
+    lines.push(paddingLine);
+  }
+  lines.push(centeredTitle);
+  for (let i = 0; i < padding; i++) {
+    lines.push(paddingLine);
+  }
+  lines.push(border);
+  return lines.join("\n");
+}
+function createSectionHeader(title, options) {
+  const {
+    borderChar = "-",
+    color = "blue",
+    width = 60
+  } = { __proto__: null, ...options };
+  return createHeader(title, {
+    width,
+    borderChar,
+    padding: 0,
+    color,
+    bold: false
+  });
+}
+function printHeader(title) {
+  const border = (0, import_strings.repeatString)("\u2550", 55);
+  console.log(border);
+  console.log(`  ${title}`);
+  console.log(border);
+}
+function printFooter(message) {
+  const border = (0, import_strings.repeatString)("\u2500", 55);
+  console.log(border);
+  if (message) {
+    console.log(import_yoctocolors_cjs.default.green(message));
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createHeader,
+  createSectionHeader,
+  printFooter,
+  printHeader
+});
+//# sourceMappingURL=header.js.map

package/dist/stdio/header.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/stdio/header.ts"],
+  "sourcesContent": ["/**\n * Console header/banner formatting utilities.\n * Provides consistent header formatting for CLI applications.\n */\n\nimport colors from '../external/yoctocolors-cjs'\nimport { centerText, repeatString } from '../strings'\n\nexport interface HeaderOptions {\n  width?: number\n  borderChar?: string\n  padding?: number\n  color?: 'cyan' | 'green' | 'yellow' | 'blue' | 'magenta' | 'red' | 'gray'\n  bold?: boolean\n}\n\n/**\n * Create a formatted header/banner.\n */\nexport function createHeader(title: string, options?: HeaderOptions): string {\n  const {\n    bold = true,\n    borderChar = '=',\n    color = 'cyan',\n    padding = 1,\n    width = 80,\n  } = { __proto__: null, ...options } as HeaderOptions\n\n  const border = repeatString(borderChar, width)\n\n  // Apply color and bold\n  let formattedTitle = title\n  if (color && colors[color]) {\n    formattedTitle = colors[color](formattedTitle)\n  }\n  if (bold && colors.bold) {\n    formattedTitle = colors.bold(formattedTitle)\n  }\n\n  const centeredTitle = centerText(formattedTitle, width)\n  const paddingLine = repeatString(' ', width)\n\n  const lines: string[] = [border]\n\n  for (let i = 0; i < padding; i++) {\n    lines.push(paddingLine)\n  }\n\n  lines.push(centeredTitle)\n\n  for (let i = 0; i < padding; i++) {\n    lines.push(paddingLine)\n  }\n\n  lines.push(border)\n\n  return lines.join('\\n')\n}\n\n/**\n * Create a simple section header.\n */\nexport function createSectionHeader(\n  title: string,\n  options?: HeaderOptions,\n): string {\n  const {\n    borderChar = '-',\n    color = 'blue',\n    width = 60,\n  } = { __proto__: null, ...options } as HeaderOptions\n\n  return createHeader(title, {\n    width,\n    borderChar,\n    padding: 0,\n    color,\n    bold: false,\n  })\n}\n\n/**\n * Print a header directly to stdout.\n * Standard formatting: 55 chars wide with \u2550 borders.\n */\nexport function printHeader(title: string): void {\n  const border = repeatString('\u2550', 55)\n  console.log(border)\n  console.log(`  ${title}`)\n  console.log(border)\n}\n\n/**\n * Print a footer with optional message.\n * Uses \u2500 as the border character.\n */\nexport function printFooter(message?: string): void {\n  const border = repeatString('\u2500', 55)\n  console.log(border)\n  if (message) {\n    console.log(colors.green(message))\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,6BAAmB;AACnB,qBAAyC;AAalC,SAAS,aAAa,OAAe,SAAiC;AAC3E,QAAM;AAAA,IACJ,OAAO;AAAA,IACP,aAAa;AAAA,IACb,QAAQ;AAAA,IACR,UAAU;AAAA,IACV,QAAQ;AAAA,EACV,IAAI,EAAE,WAAW,MAAM,GAAG,QAAQ;AAElC,QAAM,aAAS,6BAAa,YAAY,KAAK;AAG7C,MAAI,iBAAiB;AACrB,MAAI,SAAS,uBAAAA,QAAO,KAAK,GAAG;AAC1B,qBAAiB,uBAAAA,QAAO,KAAK,EAAE,cAAc;AAAA,EAC/C;AACA,MAAI,QAAQ,uBAAAA,QAAO,MAAM;AACvB,qBAAiB,uBAAAA,QAAO,KAAK,cAAc;AAAA,EAC7C;AAEA,QAAM,oBAAgB,2BAAW,gBAAgB,KAAK;AACtD,QAAM,kBAAc,6BAAa,KAAK,KAAK;AAE3C,QAAM,QAAkB,CAAC,MAAM;AAE/B,WAAS,IAAI,GAAG,IAAI,SAAS,KAAK;AAChC,UAAM,KAAK,WAAW;AAAA,EACxB;AAEA,QAAM,KAAK,aAAa;AAExB,WAAS,IAAI,GAAG,IAAI,SAAS,KAAK;AAChC,UAAM,KAAK,WAAW;AAAA,EACxB;AAEA,QAAM,KAAK,MAAM;AAEjB,SAAO,MAAM,KAAK,IAAI;AACxB;AAKO,SAAS,oBACd,OACA,SACQ;AACR,QAAM;AAAA,IACJ,aAAa;AAAA,IACb,QAAQ;AAAA,IACR,QAAQ;AAAA,EACV,IAAI,EAAE,WAAW,MAAM,GAAG,QAAQ;AAElC,SAAO,aAAa,OAAO;AAAA,IACzB;AAAA,IACA;AAAA,IACA,SAAS;AAAA,IACT;AAAA,IACA,MAAM;AAAA,EACR,CAAC;AACH;AAMO,SAAS,YAAY,OAAqB;AAC/C,QAAM,aAAS,6BAAa,UAAK,EAAE;AACnC,UAAQ,IAAI,MAAM;AAClB,UAAQ,IAAI,KAAK,KAAK,EAAE;AACxB,UAAQ,IAAI,MAAM;AACpB;AAMO,SAAS,YAAY,SAAwB;AAClD,QAAM,aAAS,6BAAa,UAAK,EAAE;AACnC,UAAQ,IAAI,MAAM;AAClB,MAAI,SAAS;AACX,YAAQ,IAAI,uBAAAA,QAAO,MAAM,OAAO,CAAC;AAAA,EACnC;AACF;",
+  "names": ["colors"]
+}

package/dist/stdio/mask.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Interactive output masking utilities for CLI tools.
+ * Provides output control with keyboard toggling (ctrl+o).
+ *
+ * ANSI Escape Sequences Used:
+ * - '\r': Carriage return - moves cursor to beginning of current line.
+ * - '\x1b[K' or '\x1b[0K': CSI K (erase line) - clear from cursor to end of line.
+ * - '\x1b[2K': CSI 2K - erase entire line.
+ * - '\x1b[1A': CSI A - move cursor up 1 line.
+ *
+ * Terminal Control:
+ * - Raw mode (setRawMode(true)): Captures keypresses immediately without buffering.
+ * - TTY detection: Ensures terminal manipulation only occurs in interactive terminals.
+ *
+ * Key Features:
+ * - Output buffering: Stores up to 1000 lines when masked to prevent memory issues.
+ * - Graceful cleanup: Always restores terminal to normal mode on exit/error.
+ * - Visual feedback: Uses spinner to indicate process is running when output is masked.
+ */
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+import readline from 'node:readline';
+export interface OutputMaskOptions {
+    /** Current working directory */
+    cwd?: string;
+    /** Environment variables */
+    env?: NodeJS.ProcessEnv;
+    /** Progress message to display */
+    message?: string;
+    /** Show output by default instead of masking it */
+    showOutput?: boolean;
+    /** Text to show after "ctrl+o" in spinner */
+    toggleText?: string;
+}
+export interface OutputMask {
+    /** Whether output is currently visible */
+    verbose: boolean;
+    /** Buffered output lines */
+    outputBuffer: string[];
+    /** Whether spinner is currently active */
+    isSpinning: boolean;
+}
+/**
+ * Create an output mask for controlling command output visibility.
+ * The mask tracks whether output should be shown or hidden (buffered).
+ * When hidden, output is buffered and a spinner is shown instead.
+ */
+export declare function createOutputMask(options?: OutputMaskOptions): OutputMask;
+/**
+ * Create a keyboard handler for toggling output visibility.
+ * Handles two key combinations:
+ * - ctrl+o: Toggle between showing and hiding output.
+ * - ctrl+c: Cancel the running process.
+ * The handler manipulates terminal state using ANSI escape sequences.
+ */
+export declare function createKeyboardHandler(mask: OutputMask, child: ChildProcess, options?: OutputMaskOptions): (_str: string, key: readline.Key) => void;
+/**
+ * Attach output masking to a child process.
+ * Returns a promise that resolves with the exit code.
+ * This function:
+ * - Sets up keyboard input handling in raw mode for immediate key capture.
+ * - Buffers stdout/stderr when not in verbose mode.
+ * - Shows a spinner when output is masked.
+ * - Allows toggling between masked and unmasked output with ctrl+o.
+ */
+export declare function attachOutputMask(child: ChildProcess, options?: OutputMaskOptions): Promise<number>;
+/**
+ * Run a command with interactive output masking.
+ * Convenience wrapper around spawn + attachOutputMask.
+ * Spawns a child process and attaches the output masking system to it.
+ * stdin is inherited, stdout and stderr are piped for masking control.
+ */
+export declare function runWithMask(command: string, args?: string[], options?: OutputMaskOptions & SpawnOptions): Promise<number>;

package/dist/stdio/mask.js

@@ -0,0 +1,187 @@
+/* Socket Lib - Built with esbuild */
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var mask_exports = {};
+__export(mask_exports, {
+  attachOutputMask: () => attachOutputMask,
+  createKeyboardHandler: () => createKeyboardHandler,
+  createOutputMask: () => createOutputMask,
+  runWithMask: () => runWithMask
+});
+module.exports = __toCommonJS(mask_exports);
+var import_node_child_process = require("node:child_process");
+var import_node_readline = __toESM(require("node:readline"));
+var import_spinner = require("../spinner.js");
+var import_clear = require("./clear.js");
+var import_stdout = require("./stdout.js");
+function createOutputMask(options = {}) {
+  const { showOutput = false } = options;
+  return {
+    verbose: showOutput,
+    outputBuffer: [],
+    isSpinning: !showOutput
+  };
+}
+function createKeyboardHandler(mask, child, options = {}) {
+  const { message = "Running\u2026", toggleText = "to see full output" } = options;
+  return (_str, key) => {
+    if (key?.ctrl && key.name === "o") {
+      mask.verbose = !mask.verbose;
+      if (mask.verbose) {
+        if (mask.isSpinning) {
+          import_spinner.spinner.stop();
+          mask.isSpinning = false;
+        }
+        (0, import_clear.clearLine)();
+        if (mask.outputBuffer.length > 0) {
+          console.log("--- Output (ctrl+o to hide) ---");
+          mask.outputBuffer.forEach((line) => {
+            (0, import_stdout.write)(line);
+          });
+        }
+      } else {
+        if (mask.outputBuffer.length > 0) {
+          const lineCount = mask.outputBuffer.join("").split("\n").length + 1;
+          for (let i = 0; i < lineCount; i += 1) {
+            process.stdout.write("\x1B[1A\x1B[2K");
+          }
+        }
+        (0, import_clear.clearLine)();
+        mask.outputBuffer = [];
+        if (!mask.isSpinning) {
+          import_spinner.spinner.start(`${message} (ctrl+o ${toggleText})`);
+          mask.isSpinning = true;
+        }
+      }
+    } else if (key?.ctrl && key.name === "c") {
+      child.kill("SIGTERM");
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      throw new Error("Process cancelled by user");
+    }
+  };
+}
+function attachOutputMask(child, options = {}) {
+  return new Promise((resolve, reject) => {
+    const { message = "Running\u2026" } = options;
+    const mask = createOutputMask(options);
+    if (mask.isSpinning && process.stdout.isTTY) {
+      import_spinner.spinner.start(
+        `${message} (ctrl+o ${options.toggleText || "to see full output"})`
+      );
+    }
+    if (process.stdin.isTTY) {
+      import_node_readline.default.emitKeypressEvents(process.stdin);
+      process.stdin.setRawMode(true);
+      const keypressHandler = createKeyboardHandler(mask, child, options);
+      process.stdin.on("keypress", keypressHandler);
+      child.on("exit", () => {
+        if (process.stdin.isTTY) {
+          process.stdin.setRawMode(false);
+          process.stdin.removeListener("keypress", keypressHandler);
+        }
+      });
+    }
+    if (child.stdout) {
+      child.stdout.on("data", (data) => {
+        const text = data.toString();
+        if (mask.verbose) {
+          (0, import_stdout.write)(text);
+        } else {
+          mask.outputBuffer.push(text);
+          const lines = mask.outputBuffer.join("").split("\n");
+          if (lines.length > 1e3) {
+            mask.outputBuffer = [lines.slice(-1e3).join("\n")];
+          }
+        }
+        return void 0;
+      });
+    }
+    if (child.stderr) {
+      child.stderr.on("data", (data) => {
+        const text = data.toString();
+        if (mask.verbose) {
+          process.stderr.write(text);
+        } else {
+          mask.outputBuffer.push(text);
+        }
+        return void 0;
+      });
+    }
+    child.on("exit", (code) => {
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      if (mask.isSpinning) {
+        if (code === 0) {
+          import_spinner.spinner.successAndStop(`${message} completed`);
+        } else {
+          import_spinner.spinner.failAndStop(`${message} failed`);
+          if (mask.outputBuffer.length > 0 && !mask.verbose) {
+            console.log("\n--- Output ---");
+            mask.outputBuffer.forEach((line) => {
+              (0, import_stdout.write)(line);
+            });
+          }
+        }
+      }
+      resolve(code || 0);
+    });
+    child.on("error", (error) => {
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      if (mask.isSpinning) {
+        import_spinner.spinner.failAndStop(`${message} error`);
+      }
+      reject(error);
+    });
+  });
+}
+async function runWithMask(command, args = [], options = {}) {
+  const {
+    message = "Running\u2026",
+    showOutput = false,
+    toggleText = "to see output",
+    ...spawnOptions
+  } = options;
+  const child = (0, import_node_child_process.spawn)(command, args, {
+    stdio: ["inherit", "pipe", "pipe"],
+    ...spawnOptions
+  });
+  return await attachOutputMask(child, { message, showOutput, toggleText });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  attachOutputMask,
+  createKeyboardHandler,
+  createOutputMask,
+  runWithMask
+});
+//# sourceMappingURL=mask.js.map

package/dist/stdio/mask.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/stdio/mask.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Interactive output masking utilities for CLI tools.\n * Provides output control with keyboard toggling (ctrl+o).\n *\n * ANSI Escape Sequences Used:\n * - '\\r': Carriage return - moves cursor to beginning of current line.\n * - '\\x1b[K' or '\\x1b[0K': CSI K (erase line) - clear from cursor to end of line.\n * - '\\x1b[2K': CSI 2K - erase entire line.\n * - '\\x1b[1A': CSI A - move cursor up 1 line.\n *\n * Terminal Control:\n * - Raw mode (setRawMode(true)): Captures keypresses immediately without buffering.\n * - TTY detection: Ensures terminal manipulation only occurs in interactive terminals.\n *\n * Key Features:\n * - Output buffering: Stores up to 1000 lines when masked to prevent memory issues.\n * - Graceful cleanup: Always restores terminal to normal mode on exit/error.\n * - Visual feedback: Uses spinner to indicate process is running when output is masked.\n */\n\nimport type { ChildProcess, SpawnOptions } from 'node:child_process'\nimport { spawn } from 'node:child_process'\nimport readline from 'node:readline'\nimport { spinner } from '../spinner.js'\nimport { clearLine } from './clear.js'\nimport { write } from './stdout.js'\n\nexport interface OutputMaskOptions {\n  /** Current working directory */\n  cwd?: string\n  /** Environment variables */\n  env?: NodeJS.ProcessEnv\n  /** Progress message to display */\n  message?: string\n  /** Show output by default instead of masking it */\n  showOutput?: boolean\n  /** Text to show after \"ctrl+o\" in spinner */\n  toggleText?: string\n}\n\nexport interface OutputMask {\n  /** Whether output is currently visible */\n  verbose: boolean\n  /** Buffered output lines */\n  outputBuffer: string[]\n  /** Whether spinner is currently active */\n  isSpinning: boolean\n}\n\n/**\n * Create an output mask for controlling command output visibility.\n * The mask tracks whether output should be shown or hidden (buffered).\n * When hidden, output is buffered and a spinner is shown instead.\n */\nexport function createOutputMask(options: OutputMaskOptions = {}): OutputMask {\n  const { showOutput = false } = options\n\n  return {\n    verbose: showOutput,\n    outputBuffer: [],\n    isSpinning: !showOutput,\n  }\n}\n\n/**\n * Create a keyboard handler for toggling output visibility.\n * Handles two key combinations:\n * - ctrl+o: Toggle between showing and hiding output.\n * - ctrl+c: Cancel the running process.\n * The handler manipulates terminal state using ANSI escape sequences.\n */\nexport function createKeyboardHandler(\n  mask: OutputMask,\n  child: ChildProcess,\n  options: OutputMaskOptions = {},\n): (_str: string, key: readline.Key) => void {\n  const { message = 'Running\u2026', toggleText = 'to see full output' } = options\n\n  return (_str, key) => {\n    // ctrl+o toggles verbose mode.\n    if (key?.ctrl && key.name === 'o') {\n      mask.verbose = !mask.verbose\n\n      if (mask.verbose) {\n        // Stop spinner and show buffered output.\n        if (mask.isSpinning) {\n          spinner.stop()\n          mask.isSpinning = false\n        }\n\n        // Clear the current line (removes spinner remnants).\n        clearLine()\n\n        // Show buffered output.\n        if (mask.outputBuffer.length > 0) {\n          console.log('--- Output (ctrl+o to hide) ---')\n          mask.outputBuffer.forEach(line => {\n            write(line)\n          })\n        }\n      } else {\n        // Hide output and show spinner.\n        // Clear all the output lines that were shown.\n        if (mask.outputBuffer.length > 0) {\n          // Calculate number of lines to clear (output + header line).\n          const lineCount = mask.outputBuffer.join('').split('\\n').length + 1\n          // Move up and clear each line using ANSI escape sequences:\n          // - '\\x1b[1A' (CSI A): Move cursor up 1 line.\n          // - '\\x1b[2K' (CSI K with param 2): Erase entire line.\n          // This combination effectively \"rewinds\" the terminal output.\n          for (let i = 0; i < lineCount; i += 1) {\n            process.stdout.write('\\x1b[1A\\x1b[2K')\n          }\n        }\n        clearLine()\n\n        // Clear the buffer and restart spinner.\n        mask.outputBuffer = []\n        if (!mask.isSpinning) {\n          spinner.start(`${message} (ctrl+o ${toggleText})`)\n          mask.isSpinning = true\n        }\n      }\n    }\n    // ctrl+c to cancel.\n    else if (key?.ctrl && key.name === 'c') {\n      // Gracefully terminate child process.\n      child.kill('SIGTERM')\n      // Restore terminal to normal mode before exiting.\n      if (process.stdin.isTTY) {\n        process.stdin.setRawMode(false)\n      }\n      throw new Error('Process cancelled by user')\n    }\n  }\n}\n\n/**\n * Attach output masking to a child process.\n * Returns a promise that resolves with the exit code.\n * This function:\n * - Sets up keyboard input handling in raw mode for immediate key capture.\n * - Buffers stdout/stderr when not in verbose mode.\n * - Shows a spinner when output is masked.\n * - Allows toggling between masked and unmasked output with ctrl+o.\n */\nexport function attachOutputMask(\n  child: ChildProcess,\n  options: OutputMaskOptions = {},\n): Promise<number> {\n  return new Promise((resolve, reject) => {\n    const { message = 'Running\u2026' } = options\n    const mask = createOutputMask(options)\n\n    // Start spinner if not verbose.\n    if (mask.isSpinning && process.stdout.isTTY) {\n      spinner.start(\n        `${message} (ctrl+o ${options.toggleText || 'to see full output'})`,\n      )\n    }\n\n    // Setup keyboard input handling.\n    // Raw mode is required to capture ctrl+o without waiting for Enter.\n    if (process.stdin.isTTY) {\n      readline.emitKeypressEvents(process.stdin)\n      process.stdin.setRawMode(true)\n\n      const keypressHandler = createKeyboardHandler(mask, child, options)\n      process.stdin.on('keypress', keypressHandler)\n\n      // Cleanup on exit: restore terminal to normal mode.\n      child.on('exit', () => {\n        if (process.stdin.isTTY) {\n          process.stdin.setRawMode(false)\n          process.stdin.removeListener('keypress', keypressHandler)\n        }\n      })\n    }\n\n    // Handle stdout: either show immediately or buffer for later.\n    if (child.stdout) {\n      child.stdout.on('data', data => {\n        const text = data.toString()\n        if (mask.verbose) {\n          write(text)\n        } else {\n          // Buffer the output for later.\n          mask.outputBuffer.push(text)\n\n          // Keep buffer size reasonable (last 1000 lines).\n          // This prevents unbounded memory growth for long-running processes.\n          const lines = mask.outputBuffer.join('').split('\\n')\n          if (lines.length > 1000) {\n            mask.outputBuffer = [lines.slice(-1000).join('\\n')]\n          }\n        }\n        return undefined\n      })\n    }\n\n    // Handle stderr: same as stdout, but write to stderr stream when verbose.\n    if (child.stderr) {\n      child.stderr.on('data', data => {\n        const text = data.toString()\n        if (mask.verbose) {\n          process.stderr.write(text)\n        } else {\n          mask.outputBuffer.push(text)\n        }\n        return undefined\n      })\n    }\n\n    child.on('exit', code => {\n      // Cleanup keyboard if needed.\n      if (process.stdin.isTTY) {\n        process.stdin.setRawMode(false)\n      }\n\n      if (mask.isSpinning) {\n        if (code === 0) {\n          spinner.successAndStop(`${message} completed`)\n        } else {\n          spinner.failAndStop(`${message} failed`)\n          // Show buffered output on failure so user can see what went wrong.\n          if (mask.outputBuffer.length > 0 && !mask.verbose) {\n            console.log('\\n--- Output ---')\n            mask.outputBuffer.forEach(line => {\n              write(line)\n            })\n          }\n        }\n      }\n\n      resolve(code || 0)\n    })\n\n    child.on('error', error => {\n      // Ensure terminal is restored to normal mode on error.\n      if (process.stdin.isTTY) {\n        process.stdin.setRawMode(false)\n      }\n\n      if (mask.isSpinning) {\n        spinner.failAndStop(`${message} error`)\n      }\n      reject(error)\n    })\n  })\n}\n\n/**\n * Run a command with interactive output masking.\n * Convenience wrapper around spawn + attachOutputMask.\n * Spawns a child process and attaches the output masking system to it.\n * stdin is inherited, stdout and stderr are piped for masking control.\n */\nexport async function runWithMask(\n  command: string,\n  args: string[] = [],\n  options: OutputMaskOptions & SpawnOptions = {},\n): Promise<number> {\n  const {\n    message = 'Running\u2026',\n    showOutput = false,\n    toggleText = 'to see output',\n    ...spawnOptions\n  } = options\n\n  const child = spawn(command, args, {\n    stdio: ['inherit', 'pipe', 'pipe'],\n    ...spawnOptions,\n  })\n\n  return await attachOutputMask(child, { message, showOutput, toggleText })\n}\n"],
+  "mappings": "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",
+  "names": ["readline"]
+}

package/dist/stdio/progress.d.ts

@@ -0,0 +1,51 @@
+export interface ProgressBarOptions {
+    width?: number;
+    // Template: ':bar :percent :current/:total :eta'.
+    format?: string;
+    complete?: string;
+    incomplete?: string;
+    head?: string;
+    clear?: boolean;
+    renderThrottle?: number;
+    stream?: NodeJS.WriteStream;
+    color?: 'cyan' | 'green' | 'yellow' | 'blue' | 'magenta';
+}
+export declare class ProgressBar {
+    private current;
+    private total;
+    private startTime;
+    private lastRender;
+    private stream;
+    private options;
+    private terminated;
+    private lastDrawnWidth;
+    constructor(total: number, options?: ProgressBarOptions);
+    /**
+     * Update progress and redraw bar.
+     */
+    update(current: number, tokens?: Record<string, unknown>): void;
+    /**
+     * Increment progress by amount.
+     */
+    tick(amount?: number, tokens?: Record<string, unknown>): void;
+    /**
+     * Render the progress bar.
+     */
+    private render;
+    /**
+     * Clear the current line.
+     */
+    private clearLine;
+    /**
+     * Format time in seconds to human readable.
+     */
+    private formatTime;
+    /**
+     * Terminate the progress bar.
+     */
+    terminate(): void;
+}
+/**
+ * Create a simple progress indicator without a bar.
+ */
+export declare function createProgressIndicator(current: number, total: number, label?: string): string;