@mks2508/better-logger 4.0.0 → 5.0.0

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));
+        }
+    }
+}

package/src/cli-primitives/spinner.ts

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Built-in spinner implementation for CLI primitives
+ * @since 5.0.0
+ */
+
+import type { ISpinnerHandle, LoggerConfig } from '../types/core.js';
+import type { Logger } from '../Logger.js';
+import { ANSI } from '../terminal/color-converter.js';
+
+/** Braille-based spinner animation frames */
+const SPINNER_FRAMES = ['\u280b', '\u2819', '\u2839', '\u2838', '\u283c', '\u2834', '\u2826', '\u2827', '\u2807', '\u280f'];
+
+/** Spinner frame interval in milliseconds */
+const FRAME_INTERVAL = 80;
+
+/**
+ * Interactive terminal spinner with in-place line updates.
+ * Writes to stderr to avoid polluting piped stdout.
+ *
+ * @implements {ISpinnerHandle}
+ * @since 5.0.0
+ */
+export class SpinnerManager implements ISpinnerHandle {
+    private message: string;
+    private frameIndex = 0;
+    private interval: ReturnType<typeof setInterval> | null = null;
+    private _logger: Logger;
+
+    constructor(message: string, _config: LoggerConfig, logger: Logger) {
+        this.message = message;
+        this._logger = logger;
+    }
+
+    /** Start the spinner animation */
+    start(): void {
+        if (this.interval) return; // Already running
+
+        // Switch logger to buffer mode to prevent garbled output
+        this._logger.updateConfig({ outputMode: 'silent' });
+
+        this.frameIndex = 0;
+        this.render();
+        this.interval = setInterval(() => {
+            this.frameIndex = (this.frameIndex + 1) % SPINNER_FRAMES.length;
+            this.render();
+        }, FRAME_INTERVAL);
+    }
+
+    /** Stop the spinner without a status message */
+    stop(): void {
+        this.clearInterval();
+        this.clearLine();
+        // Restore logger output
+        this._logger.updateConfig({ outputMode: 'console' });
+    }
+
+    /** Stop with a success indicator */
+    succeed(msg?: string): void {
+        this.clearInterval();
+        this.clearLine();
+        const text = msg ?? this.message;
+        process.stderr.write(`  ${ANSI.fg.green}\u2713${ANSI.reset} ${text}\n`);
+        this._logger.updateConfig({ outputMode: 'console' });
+    }
+
+    /** Stop with a failure indicator */
+    fail(msg?: string): void {
+        this.clearInterval();
+        this.clearLine();
+        const text = msg ?? this.message;
+        process.stderr.write(`  ${ANSI.fg.red}\u2717${ANSI.reset} ${text}\n`);
+        this._logger.updateConfig({ outputMode: 'console' });
+    }
+
+    /** Update the spinner text while running */
+    text(msg: string): void {
+        this.message = msg;
+    }
+
+    private render(): void {
+        const frame = SPINNER_FRAMES[this.frameIndex] ?? SPINNER_FRAMES[0];
+        const line = `  ${ANSI.fg.cyan}${frame}${ANSI.reset} ${this.message}`;
+        process.stderr.write(`\r\x1b[K${line}`);
+    }
+
+    private clearLine(): void {
+        process.stderr.write('\r\x1b[K');
+    }
+
+    private clearInterval(): void {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+    }
+}
+
+/**
+ * No-op spinner for non-TTY environments or silent mode.
+ * Logs start/succeed/fail as plain log messages.
+ *
+ * @implements {ISpinnerHandle}
+ * @since 5.0.0
+ */
+export class NoopSpinner implements ISpinnerHandle {
+    private message: string;
+    private _logger: Logger;
+
+    constructor(message: string, logger: Logger) {
+        this.message = message;
+        this._logger = logger;
+    }
+
+    start(): void {
+        this._logger.info(this.message);
+    }
+
+    stop(): void {
+        // No-op
+    }
+
+    succeed(msg?: string): void {
+        this._logger.success(msg ?? this.message);
+    }
+
+    fail(msg?: string): void {
+        this._logger.error(msg ?? this.message);
+    }
+
+    text(msg: string): void {
+        this.message = msg;
+    }
+}

package/src/cli-primitives/step.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Step progress renderer for CLI primitives
+ * @since 5.0.0
+ */
+
+import { getANSIForeground, ANSI, type ColorCapability } from '../terminal/color-converter.js';
+
+/**
+ * Renders a step progress indicator like `  [2/5] Analyzing repository...`
+ * @param current - Current step number
+ * @param total - Total number of steps
+ * @param msg - Step description message
+ * @param colorCap - Terminal color capability
+ * @returns Formatted step string
+ */
+export function renderStep(current: number, total: number, msg: string, colorCap: ColorCapability): string {
+    const label = `[${current}/${total}]`;
+    const colored = colorCap !== 'none'
+        ? getANSIForeground('#00bcd4', colorCap) + ANSI.bold + label + ANSI.reset
+        : label;
+    return `  ${colored} ${msg}`;
+}

package/src/constants.ts

@@ -2,7 +2,7 @@
  * @fileoverview Global constants for Advanced Logger
  */
 
-import type { LogLevel, AdaptiveColors } from './types/index.js';
+import type { LogLevel, AdaptiveColors, CLILogLevel, Verbosity } from './types/index.js';
 import type { LevelStyleConfig } from './utils/index.js';
 
 /**
@@ -298,4 +298,16 @@ export function getOptimalConfig() {
         ...DEFAULT_CONFIG,
         ...BUILD_PRESETS[preset]
     };
-}
+}
+
+/**
+ * CLI log level to internal verbosity mapping
+ * @since 5.0.0
+ */
+export const CLI_LEVEL_MAP: Record<CLILogLevel, { verbosity: Verbosity; showPrimitives: boolean }> = {
+    silent:  { verbosity: 'silent',  showPrimitives: false },
+    quiet:   { verbosity: 'error',   showPrimitives: false },
+    normal:  { verbosity: 'info',    showPrimitives: true  },
+    verbose: { verbosity: 'debug',   showPrimitives: true  },
+    debug:   { verbosity: 'debug',   showPrimitives: true  },
+} as const;

package/src/index.ts

@@ -18,7 +18,10 @@ import type {
     ThemeVariant,
     BannerType,
     StyleOptions,
-    ILogHandler
+    ILogHandler,
+    CLILogLevel,
+    IBoxOptions,
+    ITableOptions,
 } from './types/index.js';
 
 // Lazy singleton - se inicializa solo cuando se necesita
@@ -115,6 +118,16 @@ export const logAnimated = (message: string, duration?: number) =>
     getLogger().logAnimated(message, duration);
 export const cli = (command: string) => getLogger().cli(command);
 
+// CLI Primitives (v5.0)
+export const step = (current: number, total: number, message: string) => getLogger().step(current, total, message);
+export const spinner = (message: string) => getLogger().spinner(message);
+export const box = (content: string, options?: IBoxOptions) => getLogger().box(content, options);
+export const cliTable = (rows: Record<string, unknown>[], options?: ITableOptions) => getLogger().cliTable(rows, options);
+export const header = (title: string, subtitle?: string) => getLogger().header(title, subtitle);
+export const divider = () => getLogger().divider();
+export const blank = () => getLogger().blank();
+export const setCLILevel = (level: CLILogLevel) => getLogger().setCLILevel(level);
+
 // Type exports
 export type {
     LogLevel,
@@ -152,6 +165,10 @@ export type {
     ColumnAlign,
     ColumnConfig,
     LogOptions,
+    CLILogLevel,
+    ISpinnerHandle,
+    IBoxOptions,
+    ITableOptions,
 } from './types/index.js';
 
 // Styling utilities

package/src/types/core.ts

@@ -176,6 +176,8 @@ export interface LoggerConfig {
     outputMode?: OutputMode;
     /** Custom writer when outputMode is 'custom' @since 4.0.0 */
     outputWriter?: OutputWriter;
+    /** CLI verbosity level for controlling primitive output @since 5.0.0 */
+    cliLevel?: CLILogLevel;
 }
 
 /**
@@ -361,4 +363,55 @@ export interface LogOptions {
     keyValue?: boolean;
     badgeStyle?: BadgeStyle;
     timestampFormat?: TimestampFormat;
+}
+
+// ===== CLI PRIMITIVES (v5.0) =====
+
+/**
+ * CLI verbosity levels for controlling primitive output
+ * @since 5.0.0
+ */
+export type CLILogLevel = 'silent' | 'quiet' | 'normal' | 'verbose' | 'debug';
+
+/**
+ * Handle returned by logger.spinner() for controlling spinner lifecycle
+ * @since 5.0.0
+ */
+export interface ISpinnerHandle {
+    /** Start the spinner animation */
+    start(): void;
+    /** Stop the spinner without a status message */
+    stop(): void;
+    /** Stop the spinner with a success message */
+    succeed(msg?: string): void;
+    /** Stop the spinner with a failure message */
+    fail(msg?: string): void;
+    /** Update the spinner text while running */
+    text(msg: string): void;
+}
+
+/**
+ * Options for logger.box() output
+ * @since 5.0.0
+ */
+export interface IBoxOptions {
+    /** Title displayed in the top border */
+    title?: string;
+    /** Color of the border (hex, CSS name, or ANSI name) */
+    borderColor?: string;
+    /** Border character style */
+    borderStyle?: 'single' | 'double' | 'rounded' | 'bold';
+    /** Inner padding lines (default: 0) */
+    padding?: number;
+}
+
+/**
+ * Options for logger.cliTable() output
+ * @since 5.0.0
+ */
+export interface ITableOptions {
+    /** Column names to display (overrides auto-detection) */
+    columns?: string[];
+    /** Header labels (defaults to column names) */
+    head?: string[];
 }

package/src/types/index.ts

@@ -30,6 +30,10 @@ export type {
     ColumnAlign,
     ColumnConfig,
     LogOptions,
+    CLILogLevel,
+    ISpinnerHandle,
+    IBoxOptions,
+    ITableOptions,
 } from './core.js';
 
 export { LOG_LEVELS } from './core.js';

package/vite.config.ts

@@ -57,6 +57,7 @@ const buildConfigs = {
         entry: {
           index: resolve(__dirname, 'src/index.ts'),
           core: resolve(__dirname, 'src/core.ts'),
+          cli: resolve(__dirname, 'src/cli-module.ts'),
           styling: resolve(__dirname, 'src/styling-module.ts'),
           exports: resolve(__dirname, 'src/exports-module.ts')
         },
@@ -210,6 +211,38 @@ const buildConfigs = {
         }
       }
     }
+  },
+
+  // Build modular - Solo CLI primitives (spinners, boxes, tables, steps)
+  cli: {
+    ...baseConfig,
+    plugins: [
+      dts({
+        ...baseConfig.plugins[0].options,
+        outDir: 'packages/cli/dist/types',
+        include: ['src/cli-module.ts', 'src/cli-primitives/**/*', 'src/types/**/*', 'src/terminal/**/*', 'src/utils/environment-detector.ts'],
+      })
+    ],
+    build: {
+      ...baseConfig.build,
+      outDir: 'packages/cli/dist',
+      lib: {
+        entry: resolve(__dirname, 'src/cli-module.ts'),
+        name: 'BetterLoggerCLI',
+        formats: ['es', 'cjs'],
+        fileName: (format) => {
+          const ext = format === 'cjs' ? 'cjs' : 'js';
+          return `index.${ext}`;
+        }
+      },
+      rollupOptions: {
+        external: [],
+        output: {
+          globals: {},
+          exports: 'named'
+        }
+      }
+    }
   }
 };