@mks2508/better-logger 4.0.0 → 5.0.1

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/terminal/formatter.ts

@@ -3,7 +3,7 @@
  */
 
 import { getTerminalWidth } from '../utils/environment-detector.js';
-import { getANSIForeground, ANSI, type ColorCapability } from './color-converter.js';
+import { getANSIForeground, getANSIBackground, ANSI, type ColorCapability } from './color-converter.js';
 import type { ColumnConfig, ColumnAlign, BadgeStyle, TimestampFormat, LogOptions } from '../types/index.js';
 
 export function stripAnsi(str: string): string {
@@ -137,26 +137,32 @@ export function formatBadge(
     colorCapability: ColorCapability = 'full',
     color?: string
 ): string {
-    const colorCode = color && colorCapability !== 'none'
-        ? getANSIForeground(color, colorCapability)
-        : '';
     const reset = colorCapability !== 'none' ? ANSI.reset : '';
-    const bgBlack = colorCapability !== 'none' ? ANSI.bg.black : '';
 
     const text = badge.toUpperCase();
 
     switch (style) {
         case 'rounded':
-            return `${bgBlack}${colorCode}⟨${text}⟩${reset}`;
+            const colorCode1 = color && colorCapability !== 'none' ? getANSIForeground(color, colorCapability) : '';
+            const bgBlack1 = colorCapability !== 'none' ? ANSI.bg.black : '';
+            return `${bgBlack1}${colorCode1}⟨${text}⟩${reset}`;
         case 'plain':
-            return `${colorCode}${text}${reset}`;
+            const colorCode2 = color && colorCapability !== 'none' ? getANSIForeground(color, colorCapability) : '';
+            return `${colorCode2}${text}${reset}`;
         case 'unicode':
-            return `${bgBlack}${colorCode}╭${text}╮${reset}`;
+            const colorCode3 = color && colorCapability !== 'none' ? getANSIForeground(color, colorCapability) : '';
+            const bgBlack3 = colorCapability !== 'none' ? ANSI.bg.black : '';
+            return `${bgBlack3}${colorCode3}╭${text}╮${reset}`;
         case 'pill':
-            return `${bgBlack}${colorCode}⦗${text}⦘${reset}`;
+            // Badge con background de color y texto blanco/negro
+            const bgColor = color && colorCapability !== 'none' ? getANSIBackground(color, colorCapability) : '';
+            const fgColor = colorCapability !== 'none' ? getANSIForeground('#000000', colorCapability) : '';
+            return `${bgColor}${fgColor}[${text}]${reset}`;
         case 'brackets':
         default:
-            return `${bgBlack}${colorCode}[${text}]${reset}`;
+            const colorCode5 = color && colorCapability !== 'none' ? getANSIForeground(color, colorCapability) : '';
+            const bgBlack5 = colorCapability !== 'none' ? ANSI.bg.black : '';
+            return `${bgBlack5}${colorCode5}[${text}]${reset}`;
     }
 }
 

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