@mks2508/better-logger 0.18.2-alpha.1 → 0.18.2-alpha.2

package/dist/playground/TerminalBridge.d.ts

@@ -1,37 +1,41 @@
 /**
- * @fileoverview TerminalBridge — CLI terminal integration.
- * Encapsulates TTY detection, CLI primitive rendering, and server-mode
- * fallback for non-TTY environments.
+ * @fileoverview TerminalBridge — integración de terminal CLI.
+ * Encapsula detección de TTY, renderizado de primitivas CLI y fallback a
+ * server-mode para entornos non-TTY.
+ *
+ * @internal
  */
 import type { ISpinnerHandle, IBoxOptions, ITableOptions } from '../types/index.js';
 import { ServerFallback } from '../playground/server-fallback.js';
 import type { LoggerConfig } from '../types/index.js';
 import type { Logger } from '../Logger.js';
 /**
- * Bridge for CLI terminal operations.
+ * Bridge para operaciones de terminal CLI.
+ *
+ * @internal
  */
 export interface TerminalBridge {
-    /** Displays a step progress indicator. */
+    /** Muestra un indicador de progreso tipo step. */
     step(current: number, total: number, message: string): void;
-    /** Displays a styled header. */
+    /** Muestra un header con estilo. */
     header(title: string, subtitle?: string): void;
-    /** Displays a horizontal divider. */
+    /** Muestra un divider horizontal. */
     divider(): void;
-    /** Outputs a blank line. */
+    /** Emite una línea en blanco. */
     blank(): void;
-    /** Renders content inside a bordered box. */
+    /** Renderiza contenido dentro de un box con border. */
     box(content: string, options?: IBoxOptions): void;
-    /** Renders an array of objects as an ASCII table. */
+    /** Renderiza un array de objetos como tabla ASCII. */
     cliTable(rows: Record<string, unknown>[], options?: ITableOptions): void;
-    /** Creates a spinner handle. */
+    /** Crea un handle de spinner. */
     spinner(message: string): ISpinnerHandle;
-    /** Whether CLI primitives should be shown. */
+    /** Indica si las primitivas CLI deben mostrarse. */
     getShowPrimitives(): boolean;
-    /** Sets whether CLI primitives should be shown. */
+    /** Define si las primitivas CLI deben mostrarse. */
     setShowPrimitives(show: boolean): void;
-    /** Returns the server fallback instance (lazy). */
+    /** Devuelve la instancia del server fallback (lazy). */
     getServerFallback(): ServerFallback;
-    /** Returns true if running in a TTY. */
+    /** Devuelve `true` si se ejecuta en un TTY. */
     isInTerminal(): boolean;
 }
 interface ITerminalBridgeCtorOptions {
@@ -39,7 +43,10 @@ interface ITerminalBridgeCtorOptions {
     getLogger: () => Logger;
 }
 /**
- * Creates a TerminalBridge using a getter to avoid circular reference at construction.
+ * Crea un {@link TerminalBridge} usando un getter para evitar referencias
+ * circulares en la construcción.
+ *
+ * @internal
  */
 export declare function createTerminalBridge(options: ITerminalBridgeCtorOptions): TerminalBridge;
 export {};

package/dist/playground/TerminalBridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerminalBridge.d.ts","sourceRoot":"","sources":["../../src/playground/TerminalBridge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAe,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOjG,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,0CAA0C;IAC1C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5D,gCAAgC;IAChC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,qCAAqC;IACrC,OAAO,IAAI,IAAI,CAAC;IAChB,4BAA4B;IAC5B,KAAK,IAAI,IAAI,CAAC;IACd,6CAA6C;IAC7C,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAClD,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACzE,gCAAgC;IAChC,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC;IACzC,8CAA8C;IAC9C,iBAAiB,IAAI,OAAO,CAAC;IAC7B,mDAAmD;IACnD,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,mDAAmD;IACnD,iBAAiB,IAAI,cAAc,CAAC;IACpC,wCAAwC;IACxC,YAAY,IAAI,OAAO,CAAC;CAC3B;AAED,UAAU,0BAA0B;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,EAAE,MAAM,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,0BAA0B,GAAG,cAAc,CA8FxF"}
+{"version":3,"file":"TerminalBridge.d.ts","sourceRoot":"","sources":["../../src/playground/TerminalBridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAe,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOjG,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,kDAAkD;IAClD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5D,oCAAoC;IACpC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,qCAAqC;IACrC,OAAO,IAAI,IAAI,CAAC;IAChB,iCAAiC;IACjC,KAAK,IAAI,IAAI,CAAC;IACd,uDAAuD;IACvD,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAClD,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACzE,iCAAiC;IACjC,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC;IACzC,oDAAoD;IACpD,iBAAiB,IAAI,OAAO,CAAC;IAC7B,oDAAoD;IACpD,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,wDAAwD;IACxD,iBAAiB,IAAI,cAAc,CAAC;IACpC,+CAA+C;IAC/C,YAAY,IAAI,OAAO,CAAC;CAC3B;AAED,UAAU,0BAA0B;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,EAAE,MAAM,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,0BAA0B,GAAG,cAAc,CA8FxF"}

package/dist/playground/box.d.ts

@@ -4,11 +4,42 @@
 import type { IBoxOptions } from '../types/core.js';
 import type { ColorCapability } from '../terminal/color-converter.js';
 /**
- * Renders content inside a bordered box
- * @param content - Content string (may contain newlines)
- * @param options - Box rendering options
- * @param colorCap - Terminal color capability
- * @returns Formatted box string with border
+ * Renderiza `content` envuelto en un box con borde Unicode, respetando el
+ * ancho del terminal. El ancho interno se calcula a partir de la l\u00ednea m\u00e1s
+ * larga (o del {@link IBoxOptions.title} si es m\u00e1s ancho) y se acota a
+ * `min(terminalWidth - 4, 80)` columnas para no romper layouts estrechos.
+ *
+ * El padding se aplica como l\u00edneas vac\u00edas sim\u00e9tricas arriba/abajo del
+ * contenido. Si `borderColor` se omite o `colorCap` es `'none'`, el borde se
+ * emite sin secuencias ANSI (output plain-text seguro para logs y pipes).
+ *
+ * @param content - Texto a envolver; puede contener m\u00faltiples l\u00edneas (`\n`) y
+ *   secuencias ANSI embebidas \u2014 el c\u00e1lculo de ancho usa el largo visible.
+ * @param options - Configuraci\u00f3n del box (title, borderColor, borderStyle,
+ *   padding). Ver {@link IBoxOptions}.
+ * @param colorCap - Capacidad de color del terminal destino. Si es `'none'`,
+ *   se omite cualquier secuencia ANSI.
+ * @returns String multilinea con el box ya construido (sin trailing newline).
+ *
+ * @example
+ * ```ts
+ * // Box b\u00e1sico con borde redondeado (default)
+ * process.stdout.write(renderBox('Deploy completado') + '\n');
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Box con t\u00edtulo embebido en el borde superior y color custom
+ * process.stdout.write(renderBox('Service: auth-svc\nStatus: healthy', {
+ *   title: 'Health Check',
+ *   borderColor: '#00bcd4',
+ *   borderStyle: 'double',
+ *   padding: 1
+ * }) + '\n');
+ * ```
+ *
+ * @see {@link IBoxOptions} para el detalle de cada opci\u00f3n.
+ * @see {@link getTerminalWidth} para la detecci\u00f3n de ancho.
  */
 export declare function renderBox(content: string, options?: IBoxOptions, colorCap?: ColorCapability): string;
 //# sourceMappingURL=box.d.ts.map

package/dist/playground/box.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"box.d.ts","sourceRoot":"","sources":["../../src/playground/box.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAetE;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,EAAE,QAAQ,GAAE,eAAwB,GAAG,MAAM,CAyDhH"}
+{"version":3,"file":"box.d.ts","sourceRoot":"","sources":["../../src/playground/box.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAwBtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,EAAE,QAAQ,GAAE,eAAwB,GAAG,MAAM,CAyDhH"}

package/dist/playground/cli-table.d.ts

@@ -4,11 +4,47 @@
 import type { ITableOptions } from '../types/core.js';
 import type { ColorCapability } from '../terminal/color-converter.js';
 /**
- * Renders an array of objects as a formatted ASCII table
- * @param rows - Array of row objects
- * @param options - Table rendering options
- * @param colorCap - Terminal color capability
- * @returns Formatted table string
+ * Renderiza un array de objetos como tabla ASCII alineada, con headers en
+ * cian bold y separador (`─`) bajo la cabecera. Las columnas se autodetectan
+ * a partir de las keys del primer row salvo que `options.columns` las imponga,
+ * y los labels se toman de `options.head` (default: nombres de columna).
+ *
+ * El ancho de cada columna se calcula como `max(header, valor más largo) + 2`
+ * para garantizar padding horizontal consistente. Si `colorCap` es `'none'`,
+ * se omiten todas las secuencias ANSI (útil para logs plain-text o CI).
+ *
+ * @param rows - Array de row objects. Un array vacío devuelve string vacío.
+ * @param options - Ver {@link ITableOptions} para `columns` y `head`.
+ * @param colorCap - Capacidad de color del terminal destino.
+ * @returns String multilinea con la tabla (header + separator + data rows),
+ *   o `''` si `rows` está vacío.
+ *
+ * @example
+ * ```ts
+ * // Auto-detect columnas desde las keys del primer row
+ * const rows = [
+ *   { service: 'auth', status: 'healthy', latency: 12 },
+ *   { service: 'api',  status: 'degraded', latency: 245 }
+ * ];
+ * process.stdout.write(renderTable(rows) + '\n');
+ * // ┌─────────┬──────────┬─────────┐
+ * // │ service │ status   │ latency │
+ * // ─────────────────────────────────
+ * // │ auth    │ healthy  │ 12      │
+ * // │ api     │ degraded │ 245     │
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Forzar columnas y renombrar headers
+ * process.stdout.write(renderTable(rows, {
+ *   columns: ['service', 'latency'],
+ *   head:    ['Service', 'Latency (ms)']
+ * }, 'none') + '\n');
+ * ```
+ *
+ * @see {@link ITableOptions} para las opciones disponibles.
+ * @see {@link getVisibleLength} y {@link padToWidth} para el cálculo de ancho.
  */
 export declare function renderTable(rows: Record<string, unknown>[], options?: ITableOptions, colorCap?: ColorCapability): string;
 //# sourceMappingURL=cli-table.d.ts.map

package/dist/playground/cli-table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-table.d.ts","sourceRoot":"","sources":["../../src/playground/cli-table.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAItE;;;;;;GAMG;AACH,wBAAgB,WAAW,CACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,OAAO,GAAE,aAAkB,EAC3B,QAAQ,GAAE,eAAwB,GACnC,MAAM,CAwCR"}
+{"version":3,"file":"cli-table.d.ts","sourceRoot":"","sources":["../../src/playground/cli-table.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAItE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,WAAW,CACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,OAAO,GAAE,aAAkB,EAC3B,QAAQ,GAAE,eAAwB,GACnC,MAAM,CAwCR"}

package/dist/playground/divider.d.ts

@@ -2,9 +2,28 @@
  * @fileoverview Divider renderer for CLI primitives
  */
 /**
- * Renders a horizontal divider line
- * @param width - Optional explicit width (defaults to terminal width capped at 60)
- * @returns Formatted divider string
+ * Renderiza una línea divisoria horizontal dimmed (ANSI `2`) usando el
+ * caracter `─`. Por defecto el ancho es `min(terminalWidth - 4, 60)` para
+ * no ocupar todo el ancho de ventana y quedar visualmente alineado con otros
+ * primitives (box, header, table) que dejan 2 espacios de indentación.
+ *
+ * @param width - Ancho explícito en columnas visibles. Si se omite, se calcula
+ *   automáticamente a partir del ancho del terminal (capped a 60).
+ * @returns String de una línea con `width` caracteres `─` envueltos en ANSI dim.
+ *
+ * @example
+ * ```ts
+ * // Divider automático (respeta el ancho del terminal)
+ * process.stdout.write(renderDivider() + '\n');
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Divider de ancho fijo para alinear con otra salida
+ * process.stdout.write(renderDivider(40) + '\n');
+ * ```
+ *
+ * @see {@link getTerminalWidth} para la detección de ancho cuando `width` se omite.
  */
 export declare function renderDivider(width?: number): string;
 //# sourceMappingURL=divider.d.ts.map

package/dist/playground/divider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"divider.d.ts","sourceRoot":"","sources":["../../src/playground/divider.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpD"}
+{"version":3,"file":"divider.d.ts","sourceRoot":"","sources":["../../src/playground/divider.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpD"}

package/dist/playground/header.d.ts

@@ -2,10 +2,27 @@
  * @fileoverview Header renderer for CLI primitives
  */
 /**
- * Renders a styled header with optional subtitle
- * @param title - Main title text
- * @param subtitle - Optional subtitle (rendered dimmed)
- * @returns Formatted header string
+ * Renderiza un header de sección: `title` en bold seguido opcionalmente de
+ * `subtitle` en dim (ANSI `2`), ideal para marcar bloques en output de CLI.
+ * No usa colores de foreground — sólo atributos de texto, así que el renderer
+ * es seguro para cualquier terminal sin importar la paleta del theme activo.
+ *
+ * @param title - Texto principal del header (siempre en bold).
+ * @param subtitle - Texto secundario a la derecha del título; se renderiza
+ *   dimmed y separado por un espacio. Omitir si no aplica.
+ * @returns String de una línea con formato `  <bold>title</bold> <dim>subtitle</dim>`.
+ *
+ * @example
+ * ```ts
+ * process.stdout.write(renderHeader('Deploy', 'production · us-east-1') + '\n');
+ * //   **Deploy** production · us-east-1   (con atributos ANSI aplicados)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Header sin subtítulo
+ * process.stdout.write(renderHeader('Build summary') + '\n');
+ * ```
  */
 export declare function renderHeader(title: string, subtitle?: string): string;
 //# sourceMappingURL=header.d.ts.map

package/dist/playground/header.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../src/playground/header.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAIrE"}
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../src/playground/header.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAIrE"}

package/dist/playground/server-fallback.d.ts

@@ -1,27 +1,114 @@
 /**
- * @fileoverview Server/JSON fallback for CLI primitives in non-TTY environments
+ * @fileoverview Server/JSON fallback para CLI primitives en entornos non-TTY.
+ *
+ * Cuando el logger corre con `outputMode: 'json'` o fuera de una TTY real
+ * (CI logs, pipes, redirecciones), los primitives visuales — `step`,
+ * `header`, `box`, `cliTable` — no tienen sentido como arte ASCII.
+ * {@link ServerFallback} los degrada a llamadas `logger.info` / no-ops
+ * conservando el contenido semántico, para que el log siga siendo parseable
+ * línea por línea en aggregators centralizados.
+ *
+ * La factoría vive en `TerminalBridge.getServerFallback()` (lazy-singleton);
+ * los consumers no construyen esta clase directamente.
  */
 import type { IBoxOptions, ITableOptions } from '../types/core.js';
 import type { Logger } from '../Logger.js';
 /**
- * Server-mode fallback: outputs CLI primitives as plain logger calls
- * when not running in an interactive terminal.
+ * Degradación de CLI primitives para modo server/non-TTY.
+ *
+ * Cada método espeja uno del {@link TerminalBridge} (`step`/`header`/`box`/...)
+ * y decide cómo renderizarlo sin depender de caracteres de caja ni control
+ * ANSI: texto plano al logger, o no-op cuando no hay nada útil que emitir.
+ *
+ * @example
+ * ```ts
+ * // En CI (sin TTY), TerminalBridge enruta automáticamente aquí:
+ * logger.step(2, 5, 'Compilando');      // logger.info('[2/5] Compilando')
+ * logger.header('Build', 'v1.2.3');     // logger.info('Build v1.2.3')
+ * logger.divider();                     // (no-op)
+ * ```
  *
+ * @see {@link TerminalBridge} para el dispatcher TTY-vs-server.
  */
 export declare class ServerFallback {
     private logger;
+    /**
+     * @param {Logger} logger - Logger sobre el que se emiten los mensajes
+     *   degradados. Respeta el `outputMode` que tenga configurado (json,
+     *   console, ...), por lo que funciona tanto para logs estructurados
+     *   como para texto plano.
+     */
     constructor(logger: Logger);
-    /** Render step as plain info log */
+    /**
+     * Emite un step como `logger.info` con el contador `[current/total]`
+     * prefijado al mensaje. Conserva el orden y el progreso sin depender
+     * de caracteres de caja.
+     *
+     * @param {number} current - Índice del step actual (1-based).
+     * @param {number} total - Total de steps del run.
+     * @param {string} msg - Descripción del step.
+     * @returns {void}
+     */
     step(current: number, total: number, msg: string): void;
-    /** Render header as plain info log */
+    /**
+     * Emite el título (y subtítulo opcional) como `logger.info`. No pinta
+     * bordes ni separadores — en modo server solo interesa el texto.
+     *
+     * @param {string} title - Texto principal del header.
+     * @param {string} [subtitle] - Subtítulo optativo; se concatena con
+     *   espacio si viene.
+     * @returns {void}
+     */
     header(title: string, subtitle?: string): void;
-    /** Divider is a no-op in server mode */
+    /**
+     * No-op: un divisor visual (`───`) no aporta nada a un log server/JSON
+     * y solo ensuciaría el stream.
+     *
+     * @returns {void}
+     */
     divider(): void;
-    /** Blank line is a no-op in server mode */
+    /**
+     * No-op: las líneas en blanco rompen la consistencia de un log JSON
+     * (cada línea debería ser un registro parseable).
+     *
+     * @returns {void}
+     */
     blank(): void;
-    /** Render box content as plain info log */
+    /**
+     * Emite el contenido del box como `logger.info`, ignorando bordes y
+     * opciones de estilo (`title`, `borderColor`, ...). En modo server lo
+     * que importa es el payload, no el embalaje.
+     *
+     * @param {string} content - Texto a registrar.
+     * @param {IBoxOptions} [_options] - Opciones de box de la API TTY;
+     *   ignoradas en este fallback.
+     * @returns {void}
+     */
     box(content: string, _options?: IBoxOptions): void;
-    /** Render table rows as plain info logs */
+    /**
+     * Emite cada fila de la tabla como un `logger.info` con la fila
+     * serializada a JSON, en lugar de pintar una grilla ASCII.
+     *
+     * Cada fila queda como su propio registro JSON — útil para filtrar por
+     * columna en tools como `jq` o Loki. Las opciones de columnas/headers
+     * (`ITableOptions.columns` / `ITableOptions.head`) se ignoran: en modo
+     * server los keys del objeto son la fuente de verdad.
+     *
+     * @param {Record<string, unknown>[]} rows - Filas a emitir.
+     * @param {ITableOptions} [_options] - Opciones de tabla de la API TTY;
+     *   ignoradas en este fallback.
+     * @returns {void}
+     *
+     * @example
+     * ```ts
+     * serverFallback.cliTable([
+     *   { user: 'alice', age: 30 },
+     *   { user: 'bob',   age: 25 }
+     * ]);
+     * // logger.info('{"user":"alice","age":30}')
+     * // logger.info('{"user":"bob","age":25}')
+     * ```
+     */
     cliTable(rows: Record<string, unknown>[], _options?: ITableOptions): void;
 }
 //# sourceMappingURL=server-fallback.d.ts.map

package/dist/playground/server-fallback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-fallback.d.ts","sourceRoot":"","sources":["../../src/playground/server-fallback.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,MAAM;IAI1B,oCAAoC;IACpC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAIvD,sCAAsC;IACtC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAK9C,wCAAwC;IACxC,OAAO,IAAI,IAAI;IAIf,2CAA2C;IAC3C,KAAK,IAAI,IAAI;IAIb,2CAA2C;IAC3C,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI;IAIlD,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,IAAI;CAK5E"}
+{"version":3,"file":"server-fallback.d.ts","sourceRoot":"","sources":["../../src/playground/server-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;OAKG;gBACS,MAAM,EAAE,MAAM;IAI1B;;;;;;;;;OASG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAIvD;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAK9C;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAIf;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;;;;OASG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI;IAIlD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,IAAI;CAK5E"}

package/dist/playground/spinner.d.ts

@@ -1,48 +1,197 @@
 /**
- * @fileoverview Built-in spinner implementation for CLI primitives
+ * @fileoverview Built-in spinner implementation for CLI primitives.
+ *
+ * Expone dos implementaciones de {@link ISpinnerHandle}:
+ *   - {@link SpinnerManager}: spinner braille animado para TTY interactiva.
+ *   - {@link NoopSpinner}: fallback sin animaci\u00f3n para non-TTY / silent mode.
+ *
+ * La factor\u00eda que decide cu\u00e1l instanciar vive en `TerminalBridge.spinner()`;
+ * los consumers rara vez construyen estas clases directamente.
  */
 import type { ISpinnerHandle, LoggerConfig } from '../types/core.js';
 import type { Logger } from '../Logger.js';
 /**
- * Interactive terminal spinner with in-place line updates.
- * Writes to stderr to avoid polluting piped stdout.
+ * Spinner interactivo para TTY: cicla frames braille reescribiendo la l\u00ednea
+ * actual en su sitio (no emite l\u00edneas nuevas hasta el stop).
+ *
+ * Para no poluir stdout piped ni entrelazarse con el output normal del
+ * {@link Logger}, hace dos cosas no obvias:
+ *   1. Escribe SIEMPRE a `process.stderr` (carriage return + `\x1b[K` para
+ *      limpiar la l\u00ednea antes de cada render).
+ *   2. Con `start()` mutea el logger (`outputMode: 'silent'`) y lo restaura a
+ *      `'console'` en cualquier m\u00e9todo de finalizaci\u00f3n (`stop`/`succeed`/`fail`).
+ *      Sin esto, los logs del usuario se imprimir\u00edan encima del frame animado.
+ *
+ * No gestiona TTY detection \u2014 quien lo instancia (`TerminalBridge`) ya valid\u00f3
+ * que hay TTY. Para non-TTY ver {@link NoopSpinner}.
  *
  * @implements {ISpinnerHandle}
+ *
+ * @example
+ * ```ts
+ * const spinner = new SpinnerManager('Compilando...', logger.config, logger);
+ * spinner.start();
+ * // ...trabajo as\u00edncrono...
+ * spinner.succeed('Build OK');
+ * // stderr: "  \u2713 Build OK"
+ * ```
+ *
+ * @see {@link NoopSpinner} para el path non-TTY.
+ * @see {@link ISpinnerHandle} para el contrato de la API p\u00fablica.
  */
 export declare class SpinnerManager implements ISpinnerHandle {
     private message;
     private frameIndex;
     private interval;
     private _logger;
+    /**
+     * @param {string} message - Texto a mostrar al lado del frame animado.
+     *   Mutables luego v\u00eda {@link SpinnerManager.text}.
+     * @param {LoggerConfig} _config - Reservado para configuraci\u00f3n futura;
+     *   actualmente no se lee dentro de la clase (lo conserva solo el caller).
+     * @param {Logger} logger - Instancia del logger due\u00f1a del spinner. Se
+     *   mutea/restaura con `updateConfig({ outputMode })` en start/stop.
+     */
     constructor(message: string, _config: LoggerConfig, logger: Logger);
-    /** Start the spinner animation */
+    /**
+     * Arranca la animaci\u00f3n. Idempotente: si ya est\u00e1 corriendo, no hace nada.
+     *
+     * Como efecto lateral mutea el logger pasado al constructor cambiando su
+     * `outputMode` a `'silent'` \u2014 cualquier log durante la animaci\u00f3n quedar\u00eda
+     * bufferizado y se descarta al restaurar el modo. Llama siempre a
+     * {@link stop}, {@link succeed} o {@link fail} para restaurar el output.
+     *
+     * @returns {void}
+     */
     start(): void;
-    /** Stop the spinner without a status message */
+    /**
+     * Detiene la animaci\u00f3n y limpia la l\u00ednea, sin emitir mensaje de estado.
+     * Restaura el `outputMode` del logger a `'console'`.
+     *
+     * \u00datil cuando el caller ya emiti\u00f3 su propio output final y solo necesita
+     * desmontar el spinner. Para terminaci\u00f3n con tick/cross usa
+     * {@link succeed} / {@link fail}.
+     *
+     * @returns {void}
+     */
     stop(): void;
-    /** Stop with a success indicator */
+    /**
+     * Detiene la animaci\u00f3n y emite el mensaje con un check verde (`\u2713`).
+     * Restaura el `outputMode` del logger a `'console'`.
+     *
+     * @param {string} [msg] - Texto final a mostrar. Si se omite, reutiliza
+     *   el `message` con el que se construy\u00f3 el spinner (o el \u00faltimo seteado
+     *   v\u00eda {@link text}).
+     * @returns {void}
+     *
+     * @example
+     * ```ts
+     * spinner.succeed();           // \u2192 "  \u2713 <message inicial>"
+     * spinner.succeed('Hecho');    // \u2192 "  \u2713 Hecho"
+     * ```
+     */
     succeed(msg?: string): void;
-    /** Stop with a failure indicator */
+    /**
+     * Detiene la animaci\u00f3n y emite el mensaje con una cruz roja (`\u2717`).
+     * Restaura el `outputMode` del logger a `'console'`.
+     *
+     * @param {string} [msg] - Texto final a mostrar. Si se omite, reutiliza
+     *   el `message` con el que se construy\u00f3 el spinner (o el \u00faltimo seteado
+     *   v\u00eda {@link text}).
+     * @returns {void}
+     *
+     * @example
+     * ```ts
+     * try {
+     *   await build();
+     *   spinner.succeed('Build OK');
+     * } catch (e) {
+     *   spinner.fail(`Build fallido: ${e.message}`);
+     * }
+     * ```
+     */
     fail(msg?: string): void;
-    /** Update the spinner text while running */
+    /**
+     * Reemplaza el texto mostrado al lado del frame sin reiniciar la animaci\u00f3n
+     * ni perder el frame actual. Pensado para actualizar progreso in-place
+     * (p.ej. contador de items procesados).
+     *
+     * @param {string} msg - Nuevo texto a mostrar.
+     * @returns {void}
+     */
     text(msg: string): void;
     private render;
     private clearLine;
     private clearInterval;
 }
 /**
- * No-op spinner for non-TTY environments or silent mode.
- * Logs start/succeed/fail as plain log messages.
+ * Spinner degenerate para non-TTY (CI logs, pipes, `outputMode: 'silent'`).
+ *
+ * No anima nada: traduce los eventos del ciclo de vida del spinner a llamadas
+ * normales del logger (`info` en start, `success`/`error` en finish). Así el
+ * consumidor mantiene la misma API {@link ISpinnerHandle} sin saber si está
+ * corriendo en terminal interactiva o en un job de CI.
+ *
+ * A diferencia de {@link SpinnerManager}, **no** toca el `outputMode` del
+ * logger — no hay nada que mutear porque no hay frame animado que proteger.
  *
  * @implements {ISpinnerHandle}
+ *
+ * @example
+ * ```ts
+ * // En CI (sin TTY) el TerminalBridge entrega un NoopSpinner automáticamente:
+ * const s = logger.spinner('Running tests...');
+ * s.start();                 // logger.info('Running tests...')
+ * s.succeed('All green');    // logger.success('All green')
+ * ```
+ *
+ * @see {@link SpinnerManager} para el path interactivo con animación.
  */
 export declare class NoopSpinner implements ISpinnerHandle {
     private message;
     private _logger;
+    /**
+     * @param {string} message - Texto base; se reutiliza como mensaje final
+     *   si {@link succeed} / {@link fail} se llaman sin argumento.
+     * @param {Logger} logger - Logger sobre el que se emiten los eventos.
+     */
     constructor(message: string, logger: Logger);
+    /**
+     * Emite el mensaje inicial como `logger.info(...)`. No arranca ningún
+     * timer — en non-TTY no hay nada que animar.
+     *
+     * @returns {void}
+     */
     start(): void;
+    /**
+     * No-op — no hay animación que detener ni output que restaurar.
+     *
+     * @returns {void}
+     */
     stop(): void;
+    /**
+     * Emite el mensaje final como `logger.success(...)`.
+     *
+     * @param {string} [msg] - Texto final; si se omite usa el `message`
+     *   inicial o el último seteado vía {@link text}.
+     * @returns {void}
+     */
     succeed(msg?: string): void;
+    /**
+     * Emite el mensaje final como `logger.error(...)`.
+     *
+     * @param {string} [msg] - Texto final; si se omite usa el `message`
+     *   inicial o el último seteado vía {@link text}.
+     * @returns {void}
+     */
     fail(msg?: string): void;
+    /**
+     * Actualiza el mensaje interno (sin output). Solo afecta al texto que
+     * emitirán {@link succeed} / {@link fail} cuando se invoquen sin argumento.
+     *
+     * @param {string} msg - Nuevo texto base.
+     * @returns {void}
+     */
     text(msg: string): void;
 }
 //# sourceMappingURL=spinner.d.ts.map

package/dist/playground/spinner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../src/playground/spinner.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAS3C;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,cAAc;IACjD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM;IAKlE,kCAAkC;IAClC,KAAK,IAAI,IAAI;IAcb,gDAAgD;IAChD,IAAI,IAAI,IAAI;IAOZ,oCAAoC;IACpC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ3B,oCAAoC;IACpC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAQxB,4CAA4C;IAC5C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIvB,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,aAAa;CAMxB;AAED;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,cAAc;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK3C,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI;IAIZ,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAI3B,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAIxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAG1B"}
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../src/playground/spinner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAkB3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,cAAe,YAAW,cAAc;IACjD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;;OAOG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM;IAKlE;;;;;;;;;OASG;IACH,KAAK,IAAI,IAAI;IAcb;;;;;;;;;OASG;IACH,IAAI,IAAI,IAAI;IAOZ;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAQxB;;;;;;;OAOG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIvB,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,aAAa;CAMxB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,WAAY,YAAW,cAAc;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IAExB;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK3C;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAIZ;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAI3B;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAG1B"}