@mks2508/better-logger 3.1.0 → 5.0.0

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
@@ -371,4 +388,8 @@ export {
     getEnvironmentInfo,
 } from './utils/environment-detector.js';
 
-export type { Environment } from './utils/environment-detector.js';
+export type { Environment } from './utils/environment-detector.js';
+
+// Output writers for custom log destinations
+export { BufferWriter, type BufferEntry } from './writers/index.js';
+export type { OutputWriter, OutputMode } from './types/core.js';

package/src/types/core.ts

@@ -100,6 +100,48 @@ export type ExportFormat = 'json' | 'csv' | 'markdown' | 'plain' | 'html';
  */
 export type OutputFormat = 'auto' | 'plain' | 'ansi' | 'build' | 'ci';
 
+/**
+ * Output modes for controlling where logs are written
+ * @typedef {'console' | 'silent' | 'custom'} OutputMode
+ *
+ * @description
+ * - console: Standard console.log output (default)
+ * - silent: No output at all
+ * - custom: Use custom OutputWriter for advanced scenarios
+ */
+export type OutputMode = 'console' | 'silent' | 'custom';
+
+/**
+ * Custom output writer interface for redirecting log output
+ *
+ * @interface OutputWriter
+ * @since 4.0.0
+ *
+ * @description
+ * Allows redirecting log output to custom destinations like:
+ * - DraftLog for CLI spinners with concurrent logging
+ * - Buffers for collecting logs during operations
+ * - Custom streams or transports
+ *
+ * @example
+ * class BufferWriter implements OutputWriter {
+ *   private buffer: string[] = [];
+ *
+ *   write(message: string, level: LogLevel, styles: string[]): void {
+ *     this.buffer.push(message);
+ *   }
+ *
+ *   flush(): void {
+ *     this.buffer.forEach(msg => console.log(msg));
+ *     this.buffer = [];
+ *   }
+ * }
+ */
+export interface OutputWriter {
+    write(message: string, level: LogLevel, styles: string[]): void;
+    flush?(): void;
+}
+
 /**
  * Interfaz de configuración para instancias del logger
  * 
@@ -130,6 +172,12 @@ export interface LoggerConfig {
     bufferSize?: number;
     autoDetectTheme?: boolean;
     outputFormat?: OutputFormat;
+    /** Output mode: 'console' (default), 'silent', or 'custom' @since 4.0.0 */
+    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;
 }
 
 /**
@@ -315,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/src/writers/BufferWriter.ts

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview BufferWriter - Collects log output in memory for later use
+ * @version 4.0.0
+ */
+
+import type { LogLevel, OutputWriter } from '../types/core.js';
+
+/**
+ * Entry in the log buffer
+ */
+export interface BufferEntry {
+    message: string;
+    level: LogLevel;
+    styles: string[];
+    timestamp: number;
+}
+
+/**
+ * BufferWriter collects log messages in memory instead of outputting to console.
+ * Useful for:
+ * - CLI operations with spinners (buffer logs during spinner, show after)
+ * - Testing (capture logs for assertions)
+ * - Batch processing (collect logs, process together)
+ *
+ * @implements {OutputWriter}
+ * @since 4.0.0
+ *
+ * @example
+ * import logger, { BufferWriter } from '@mks2508/better-logger';
+ *
+ * const buffer = new BufferWriter();
+ * logger.updateConfig({
+ *   outputMode: 'custom',
+ *   outputWriter: buffer
+ * });
+ *
+ * // Logs go to buffer, not console
+ * spinner.start('Loading...');
+ * logger.info('Connecting...');
+ * logger.info('Processing...');
+ * spinner.stop();
+ *
+ * // Show buffered logs
+ * logger.updateConfig({ outputMode: 'console' });
+ * buffer.flush(); // Outputs all buffered logs to console
+ */
+export class BufferWriter implements OutputWriter {
+    private buffer: BufferEntry[] = [];
+    private maxSize: number;
+
+    /**
+     * Creates a new BufferWriter
+     * @param maxSize - Maximum number of entries to buffer (default: 1000)
+     */
+    constructor(maxSize: number = 1000) {
+        this.maxSize = maxSize;
+    }
+
+    /**
+     * Writes a log entry to the buffer
+     * @param message - Formatted log message
+     * @param level - Log level
+     * @param styles - CSS styles (for browser console)
+     */
+    write(message: string, level: LogLevel, styles: string[]): void {
+        if (this.buffer.length >= this.maxSize) {
+            this.buffer.shift(); // Remove oldest entry
+        }
+
+        this.buffer.push({
+            message,
+            level,
+            styles,
+            timestamp: Date.now()
+        });
+    }
+
+    /**
+     * Returns all buffered entries
+     * @returns Copy of the buffer array
+     */
+    getBuffer(): BufferEntry[] {
+        return [...this.buffer];
+    }
+
+    /**
+     * Returns buffered entries filtered by log level
+     * @param levels - Log levels to include
+     * @returns Filtered buffer entries
+     */
+    getByLevel(...levels: LogLevel[]): BufferEntry[] {
+        return this.buffer.filter(entry => levels.includes(entry.level));
+    }
+
+    /**
+     * Returns the number of buffered entries
+     */
+    get size(): number {
+        return this.buffer.length;
+    }
+
+    /**
+     * Checks if buffer is empty
+     */
+    get isEmpty(): boolean {
+        return this.buffer.length === 0;
+    }
+
+    /**
+     * Clears all buffered entries
+     */
+    clear(): void {
+        this.buffer = [];
+    }
+
+    /**
+     * Outputs all buffered entries to console and clears the buffer
+     */
+    flush(): void {
+        this.buffer.forEach(entry => {
+            if (entry.styles.length > 0) {
+                console.log(entry.message, ...entry.styles);
+            } else {
+                console.log(entry.message);
+            }
+        });
+        this.clear();
+    }
+
+    /**
+     * Outputs buffered entries to console without clearing
+     */
+    replay(): void {
+        this.buffer.forEach(entry => {
+            if (entry.styles.length > 0) {
+                console.log(entry.message, ...entry.styles);
+            } else {
+                console.log(entry.message);
+            }
+        });
+    }
+
+    /**
+     * Returns all messages as an array of strings
+     */
+    toArray(): string[] {
+        return this.buffer.map(entry => entry.message);
+    }
+
+    /**
+     * Returns all messages joined as a single string
+     * @param separator - String to join messages with (default: newline)
+     */
+    toString(separator: string = '\n'): string {
+        return this.toArray().join(separator);
+    }
+}

package/src/writers/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Output writers for better-logger
+ * @version 4.0.0
+ */
+
+export { BufferWriter, type BufferEntry } from './BufferWriter.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'
+        }
+      }
+    }
   }
 };