@mks2508/better-logger 4.0.0 → 5.0.0

package/playground/demo-levels.ts

@@ -0,0 +1,56 @@
+/**
+ * setCLILevel() toggling: silent → quiet → normal → verbose.
+ * Run: bun playground/demo-levels.ts
+ */
+import { Logger } from '../src/Logger.js';
+import type { CLILogLevel } from '../src/types/index.js';
+
+const logger = new Logger();
+
+function demonstrateLevel(level: CLILogLevel) {
+    logger.setCLILevel(level);
+    process.stderr.write(`\n── setCLILevel('${level}') ──\n`);
+
+    // Try each primitive
+    logger.header('Header', 'subtitle');
+    logger.divider();
+    logger.step(1, 3, 'Step message');
+    logger.box('Box content', { title: 'Box', borderStyle: 'rounded' });
+    logger.cliTable([{ key: 'value', status: 'ok' }]);
+    logger.blank();
+
+    // Also test regular log methods
+    logger.info('info message');
+    logger.warn('warn message');
+    logger.error('error message');
+
+    process.stderr.write(`── end '${level}' ──\n`);
+}
+
+function main() {
+    // Start with a visible header
+    logger.setCLILevel('normal');
+    logger.header('CLI Level Demos');
+    logger.divider();
+
+    logger.info('Each level sets verbosity + primitive visibility:');
+    logger.info('  silent  → no output at all');
+    logger.info('  quiet   → errors only, primitives hidden');
+    logger.info('  normal  → info+, primitives visible');
+    logger.info('  verbose → debug+, primitives visible');
+    logger.blank();
+
+    // Demonstrate each level
+    const levels: CLILogLevel[] = ['silent', 'quiet', 'normal', 'verbose'];
+    for (const level of levels) {
+        demonstrateLevel(level);
+    }
+
+    // Restore to normal
+    logger.setCLILevel('normal');
+    logger.blank();
+    logger.divider();
+    logger.info('Level demos complete. Restored to "normal".');
+}
+
+main();

package/playground/demo-real-world.ts

@@ -0,0 +1,98 @@
+/**
+ * Real-world simulation: a commit-wizard-like CLI workflow.
+ * Run: bun playground/demo-real-world.ts
+ */
+import { Logger } from '../src/Logger.js';
+
+const logger = new Logger();
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function main() {
+    // ── Startup ───────────────────────────────────────
+    logger.header('Commit Wizard', 'v2.0.0');
+    logger.divider();
+    logger.blank();
+
+    // ── Step 1: Analyze repository ────────────────────
+    logger.step(1, 5, 'Analyzing repository...');
+    const s1 = logger.spinner('Loading git diff...');
+    s1.start();
+    await sleep(1200);
+    s1.succeed('3 files changed, 47 insertions, 12 deletions');
+    logger.blank();
+
+    // ── Step 2: Detect provider ───────────────────────
+    logger.step(2, 5, 'Detecting provider...');
+    await sleep(300);
+
+    logger.cliTable([
+        { provider: 'Gemini SDK', key: 'GEMINI_API_KEY', status: 'not set' },
+        { provider: 'Groq', key: 'GROQ_API_KEY', status: 'found ✓' },
+        { provider: 'OpenRouter', key: 'OPENROUTER_API_KEY', status: 'not set' },
+        { provider: 'Gemini CLI', key: 'binary', status: 'not found' },
+    ]);
+    logger.blank();
+    logger.info('  Using provider: Groq (llama-3.3-70b-versatile)');
+    logger.blank();
+
+    // ── Step 3: Generate commit ───────────────────────
+    logger.step(3, 5, 'Generating commit message...');
+    const s3 = logger.spinner('AI thinking...');
+    s3.start();
+    await sleep(800);
+    s3.text('Analyzing diff patterns...');
+    await sleep(600);
+    s3.text('Composing message...');
+    await sleep(600);
+    s3.succeed('Commit message generated');
+    logger.blank();
+
+    logger.box(
+        [
+            'feat(providers): add multi-provider AI support',
+            '',
+            'Implement Gemini SDK, Groq, and OpenRouter providers',
+            'with automatic detection based on available API keys.',
+            '',
+            '<technical>',
+            '- Added GeminiSdkProvider, GroqProvider, OpenRouterProvider classes',
+            '- Factory function with priority-based auto-detection',
+            '- Shared IAIProvider interface for all implementations',
+            '</technical>',
+            '',
+            '<changelog>',
+            '## Feature 🚀',
+            'Multi-provider AI support with automatic fallback',
+            '</changelog>',
+        ].join('\n'),
+        { title: 'Commit #1', borderStyle: 'rounded', borderColor: '#ff6b6b' },
+    );
+    logger.blank();
+
+    // ── Step 4: Apply commit ──────────────────────────
+    logger.step(4, 5, 'Applying commit...');
+    const s4 = logger.spinner('Running git commit...');
+    s4.start();
+    await sleep(800);
+    s4.succeed('Commit applied: abc1234');
+    logger.blank();
+
+    // ── Step 5: Done ──────────────────────────────────
+    logger.step(5, 5, 'Done');
+    logger.blank();
+
+    logger.box(
+        [
+            '1 commit applied successfully',
+            '',
+            'Provider: Groq',
+            'Model:    llama-3.3-70b-versatile',
+            'Time:     2.4s',
+        ].join('\n'),
+        { title: 'Summary', borderStyle: 'rounded', borderColor: '#00ff00' },
+    );
+    logger.blank();
+    logger.divider();
+}
+
+main().catch(console.error);

package/playground/demo-spinner.ts

@@ -0,0 +1,77 @@
+/**
+ * Spinner lifecycle: start, text update, succeed/fail.
+ * Run: bun playground/demo-spinner.ts
+ */
+import { Logger } from '../src/Logger.js';
+
+const logger = new Logger();
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function main() {
+    logger.header('Spinner Demos');
+    logger.divider();
+    logger.blank();
+
+    // ── Basic spinner → succeed ───────────────────────
+    logger.info('1. Basic spinner with succeed');
+    const s1 = logger.spinner('Installing dependencies...');
+    s1.start();
+    await sleep(1500);
+    s1.succeed('Dependencies installed');
+    logger.blank();
+
+    // ── Spinner with text() update ────────────────────
+    logger.info('2. Spinner with text update');
+    const s2 = logger.spinner('Downloading package 1/3...');
+    s2.start();
+    await sleep(800);
+    s2.text('Downloading package 2/3...');
+    await sleep(800);
+    s2.text('Downloading package 3/3...');
+    await sleep(800);
+    s2.succeed('All packages downloaded');
+    logger.blank();
+
+    // ── Spinner → fail ────────────────────────────────
+    logger.info('3. Spinner with fail');
+    const s3 = logger.spinner('Connecting to database...');
+    s3.start();
+    await sleep(1200);
+    s3.fail('Connection refused on port 5432');
+    logger.blank();
+
+    // ── Multiple sequential spinners ──────────────────
+    logger.info('4. Sequential spinners');
+    const tasks = [
+        'Compiling TypeScript...',
+        'Running linter...',
+        'Building bundles...',
+        'Generating types...',
+    ];
+    for (const task of tasks) {
+        const s = logger.spinner(task);
+        s.start();
+        await sleep(700);
+        s.succeed();
+    }
+    logger.blank();
+
+    // ── Spinner concurrent with logger.info ───────────
+    logger.info('5. Spinner with interleaved log messages');
+    const s5 = logger.spinner('Processing files...');
+    s5.start();
+    await sleep(400);
+    logger.info('  Found 42 files');
+    await sleep(400);
+    logger.info('  Processed batch 1');
+    await sleep(400);
+    logger.info('  Processed batch 2');
+    await sleep(400);
+    s5.succeed('All files processed');
+    logger.blank();
+
+    logger.divider();
+    logger.info('Spinner demos complete.');
+}
+
+main().catch(console.error);

package/playground/demo-steps.ts

@@ -0,0 +1,72 @@
+/**
+ * Step progress walkthrough with simulated work delays.
+ * Run: bun playground/demo-steps.ts
+ */
+import { Logger } from '../src/Logger.js';
+
+const logger = new Logger();
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function main() {
+    logger.header('Step Progress Demos');
+    logger.divider();
+    logger.blank();
+
+    // ── Basic step sequence ───────────────────────────
+    logger.info('1. Basic step sequence');
+    logger.blank();
+
+    const steps = [
+        'Reading configuration...',
+        'Validating schema...',
+        'Compiling sources...',
+        'Running tests...',
+        'Generating output...',
+    ];
+
+    for (let i = 0; i < steps.length; i++) {
+        logger.step(i + 1, steps.length, steps[i]);
+        await sleep(300);
+    }
+    logger.blank();
+
+    // ── Steps combined with spinners ──────────────────
+    logger.info('2. Steps with spinners');
+    logger.blank();
+
+    logger.step(1, 3, 'Fetching remote data');
+    const s1 = logger.spinner('Downloading manifest...');
+    s1.start();
+    await sleep(1000);
+    s1.succeed('Manifest downloaded (2.3 KB)');
+
+    logger.step(2, 3, 'Processing data');
+    const s2 = logger.spinner('Parsing JSON...');
+    s2.start();
+    await sleep(600);
+    s2.text('Validating entries...');
+    await sleep(600);
+    s2.succeed('42 entries validated');
+
+    logger.step(3, 3, 'Writing output');
+    const s3 = logger.spinner('Generating report...');
+    s3.start();
+    await sleep(800);
+    s3.succeed('Report saved to ./output/report.json');
+    logger.blank();
+
+    // ── Many steps ────────────────────────────────────
+    logger.info('3. Long step sequence (10 steps)');
+    logger.blank();
+
+    for (let i = 1; i <= 10; i++) {
+        logger.step(i, 10, `Migration step ${i}`);
+        await sleep(150);
+    }
+    logger.blank();
+
+    logger.divider();
+    logger.info('Step demos complete.');
+}
+
+main().catch(console.error);

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 =====
 
     /**