@mks2508/better-logger 4.0.0 → 5.0.1

package/playground/demo-table.ts

@@ -0,0 +1,83 @@
+/**
+ * CLI table — various column counts, auto-width, explicit columns.
+ * Run: bun playground/demo-table.ts
+ */
+import { Logger } from '../src/Logger.js';
+
+const logger = new Logger();
+
+function main() {
+    logger.header('Table Demos');
+    logger.divider();
+    logger.blank();
+
+    // ── Auto-detect columns from data ─────────────────
+    logger.info('1. Auto-detected columns');
+    logger.blank();
+
+    logger.cliTable([
+        { name: 'Gemini SDK', version: '1.0.0', status: 'active' },
+        { name: 'Groq SDK', version: '0.8.2', status: 'active' },
+        { name: 'OpenRouter', version: '2.1.0', status: 'fallback' },
+    ]);
+    logger.blank();
+
+    // ── Explicit columns via options ──────────────────
+    logger.info('2. Explicit columns (subset)');
+    logger.blank();
+
+    logger.cliTable(
+        [
+            { id: 1, name: 'Alice', email: 'alice@example.com', role: 'admin' },
+            { id: 2, name: 'Bob', email: 'bob@example.com', role: 'user' },
+            { id: 3, name: 'Charlie', email: 'charlie@example.com', role: 'user' },
+        ],
+        { columns: ['name', 'role'] },
+    );
+    logger.blank();
+
+    // ── Various value lengths ─────────────────────────
+    logger.info('3. Mixed value lengths');
+    logger.blank();
+
+    logger.cliTable([
+        { key: 'a', value: 'short' },
+        { key: 'longer-key-name', value: 'This is a much longer value to test column sizing' },
+        { key: 'b', value: '42' },
+    ]);
+    logger.blank();
+
+    // ── Numeric and boolean values ────────────────────
+    logger.info('4. Numeric and boolean values');
+    logger.blank();
+
+    logger.cliTable([
+        { metric: 'Requests/sec', value: 12500, healthy: true },
+        { metric: 'Avg latency', value: 23.4, healthy: true },
+        { metric: 'Error rate', value: 0.02, healthy: true },
+        { metric: 'Memory (MB)', value: 512, healthy: false },
+    ]);
+    logger.blank();
+
+    // ── Many columns ──────────────────────────────────
+    logger.info('5. Many columns');
+    logger.blank();
+
+    logger.cliTable([
+        { col1: 'A', col2: 'B', col3: 'C', col4: 'D', col5: 'E', col6: 'F' },
+        { col1: '1', col2: '2', col3: '3', col4: '4', col5: '5', col6: '6' },
+    ]);
+    logger.blank();
+
+    // ── Single row ────────────────────────────────────
+    logger.info('6. Single row');
+    logger.blank();
+
+    logger.cliTable([{ provider: 'Gemini SDK', model: 'gemini-2.5-flash', latency: '120ms' }]);
+    logger.blank();
+
+    logger.divider();
+    logger.info('Table demos complete.');
+}
+
+main();

package/src/Logger.ts

@@ -36,7 +36,7 @@ import { TransportManager } from './transports/index.js';
 import { parseStackTrace } from './utils/stackTrace.js';
 import { formatTimestamp } from './utils/timestamps.js';
 import { createStyledOutput, setupThemeChangeListener } from './utils/output.js';
-import { getEnvironment, getColorCapability } from './utils/environment-detector.js';
+import { getEnvironment, getColorCapability, isRunningInTerminal } from './utils/environment-detector.js';
 import { formatBadge } from './terminal/formatter.js';
 
 // Styling imports
@@ -62,7 +62,17 @@ import { ExportLogHandler } from './handlers/index.js';
 import { createDefaultCLI, type CommandProcessor } from './cli/index.js';
 
 // Constants
-import { DEFAULT_CONFIG } from './constants.js';
+import { DEFAULT_CONFIG, CLI_LEVEL_MAP } from './constants.js';
+
+// CLI Primitives
+import type { CLILogLevel, ISpinnerHandle, IBoxOptions, ITableOptions } from './types/index.js';
+import { renderStep } from './cli-primitives/step.js';
+import { renderHeader } from './cli-primitives/header.js';
+import { renderDivider } from './cli-primitives/divider.js';
+import { renderBox } from './cli-primitives/box.js';
+import { renderTable } from './cli-primitives/cli-table.js';
+import { SpinnerManager, NoopSpinner } from './cli-primitives/spinner.js';
+import { ServerFallback } from './cli-primitives/server-fallback.js';
 
 /**
  * Estilos del tema activo actual
@@ -116,6 +126,11 @@ export class Logger {
     private hookManager: HookManager;
     private transportManager?: TransportManager;
 
+    /** Whether CLI primitives (step, box, header, etc.) should be shown @since 5.0.0 */
+    private _showPrimitives = true;
+    /** Server-mode fallback for non-TTY environments @since 5.0.0 */
+    private _serverFallback?: ServerFallback;
+
     /**
      * Crea una nueva instancia del Logger
      * 
@@ -1292,21 +1307,22 @@ export class Logger {
 
     /**
      * Finaliza un temporizador y muestra el tiempo transcurrido
-     * 
+     *
      * @param {string} label - Etiqueta del temporizador a finalizar
-     * 
+     * @returns {number} Elapsed milliseconds, or -1 if timer not found
+     *
      * @example
      * logger.time('consulta-db');
      * await consultarBaseDatos();
-     * logger.timeEnd('consulta-db'); // ⏱️ Timer ended: consulta-db - 234.56ms
-     * 
+     * const elapsed = logger.timeEnd('consulta-db'); // ⏱️ Timer ended: consulta-db - 234.56ms
+     *
      * @since 0.3.0
      */
-    timeEnd(label: string): void {
+    timeEnd(label: string): number {
         const timer = this.timers.get(label);
         if (!timer) {
             this.warn(`Timer '${label}' does not exist`);
-            return;
+            return -1;
         }
 
         const elapsed = performance.now() - timer.startTime;
@@ -1314,6 +1330,8 @@ export class Logger {
 
         const timerStyle = StylePresets.success().build();
         console.log(`%c⏱️ Timer ended: ${label} - ${elapsed.toFixed(2)}ms`, timerStyle);
+
+        return elapsed;
     }
 
     // ===== ADVANCED VISUAL FEATURES =====
@@ -1462,6 +1480,193 @@ export class Logger {
         }
     }
 
+    // ===== CLI PRIMITIVES (v5.0) =====
+
+    /**
+     * Displays a step progress indicator in the terminal
+     *
+     * @param {number} current - Current step number
+     * @param {number} total - Total number of steps
+     * @param {string} message - Step description
+     *
+     * @example
+     * logger.step(1, 5, 'Analyzing repository...');
+     * logger.step(2, 5, 'Generating commit message...');
+     *
+     * @since 5.0.0
+     */
+    step(current: number, total: number, message: string): void {
+        if (!this._showPrimitives) return;
+        if (!isRunningInTerminal()) {
+            this.getServerFallback().step(current, total, message);
+            return;
+        }
+        const colorCap = getColorCapability();
+        const output = renderStep(current, total, message, colorCap);
+        process.stderr.write(output + '\n');
+    }
+
+    /**
+     * Displays a styled header with optional subtitle
+     *
+     * @param {string} title - Main title text
+     * @param {string} subtitle - Optional subtitle (rendered dimmed)
+     *
+     * @example
+     * logger.header('Commit Wizard', 'v2.0.0');
+     *
+     * @since 5.0.0
+     */
+    header(title: string, subtitle?: string): void {
+        if (!this._showPrimitives) return;
+        if (!isRunningInTerminal()) {
+            this.getServerFallback().header(title, subtitle);
+            return;
+        }
+        const output = renderHeader(title, subtitle);
+        process.stderr.write(output + '\n');
+    }
+
+    /**
+     * Displays a horizontal divider line
+     *
+     * @example
+     * logger.divider();
+     *
+     * @since 5.0.0
+     */
+    divider(): void {
+        if (!this._showPrimitives) return;
+        if (!isRunningInTerminal()) {
+            this.getServerFallback().divider();
+            return;
+        }
+        const output = renderDivider();
+        process.stderr.write(output + '\n');
+    }
+
+    /**
+     * Outputs a blank line
+     *
+     * @example
+     * logger.blank();
+     *
+     * @since 5.0.0
+     */
+    blank(): void {
+        if (!this._showPrimitives) return;
+        if (!isRunningInTerminal()) {
+            this.getServerFallback().blank();
+            return;
+        }
+        process.stderr.write('\n');
+    }
+
+    /**
+     * Renders content inside a bordered box
+     *
+     * @param {string} content - Content string (may contain newlines)
+     * @param {IBoxOptions} options - Box rendering options
+     *
+     * @example
+     * logger.box('3 commits generated\nProvider: Groq', { title: 'Done', borderColor: '#00ff00' });
+     *
+     * @since 5.0.0
+     */
+    box(content: string, options?: IBoxOptions): void {
+        if (!this._showPrimitives) return;
+        if (!isRunningInTerminal()) {
+            this.getServerFallback().box(content, options);
+            return;
+        }
+        const colorCap = getColorCapability();
+        const output = renderBox(content, options, colorCap);
+        process.stderr.write(output + '\n');
+    }
+
+    /**
+     * Renders an array of objects as a formatted ASCII table.
+     * Note: This is distinct from the existing table() method which uses console.table.
+     *
+     * @param {Record<string, unknown>[]} rows - Array of row objects
+     * @param {ITableOptions} options - Table rendering options
+     *
+     * @example
+     * logger.cliTable([
+     *   { provider: 'Groq', status: 'Available', model: 'llama-3.3-70b' },
+     *   { provider: 'Gemini', status: 'Configured', model: 'gemini-2.5-flash' },
+     * ]);
+     *
+     * @since 5.0.0
+     */
+    cliTable(rows: Record<string, unknown>[], options?: ITableOptions): void {
+        if (!this._showPrimitives) return;
+        if (!isRunningInTerminal()) {
+            this.getServerFallback().cliTable(rows, options);
+            return;
+        }
+        const colorCap = getColorCapability();
+        const output = renderTable(rows, options, colorCap);
+        process.stderr.write(output + '\n');
+    }
+
+    /**
+     * Creates a spinner handle for showing progress during async operations.
+     * Returns a NoopSpinner in non-TTY environments.
+     *
+     * @param {string} message - Initial spinner text
+     * @returns {ISpinnerHandle} Spinner controller
+     *
+     * @example
+     * const s = logger.spinner('Analyzing repository...');
+     * s.start();
+     * await analyzeRepo();
+     * s.succeed('Analysis complete (1.2s)');
+     *
+     * @since 5.0.0
+     */
+    spinner(message: string): ISpinnerHandle {
+        if (!isRunningInTerminal() || this.config.outputMode === 'silent') {
+            return new NoopSpinner(message, this);
+        }
+        return new SpinnerManager(message, this.config, this);
+    }
+
+    /**
+     * Sets the CLI verbosity level, controlling both log verbosity and primitive visibility
+     *
+     * @param {CLILogLevel} level - CLI log level
+     *
+     * @example
+     * logger.setCLILevel('quiet');   // Only errors, no CLI primitives
+     * logger.setCLILevel('verbose'); // Debug logs + all CLI primitives
+     *
+     * @since 5.0.0
+     */
+    setCLILevel(level: CLILogLevel): void {
+        const mapping = CLI_LEVEL_MAP[level];
+        this.setVerbosity(mapping.verbosity);
+        this._showPrimitives = mapping.showPrimitives;
+        this.config.cliLevel = level;
+    }
+
+    /**
+     * Returns the current CLI log level
+     * @returns {CLILogLevel} Current CLI log level
+     * @since 5.0.0
+     */
+    get cliLevel(): CLILogLevel {
+        return this.config.cliLevel ?? 'normal';
+    }
+
+    /** Lazily creates the server fallback instance @private */
+    private getServerFallback(): ServerFallback {
+        if (!this._serverFallback) {
+            this._serverFallback = new ServerFallback(this);
+        }
+        return this._serverFallback;
+    }
+
     // ===== OUTPUT WRITER SYSTEM =====
 
     /**

package/src/ScopedLogger.ts

@@ -1,5 +1,5 @@
 import { Logger } from './Logger.js';
-import type { TimerEntry, Bindings } from './types/index.js';
+import type { TimerEntry, Bindings, ISpinnerHandle, IBoxOptions, ITableOptions, CLILogLevel } from './types/index.js';
 
 export class ScopedLogger {
     private readonly parent: Logger;
@@ -105,6 +105,48 @@ export class ScopedLogger {
         console.trace(`[${this.scopeName}]`);
     }
 
+    // ===== CLI PRIMITIVES (v5.0 delegation) =====
+
+    /** @see Logger.step */
+    step(current: number, total: number, message: string): void {
+        this.parent.step(current, total, message);
+    }
+
+    /** @see Logger.header */
+    header(title: string, subtitle?: string): void {
+        this.parent.header(title, subtitle);
+    }
+
+    /** @see Logger.divider */
+    divider(): void {
+        this.parent.divider();
+    }
+
+    /** @see Logger.blank */
+    blank(): void {
+        this.parent.blank();
+    }
+
+    /** @see Logger.box */
+    box(content: string, options?: IBoxOptions): void {
+        this.parent.box(content, options);
+    }
+
+    /** @see Logger.cliTable */
+    cliTable(rows: Record<string, unknown>[], options?: ITableOptions): void {
+        this.parent.cliTable(rows, options);
+    }
+
+    /** @see Logger.spinner */
+    spinner(message: string): ISpinnerHandle {
+        return this.parent.spinner(message);
+    }
+
+    /** @see Logger.setCLILevel */
+    setCLILevel(level: CLILogLevel): void {
+        this.parent.setCLILevel(level);
+    }
+
     _pushContext(context: string): void {
         this.contextStack.push(context);
     }

package/src/cli-module.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview CLI-only entry point for @mks2508/better-logger/cli
+ * Exports only CLI primitives for minimal bundle size in CLI tools.
+ * @version 5.0.0
+ * @since 5.0.0
+ */
+
+export { renderStep } from './cli-primitives/step.js';
+export { renderHeader } from './cli-primitives/header.js';
+export { renderDivider } from './cli-primitives/divider.js';
+export { renderBox } from './cli-primitives/box.js';
+export { renderTable } from './cli-primitives/cli-table.js';
+export { SpinnerManager, NoopSpinner } from './cli-primitives/spinner.js';
+export { ServerFallback } from './cli-primitives/server-fallback.js';
+
+export type {
+    CLILogLevel,
+    ISpinnerHandle,
+    IBoxOptions,
+    ITableOptions,
+} from './types/index.js';

package/src/cli-primitives/box.ts

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Box renderer for CLI primitives
+ * @since 5.0.0
+ */
+
+import type { IBoxOptions } from '../types/core.js';
+import type { ColorCapability } from '../terminal/color-converter.js';
+import { getANSIForeground, ANSI } from '../terminal/color-converter.js';
+import { getTerminalWidth } from '../utils/environment-detector.js';
+import { stripAnsi, getVisibleLength } from '../terminal/formatter.js';
+
+/**
+ * Border character sets for different styles
+ */
+const BORDER_CHARS = {
+    single:  { tl: '\u250c', tr: '\u2510', bl: '\u2514', br: '\u2518', h: '\u2500', v: '\u2502' },
+    rounded: { tl: '\u256d', tr: '\u256e', bl: '\u2570', br: '\u256f', h: '\u2500', v: '\u2502' },
+    double:  { tl: '\u2554', tr: '\u2557', bl: '\u255a', br: '\u255d', h: '\u2550', v: '\u2551' },
+    bold:    { tl: '\u250f', tr: '\u2513', bl: '\u2517', br: '\u251b', h: '\u2501', v: '\u2503' },
+} as const;
+
+/**
+ * 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
+ */
+export function renderBox(content: string, options: IBoxOptions = {}, colorCap: ColorCapability = 'full'): string {
+    const {
+        title,
+        borderColor,
+        borderStyle = 'rounded',
+        padding = 0,
+    } = options;
+
+    const chars = BORDER_CHARS[borderStyle] ?? BORDER_CHARS.rounded;
+    const lines = content.split('\n');
+    const maxTermWidth = Math.min(getTerminalWidth() - 4, 80);
+
+    // Calculate content width from visible text
+    const contentWidths = lines.map(l => getVisibleLength(l));
+    const titleWidth = title ? stripAnsi(title).length + 2 : 0; // +2 for spaces around title
+    const maxContentWidth = Math.max(...contentWidths, titleWidth);
+    const innerWidth = Math.min(maxContentWidth + 2, maxTermWidth); // +2 for horizontal padding
+
+    // Color wrapper for border chars
+    const bc = borderColor && colorCap !== 'none'
+        ? getANSIForeground(borderColor, colorCap)
+        : '';
+    const reset = bc ? ANSI.reset : '';
+
+    const wrap = (char: string) => `${bc}${char}${reset}`;
+
+    // Build top border (with optional title)
+    let topBorder: string;
+    if (title) {
+        const titleStr = ` ${title} `;
+        const afterTitle = innerWidth - stripAnsi(titleStr).length;
+        topBorder = `  ${wrap(chars.tl)}${wrap(chars.h)}${wrap(titleStr)}${wrap(chars.h.repeat(Math.max(0, afterTitle - 1)))}${wrap(chars.tr)}`;
+    } else {
+        topBorder = `  ${wrap(chars.tl)}${wrap(chars.h.repeat(innerWidth))}${wrap(chars.tr)}`;
+    }
+
+    // Build bottom border
+    const bottomBorder = `  ${wrap(chars.bl)}${wrap(chars.h.repeat(innerWidth))}${wrap(chars.br)}`;
+
+    // Build padding lines
+    const emptyLine = `  ${wrap(chars.v)}${' '.repeat(innerWidth)}${wrap(chars.v)}`;
+    const paddingLines = padding > 0 ? Array(padding).fill(emptyLine) : [];
+
+    // Build content lines
+    const contentLines = lines.map(line => {
+        const visible = getVisibleLength(line);
+        const pad = innerWidth - visible - 1; // -1 for left space
+        return `  ${wrap(chars.v)} ${line}${' '.repeat(Math.max(0, pad))}${wrap(chars.v)}`;
+    });
+
+    return [
+        topBorder,
+        ...paddingLines,
+        ...contentLines,
+        ...paddingLines,
+        bottomBorder,
+    ].join('\n');
+}

package/src/cli-primitives/cli-table.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview CLI table renderer for CLI primitives
+ * @since 5.0.0
+ */
+
+import type { ITableOptions } from '../types/core.js';
+import type { ColorCapability } from '../terminal/color-converter.js';
+import { getANSIForeground, ANSI } from '../terminal/color-converter.js';
+import { getVisibleLength, padToWidth } from '../terminal/formatter.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
+ */
+export function renderTable(
+    rows: Record<string, unknown>[],
+    options: ITableOptions = {},
+    colorCap: ColorCapability = 'full'
+): string {
+    if (rows.length === 0) return '';
+
+    // Determine columns from options or first row's keys
+    const columns = options.columns ?? Object.keys(rows[0]!);
+    const headers = options.head ?? columns;
+
+    // Calculate column widths (max of header and all values)
+    const colWidths = columns.map((col, i) => {
+        const headerLen = getVisibleLength(headers[i] ?? col);
+        const maxValueLen = rows.reduce((max, row) => {
+            const val = String(row[col] ?? '');
+            return Math.max(max, getVisibleLength(val));
+        }, 0);
+        return Math.max(headerLen, maxValueLen) + 2; // +2 for padding
+    });
+
+    // Color helpers
+    const cyan = colorCap !== 'none' ? getANSIForeground('#00bcd4', colorCap) : '';
+    const dim = colorCap !== 'none' ? ANSI.dim : '';
+    const reset = colorCap !== 'none' ? ANSI.reset : '';
+
+    // Build header row
+    const headerRow = '  ' + columns.map((col, i) => {
+        const label = headers[i] ?? col;
+        return cyan + ANSI.bold + padToWidth(` ${label}`, colWidths[i]!) + reset;
+    }).join('');
+
+    // Build separator
+    const separator = '  ' + dim + colWidths.map(w => '\u2500'.repeat(w)).join('\u2500') + reset;
+
+    // Build data rows
+    const dataRows = rows.map(row => {
+        return '  ' + columns.map((col, i) => {
+            const val = String(row[col] ?? '');
+            return padToWidth(` ${val}`, colWidths[i]!);
+        }).join('');
+    });
+
+    return [headerRow, separator, ...dataRows].join('\n');
+}

package/src/cli-primitives/divider.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Divider renderer for CLI primitives
+ * @since 5.0.0
+ */
+
+import { ANSI } from '../terminal/color-converter.js';
+import { getTerminalWidth } from '../utils/environment-detector.js';
+
+/**
+ * Renders a horizontal divider line
+ * @param width - Optional explicit width (defaults to terminal width capped at 60)
+ * @returns Formatted divider string
+ */
+export function renderDivider(width?: number): string {
+    const w = width ?? Math.min(getTerminalWidth() - 4, 60);
+    return ANSI.dim + '  ' + '\u2500'.repeat(w) + ANSI.reset;
+}

package/src/cli-primitives/header.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Header renderer for CLI primitives
+ * @since 5.0.0
+ */
+
+import { ANSI } from '../terminal/color-converter.js';
+
+/**
+ * Renders a styled header with optional subtitle
+ * @param title - Main title text
+ * @param subtitle - Optional subtitle (rendered dimmed)
+ * @returns Formatted header string
+ */
+export function renderHeader(title: string, subtitle?: string): string {
+    const t = ANSI.bold + title + ANSI.reset;
+    const s = subtitle ? ANSI.dim + ` ${subtitle}` + ANSI.reset : '';
+    return `  ${t}${s}`;
+}

package/src/cli-primitives/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview CLI Primitives - Built-in terminal UI components for better-logger
+ * @version 5.0.0
+ * @since 5.0.0
+ */
+
+export { renderStep } from './step.js';
+export { renderHeader } from './header.js';
+export { renderDivider } from './divider.js';
+export { renderBox } from './box.js';
+export { renderTable } from './cli-table.js';
+export { SpinnerManager, NoopSpinner } from './spinner.js';
+export { ServerFallback } from './server-fallback.js';

package/src/cli-primitives/server-fallback.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Server/JSON fallback for CLI primitives in non-TTY environments
+ * @since 5.0.0
+ */
+
+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.
+ *
+ * @since 5.0.0
+ */
+export class ServerFallback {
+    private logger: Logger;
+
+    constructor(logger: Logger) {
+        this.logger = logger;
+    }
+
+    /** Render step as plain info log */
+    step(current: number, total: number, msg: string): void {
+        this.logger.info(`[${current}/${total}] ${msg}`);
+    }
+
+    /** Render header as plain info log */
+    header(title: string, subtitle?: string): void {
+        const text = subtitle ? `${title} ${subtitle}` : title;
+        this.logger.info(text);
+    }
+
+    /** Divider is a no-op in server mode */
+    divider(): void {
+        // No-op in server/JSON mode
+    }
+
+    /** Blank line is a no-op in server mode */
+    blank(): void {
+        // No-op in server/JSON mode
+    }
+
+    /** Render box content as plain info log */
+    box(content: string, _options?: IBoxOptions): void {
+        this.logger.info(content);
+    }
+
+    /** Render table rows as plain info logs */
+    cliTable(rows: Record<string, unknown>[], _options?: ITableOptions): void {
+        for (const row of rows) {
+            this.logger.info(JSON.stringify(row));
+        }
+    }
+}