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

package/dist/playground/TerminalBridge.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @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 para operaciones de terminal CLI.
+ *
+ * @internal
+ */
+export interface TerminalBridge {
+    /** Muestra un indicador de progreso tipo step. */
+    step(current: number, total: number, message: string): void;
+    /** Muestra un header con estilo. */
+    header(title: string, subtitle?: string): void;
+    /** Muestra un divider horizontal. */
+    divider(): void;
+    /** Emite una línea en blanco. */
+    blank(): void;
+    /** Renderiza contenido dentro de un box con border. */
+    box(content: string, options?: IBoxOptions): void;
+    /** Renderiza un array de objetos como tabla ASCII. */
+    cliTable(rows: Record<string, unknown>[], options?: ITableOptions): void;
+    /** Crea un handle de spinner. */
+    spinner(message: string): ISpinnerHandle;
+    /** Indica si las primitivas CLI deben mostrarse. */
+    getShowPrimitives(): boolean;
+    /** Define si las primitivas CLI deben mostrarse. */
+    setShowPrimitives(show: boolean): void;
+    /** Devuelve la instancia del server fallback (lazy). */
+    getServerFallback(): ServerFallback;
+    /** Devuelve `true` si se ejecuta en un TTY. */
+    isInTerminal(): boolean;
+}
+interface ITerminalBridgeCtorOptions {
+    config: LoggerConfig;
+    getLogger: () => Logger;
+}
+/**
+ * Crea un {@link TerminalBridge} usando un getter para evitar referencias
+ * circulares en la construcción.
+ *
+ * @internal
+ */
+export declare function createTerminalBridge(options: ITerminalBridgeCtorOptions): TerminalBridge;
+export {};
+//# sourceMappingURL=TerminalBridge.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Box renderer for CLI primitives
+ */
+import type { IBoxOptions } from '../types/core.js';
+import type { ColorCapability } from '../terminal/color-converter.js';
+/**
+ * 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

@@ -0,0 +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;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

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview CLI table renderer for CLI primitives
+ */
+import type { ITableOptions } from '../types/core.js';
+import type { ColorCapability } from '../terminal/color-converter.js';
+/**
+ * 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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Divider renderer for CLI primitives
+ */
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Header renderer for CLI primitives
+ */
+/**
+ * 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

@@ -0,0 +1 @@
+{"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/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Playground subpath barrel — visual CLI helpers.
+ * Raw rendering functions used by TerminalBridge.
+ */
+export { renderBox } from './box.js';
+export { renderTable } from './cli-table.js';
+export { renderStep } from './step.js';
+export { SpinnerManager, NoopSpinner } from './spinner.js';
+export { renderHeader } from './header.js';
+export { renderDivider } from './divider.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/playground/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,114 @@
+/**
+ * @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';
+/**
+ * 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);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * No-op: un divisor visual (`───`) no aporta nada a un log server/JSON
+     * y solo ensuciaría el stream.
+     *
+     * @returns {void}
+     */
+    divider(): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,197 @@
+/**
+ * @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';
+/**
+ * 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);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}
+/**
+ * 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

@@ -0,0 +1 @@
+{"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"}

package/dist/playground/step.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Step progress renderer for CLI primitives
+ */
+import { type ColorCapability } from '../terminal/color-converter.js';
+/**
+ * Renderiza un indicador de progreso de step con el formato `  [n/total] msg`,
+ * donde el `[n/total]` se emite en cian bold (respetando `colorCap`) para
+ * destacarlo del mensaje descriptivo. Pensado para output secuencial de CLI
+ * tipo "steps de un build", "fases de un deploy" o "tareas de un script".
+ *
+ * No hace ningún chequeo de rango sobre `current`/`total` — el caller es
+ * responsable de pasar valores coherentes (se renderizan tal cual).
+ *
+ * @param current - Número de step actual (típicamente 1-based).
+ * @param total - Total de steps del proceso.
+ * @param msg - Descripción corta del step en curso.
+ * @param colorCap - Capacidad de color del terminal destino. Si es `'none'`,
+ *   el label `[n/total]` se emite sin color.
+ * @returns String de una sola línea con formato `  [n/total] msg`.
+ *
+ * @example
+ * ```ts
+ * const steps = ['Resolving deps', 'Bundling', 'Writing dist'];
+ * steps.forEach((step, i) => {
+ *   process.stdout.write(renderStep(i + 1, steps.length, step, 'full') + '\n');
+ * });
+ * //   [1/3] Resolving deps
+ * //   [2/3] Bundling
+ * //   [3/3] Writing dist
+ * ```
+ */
+export declare function renderStep(current: number, total: number, msg: string, colorCap: ColorCapability): string;
+//# sourceMappingURL=step.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/playground/step.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,MAAM,CAMzG"}

package/dist/playground-module.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Entry point for ./playground subpath.
+ * Visual CLI helpers: box, table, steps, spinner rendering functions.
+ */
+export { renderBox } from './playground/index.js';
+export { renderTable } from './playground/index.js';
+export { renderStep } from './playground/index.js';
+export { SpinnerManager, NoopSpinner } from './playground/index.js';
+export { renderHeader } from './playground/index.js';
+export { renderDivider } from './playground/index.js';
+//# sourceMappingURL=playground-module.d.ts.map

package/dist/playground-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playground-module.d.ts","sourceRoot":"","sources":["../src/playground-module.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/playground.cjs

@@ -0,0 +1,9 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_spinner = require("./chunks/spinner-BHyYEXsM.cjs");
+exports.NoopSpinner = require_spinner.NoopSpinner;
+exports.SpinnerManager = require_spinner.SpinnerManager;
+exports.renderBox = require_spinner.renderBox;
+exports.renderDivider = require_spinner.renderDivider;
+exports.renderHeader = require_spinner.renderHeader;
+exports.renderStep = require_spinner.renderStep;
+exports.renderTable = require_spinner.renderTable;

package/dist/playground.js

@@ -0,0 +1,2 @@
+import { a as renderDivider, i as renderBox, n as SpinnerManager, o as renderHeader, r as renderTable, s as renderStep, t as NoopSpinner } from "./chunks/spinner-BtkwpzYv.js";
+export { NoopSpinner, SpinnerManager, renderBox, renderDivider, renderHeader, renderStep, renderTable };