@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/logger.d.ts

@@ -1,993 +0,0 @@
-/**
- * @fileoverview Console logging utilities with line prefix support.
- * Provides enhanced console methods with formatted output capabilities.
- */
-/**
- * Log symbols for terminal output with colored indicators.
- *
- * Each symbol provides visual feedback for different message types, with
- * Unicode and ASCII fallback support.
- *
- * @example
- * ```typescript
- * import { LOG_SYMBOLS } from '@socketsecurity/lib'
- *
- * console.log(`${LOG_SYMBOLS.success} Operation completed`)
- * console.log(`${LOG_SYMBOLS.fail} Operation failed`)
- * console.log(`${LOG_SYMBOLS.warn} Warning message`)
- * console.log(`${LOG_SYMBOLS.info} Information message`)
- * console.log(`${LOG_SYMBOLS.step} Processing step`)
- * console.log(`${LOG_SYMBOLS.progress} Working on task`)
- * ```
- */
-type LogSymbols = {
-    /** Red colored failure symbol (✖ or × in ASCII) */
-    fail: string;
-    /** Blue colored information symbol (ℹ or i in ASCII) */
-    info: string;
-    /** Cyan colored progress indicator symbol (∴ or :. in ASCII) */
-    progress: string;
-    /** Cyan colored skip symbol (↻ or @ in ASCII) */
-    skip: string;
-    /** Cyan colored step symbol (→ or > in ASCII) */
-    step: string;
-    /** Green colored success symbol (✔ or √ in ASCII) */
-    success: string;
-    /** Yellow colored warning symbol (⚠ or ‼ in ASCII) */
-    warn: string;
-};
-/**
- * Type definition for logger methods that mirror console methods.
- *
- * All methods return the logger instance for method chaining.
- */
-type LoggerMethods = {
-    [K in keyof typeof console]: (typeof console)[K] extends (...args: infer A) => any ? (...args: A) => Logger : (typeof console)[K];
-};
-/**
- * A task that can be executed with automatic start/complete logging.
- *
- * @example
- * ```typescript
- * const task = logger.createTask('Database migration')
- * task.run(() => {
- *   // Migration logic here
- * })
- * // Logs: "Starting task: Database migration"
- * // Logs: "Completed task: Database migration"
- * ```
- */
-interface Task {
-    /**
-     * Executes the task function with automatic logging.
-     *
-     * @template T - The return type of the task function
-     * @param f - The function to execute
-     * @returns The result of the task function
-     */
-    run<T>(f: () => T): T;
-}
-export type { LogSymbols, LoggerMethods, Task };
-/**
- * Log symbols for terminal output with colored indicators.
- *
- * Provides colored Unicode symbols (✖, ℹ, ∴, →, ✔, ⚠) with ASCII fallbacks (×, i, :., >, √, ‼)
- * for terminals that don't support Unicode. Symbols are colored according to the active
- * theme's color palette (error, info, reason, step, success, warning).
- *
- * The symbols are lazily initialized on first access and automatically update when the
- * fallback theme changes (via setTheme()). Note that LOG_SYMBOLS reflect the global
- * fallback theme, not async-local theme contexts from withTheme().
- *
- * @example
- * ```typescript
- * import { LOG_SYMBOLS } from '@socketsecurity/lib'
- *
- * console.log(`${LOG_SYMBOLS.fail} Build failed`)          // Theme error color ✖
- * console.log(`${LOG_SYMBOLS.info} Starting process`)      // Theme info color ℹ
- * console.log(`${LOG_SYMBOLS.progress} Working on task`)   // Theme step color ∴
- * console.log(`${LOG_SYMBOLS.step} Processing files`)      // Theme step color →
- * console.log(`${LOG_SYMBOLS.success} Build completed`)    // Theme success color ✔
- * console.log(`${LOG_SYMBOLS.warn} Deprecated API used`)   // Theme warning color ⚠
- * ```
- */
-export declare const LOG_SYMBOLS: Record<string, string>;
-/**
- * Symbol for incrementing the internal log call counter.
- *
- * This is an internal symbol used to track the number of times logging
- * methods have been called on a logger instance.
- */
-export declare const incLogCallCountSymbol: unique symbol;
-/**
- * Symbol for tracking whether the last logged line was blank.
- *
- * This is used internally to prevent multiple consecutive blank lines
- * and to determine whether to add spacing before certain messages.
- */
-export declare const lastWasBlankSymbol: unique symbol;
-/**
- * Enhanced console logger with indentation, colored symbols, and stream management.
- *
- * Provides a fluent API for logging with automatic indentation tracking, colored
- * status symbols, separate stderr/stdout management, and method chaining. All
- * methods return `this` for easy chaining.
- *
- * Features:
- * - Automatic line prefixing with indentation
- * - Colored status symbols (success, fail, warn, info)
- * - Separate indentation tracking for stderr and stdout
- * - Stream-bound logger instances via `.stderr` and `.stdout`
- * - Group/indentation management
- * - Progress indicators with clearable lines
- * - Task execution with automatic logging
- *
- * @example
- * ```typescript
- * import { logger } from '@socketsecurity/lib'
- *
- * // Basic logging with symbols
- * logger.success('Build completed')
- * logger.fail('Build failed')
- * logger.warn('Deprecated API')
- * logger.info('Starting process')
- *
- * // Indentation and grouping
- * logger.log('Processing files:')
- * logger.indent()
- * logger.log('file1.js')
- * logger.log('file2.js')
- * logger.dedent()
- *
- * // Method chaining
- * logger
- *   .log('Step 1')
- *   .indent()
- *   .log('Substep 1.1')
- *   .log('Substep 1.2')
- *   .dedent()
- *   .log('Step 2')
- *
- * // Stream-specific logging
- * logger.stdout.log('Normal output')
- * logger.stderr.error('Error message')
- *
- * // Progress indicators
- * logger.progress('Processing...')
- * // ... do work ...
- * logger.clearLine()
- * logger.success('Done')
- *
- * // Task execution
- * const task = logger.createTask('Migration')
- * task.run(() => {
- *   // Migration logic
- * })
- * ```
- */
-export declare class Logger {
-    #private;
-    /**
-     * Static reference to log symbols for convenience.
-     *
-     * @example
-     * ```typescript
-     * console.log(`${Logger.LOG_SYMBOLS.success} Done`)
-     * ```
-     */
-    static LOG_SYMBOLS: Record<string, string>;
-    /**
-     * Creates a new Logger instance.
-     *
-     * When called without arguments, creates a logger using the default
-     * `process.stdout` and `process.stderr` streams. Can accept custom
-     * console constructor arguments for advanced use cases.
-     *
-     * @param args - Optional console constructor arguments
-     *
-     * @example
-     * ```typescript
-     * // Default logger
-     * const logger = new Logger()
-     *
-     * // Custom streams (advanced)
-     * const customLogger = new Logger({
-     *   stdout: customWritableStream,
-     *   stderr: customErrorStream
-     * })
-     * ```
-     */
-    constructor(...args: unknown[]);
-    /**
-     * Gets a logger instance bound exclusively to stderr.
-     *
-     * All logging operations on this instance will write to stderr only.
-     * Indentation is tracked separately from stdout. The instance is
-     * cached and reused on subsequent accesses.
-     *
-     * @returns A logger instance bound to stderr
-     *
-     * @example
-     * ```typescript
-     * // Write errors to stderr
-     * logger.stderr.error('Configuration invalid')
-     * logger.stderr.warn('Using fallback settings')
-     *
-     * // Indent only affects stderr
-     * logger.stderr.indent()
-     * logger.stderr.error('Nested error details')
-     * logger.stderr.dedent()
-     * ```
-     */
-    get stderr(): Logger;
-    /**
-     * Gets a logger instance bound exclusively to stdout.
-     *
-     * All logging operations on this instance will write to stdout only.
-     * Indentation is tracked separately from stderr. The instance is
-     * cached and reused on subsequent accesses.
-     *
-     * @returns A logger instance bound to stdout
-     *
-     * @example
-     * ```typescript
-     * // Write normal output to stdout
-     * logger.stdout.log('Processing started')
-     * logger.stdout.log('Items processed: 42')
-     *
-     * // Indent only affects stdout
-     * logger.stdout.indent()
-     * logger.stdout.log('Detailed output')
-     * logger.stdout.dedent()
-     * ```
-     */
-    get stdout(): Logger;
-    /**
-     * Gets the total number of log calls made on this logger instance.
-     *
-     * Tracks all logging method calls including `log()`, `error()`, `warn()`,
-     * `success()`, `fail()`, etc. Useful for testing and monitoring logging activity.
-     *
-     * @returns The number of times logging methods have been called
-     *
-     * @example
-     * ```typescript
-     * logger.log('Message 1')
-     * logger.error('Message 2')
-     * console.log(logger.logCallCount) // 2
-     * ```
-     */
-    get logCallCount(): number;
-    /**
-     * Increments the internal log call counter.
-     *
-     * This is called automatically by logging methods and should not
-     * be called directly in normal usage.
-     *
-     * @returns The logger instance for chaining
-     */
-    [incLogCallCountSymbol](): this;
-    /**
-     * Sets whether the last logged line was blank.
-     *
-     * Used internally to track blank lines and prevent duplicate spacing.
-     * This is called automatically by logging methods.
-     *
-     * @param value - Whether the last line was blank
-     * @param stream - Optional stream to update (defaults to both streams if not bound, or target stream if bound)
-     * @returns The logger instance for chaining
-     */
-    [lastWasBlankSymbol](value: unknown, stream?: 'stderr' | 'stdout'): this;
-    /**
-     * Logs an assertion failure message if the value is falsy.
-     *
-     * Works like `console.assert()` but returns the logger for chaining.
-     * If the value is truthy, nothing is logged. If falsy, logs an error
-     * message with an assertion failure.
-     *
-     * @param value - The value to test
-     * @param message - Optional message and additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.assert(true, 'This will not log')
-     * logger.assert(false, 'Assertion failed: value is false')
-     * logger.assert(items.length > 0, 'No items found')
-     * ```
-     */
-    assert(value: unknown, ...message: unknown[]): this;
-    /**
-     * Clears the current line in the terminal.
-     *
-     * Moves the cursor to the beginning of the line and clears all content.
-     * Works in both TTY and non-TTY environments. Useful for clearing
-     * progress indicators created with `progress()`.
-     *
-     * The stream to clear (stderr or stdout) depends on whether the logger
-     * is stream-bound.
-     *
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.progress('Loading...')
-     * // ... do work ...
-     * logger.clearLine()
-     * logger.success('Loaded')
-     *
-     * // Clear multiple progress updates
-     * for (const file of files) {
-     *   logger.progress(`Processing ${file}`)
-     *   processFile(file)
-     *   logger.clearLine()
-     * }
-     * logger.success('All files processed')
-     * ```
-     */
-    clearLine(): this;
-    /**
-     * Clears the visible terminal screen.
-     *
-     * Only available on the main logger instance, not on stream-bound instances
-     * (`.stderr` or `.stdout`). Resets the log call count and blank line tracking
-     * if the output is a TTY.
-     *
-     * @returns The logger instance for chaining
-     * @throws {Error} If called on a stream-bound logger instance
-     *
-     * @example
-     * ```typescript
-     * logger.log('Some output')
-     * logger.clearVisible()  // Screen is now clear
-     *
-     * // Error: Can't call on stream-bound instance
-     * logger.stderr.clearVisible()  // throws
-     * ```
-     */
-    clearVisible(): this;
-    /**
-     * Increments and logs a counter for the given label.
-     *
-     * Each unique label maintains its own counter. Works like `console.count()`.
-     *
-     * @param label - Optional label for the counter
-     * @default 'default'
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.count('requests')  // requests: 1
-     * logger.count('requests')  // requests: 2
-     * logger.count('errors')    // errors: 1
-     * logger.count()            // default: 1
-     * ```
-     */
-    count(label?: string | undefined): this;
-    /**
-     * Creates a task that logs start and completion messages automatically.
-     *
-     * Returns a task object with a `run()` method that executes the provided
-     * function and logs "Starting task: {name}" before execution and
-     * "Completed task: {name}" after completion.
-     *
-     * @param name - The name of the task
-     * @returns A task object with a `run()` method
-     *
-     * @example
-     * ```typescript
-     * const task = logger.createTask('Database Migration')
-     * const result = task.run(() => {
-     *   // Logs: "Starting task: Database Migration"
-     *   migrateDatabase()
-     *   return 'success'
-     *   // Logs: "Completed task: Database Migration"
-     * })
-     * console.log(result)  // 'success'
-     * ```
-     */
-    createTask(name: string): Task;
-    /**
-     * Decreases the indentation level by removing spaces from the prefix.
-     *
-     * When called on the main logger, affects both stderr and stdout indentation.
-     * When called on a stream-bound logger (`.stderr` or `.stdout`), affects
-     * only that stream's indentation.
-     *
-     * @param spaces - Number of spaces to remove from indentation
-     * @default 2
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.indent()
-     * logger.log('Indented')
-     * logger.dedent()
-     * logger.log('Back to normal')
-     *
-     * // Remove custom amount
-     * logger.indent(4)
-     * logger.log('Four spaces')
-     * logger.dedent(4)
-     *
-     * // Stream-specific dedent
-     * logger.stdout.indent()
-     * logger.stdout.log('Indented stdout')
-     * logger.stdout.dedent()
-     * ```
-     */
-    dedent(spaces?: number): this;
-    /**
-     * Displays an object's properties in a formatted way.
-     *
-     * Works like `console.dir()` with customizable options for depth,
-     * colors, etc. Useful for inspecting complex objects.
-     *
-     * @param obj - The object to display
-     * @param options - Optional formatting options (Node.js inspect options)
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * const obj = { a: 1, b: { c: 2, d: { e: 3 } } }
-     * logger.dir(obj)
-     * logger.dir(obj, { depth: 1 })  // Limit nesting depth
-     * logger.dir(obj, { colors: true })  // Enable colors
-     * ```
-     */
-    dir(obj: unknown, options?: unknown | undefined): this;
-    /**
-     * Displays data as XML/HTML in a formatted way.
-     *
-     * Works like `console.dirxml()`. In Node.js, behaves the same as `dir()`.
-     *
-     * @param data - The data to display
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.dirxml(document.body)  // In browser environments
-     * logger.dirxml(xmlObject)       // In Node.js
-     * ```
-     */
-    dirxml(...data: unknown[]): this;
-    /**
-     * Logs a completion message with a success symbol (alias for `success()`).
-     *
-     * Provides semantic clarity when marking something as "done". Does NOT
-     * automatically clear the current line - call `clearLine()` first if
-     * needed after using `progress()`.
-     *
-     * @param args - Message and additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.done('Task completed')
-     *
-     * // After progress indicator
-     * logger.progress('Processing...')
-     * // ... do work ...
-     * logger.clearLine()
-     * logger.done('Processing complete')
-     * ```
-     */
-    done(...args: unknown[]): this;
-    /**
-     * Logs an error message to stderr.
-     *
-     * Automatically applies current indentation. All arguments are formatted
-     * and logged like `console.error()`.
-     *
-     * @param args - Message and additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.error('Build failed')
-     * logger.error('Error code:', 500)
-     * logger.error('Details:', { message: 'Not found' })
-     * ```
-     */
-    error(...args: unknown[]): this;
-    /**
-     * Logs a newline to stderr only if the last line wasn't already blank.
-     *
-     * Prevents multiple consecutive blank lines. Useful for adding spacing
-     * between sections without creating excessive whitespace.
-     *
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.error('Error message')
-     * logger.errorNewline()  // Adds blank line
-     * logger.errorNewline()  // Does nothing (already blank)
-     * logger.error('Next section')
-     * ```
-     */
-    errorNewline(): this;
-    /**
-     * Logs a failure message with a red colored fail symbol.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.fail` (red ✖).
-     * Always outputs to stderr. If the message starts with an existing
-     * symbol, it will be stripped and replaced.
-     *
-     * @param args - Message and additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.fail('Build failed')
-     * logger.fail('Test suite failed:', { passed: 5, failed: 3 })
-     * ```
-     */
-    fail(...args: unknown[]): this;
-    /**
-     * Starts a new indented log group.
-     *
-     * If a label is provided, it's logged before increasing indentation.
-     * Groups can be nested. Each group increases indentation by the
-     * `kGroupIndentWidth` (default 2 spaces). Call `groupEnd()` to close.
-     *
-     * @param label - Optional label to display before the group
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.group('Processing files:')
-     * logger.log('file1.js')
-     * logger.log('file2.js')
-     * logger.groupEnd()
-     *
-     * // Nested groups
-     * logger.group('Outer')
-     * logger.log('Outer content')
-     * logger.group('Inner')
-     * logger.log('Inner content')
-     * logger.groupEnd()
-     * logger.groupEnd()
-     * ```
-     */
-    group(...label: unknown[]): this;
-    /**
-     * Starts a new collapsed log group (alias for `group()`).
-     *
-     * In browser consoles, this creates a collapsed group. In Node.js,
-     * it behaves identically to `group()`.
-     *
-     * @param label - Optional label to display before the group
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.groupCollapsed('Details')
-     * logger.log('Hidden by default in browsers')
-     * logger.groupEnd()
-     * ```
-     */
-    groupCollapsed(...label: unknown[]): this;
-    /**
-     * Ends the current log group and decreases indentation.
-     *
-     * Must be called once for each `group()` or `groupCollapsed()` call
-     * to properly close the group and restore indentation.
-     *
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.group('Group 1')
-     * logger.log('Content')
-     * logger.groupEnd()  // Closes 'Group 1'
-     * ```
-     */
-    groupEnd(): this;
-    /**
-     * Increases the indentation level by adding spaces to the prefix.
-     *
-     * When called on the main logger, affects both stderr and stdout indentation.
-     * When called on a stream-bound logger (`.stderr` or `.stdout`), affects
-     * only that stream's indentation. Maximum indentation is 1000 spaces.
-     *
-     * @param spaces - Number of spaces to add to indentation
-     * @default 2
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.log('Level 0')
-     * logger.indent()
-     * logger.log('Level 1')
-     * logger.indent()
-     * logger.log('Level 2')
-     * logger.dedent()
-     * logger.dedent()
-     *
-     * // Custom indent amount
-     * logger.indent(4)
-     * logger.log('Indented 4 spaces')
-     * logger.dedent(4)
-     *
-     * // Stream-specific indent
-     * logger.stdout.indent()
-     * logger.stdout.log('Only stdout is indented')
-     * ```
-     */
-    indent(spaces?: number): this;
-    /**
-     * Logs an informational message with a blue colored info symbol.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.info` (blue ℹ).
-     * Always outputs to stderr. If the message starts with an existing
-     * symbol, it will be stripped and replaced.
-     *
-     * @param args - Message and additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.info('Starting build process')
-     * logger.info('Configuration loaded:', config)
-     * logger.info('Using cache directory:', cacheDir)
-     * ```
-     */
-    info(...args: unknown[]): this;
-    /**
-     * Logs a message to stdout.
-     *
-     * Automatically applies current indentation. All arguments are formatted
-     * and logged like `console.log()`. This is the primary method for
-     * standard output.
-     *
-     * @param args - Message and additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.log('Processing complete')
-     * logger.log('Items processed:', 42)
-     * logger.log('Results:', { success: true, count: 10 })
-     *
-     * // Method chaining
-     * logger.log('Step 1').log('Step 2').log('Step 3')
-     * ```
-     */
-    log(...args: unknown[]): this;
-    /**
-     * Logs a newline to stdout only if the last line wasn't already blank.
-     *
-     * Prevents multiple consecutive blank lines. Useful for adding spacing
-     * between sections without creating excessive whitespace.
-     *
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.log('Section 1')
-     * logger.logNewline()  // Adds blank line
-     * logger.logNewline()  // Does nothing (already blank)
-     * logger.log('Section 2')
-     * ```
-     */
-    logNewline(): this;
-    /**
-     * Shows a progress indicator that can be cleared with `clearLine()`.
-     *
-     * Displays a simple status message with a '∴' prefix. Does not include
-     * animation or spinner. Intended to be cleared once the operation completes.
-     * The output stream (stderr or stdout) depends on whether the logger is
-     * stream-bound.
-     *
-     * @param text - The progress message to display
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.progress('Processing files...')
-     * // ... do work ...
-     * logger.clearLine()
-     * logger.success('Files processed')
-     *
-     * // Stream-specific progress
-     * logger.stdout.progress('Loading...')
-     * // ... do work ...
-     * logger.stdout.clearLine()
-     * logger.stdout.log('Done')
-     * ```
-     */
-    progress(text: string): this;
-    /**
-     * Resets all indentation to zero.
-     *
-     * When called on the main logger, resets both stderr and stdout indentation.
-     * When called on a stream-bound logger (`.stderr` or `.stdout`), resets
-     * only that stream's indentation.
-     *
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.indent().indent().indent()
-     * logger.log('Very indented')
-     * logger.resetIndent()
-     * logger.log('Back to zero indentation')
-     *
-     * // Reset only stdout
-     * logger.stdout.resetIndent()
-     * ```
-     */
-    resetIndent(): this;
-    /**
-     * Logs a skip message with a cyan colored skip symbol.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.skip` (cyan ↻).
-     * Always outputs to stderr. If the message starts with an existing
-     * symbol, it will be stripped and replaced.
-     *
-     * @param args - Message and additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.skip('Test skipped due to environment')
-     * logger.skip('Skipping optional step')
-     * logger.skip('Feature disabled, skipping')
-     * ```
-     */
-    skip(...args: unknown[]): this;
-    /**
-     * Logs a main step message with a cyan arrow symbol and blank line before it.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.step` (cyan →) and
-     * adds a blank line before the message unless the last line was already blank.
-     * Useful for marking major steps in a process with clear visual separation.
-     * Always outputs to stdout. If the message starts with an existing symbol,
-     * it will be stripped and replaced.
-     *
-     * @param msg - The step message to log
-     * @param extras - Additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.step('Building project')
-     * logger.log('Compiling TypeScript...')
-     * logger.step('Running tests')
-     * logger.log('Running test suite...')
-     * // Output:
-     * // [blank line]
-     * // → Building project
-     * // Compiling TypeScript...
-     * // [blank line]
-     * // → Running tests
-     * // Running test suite...
-     * ```
-     */
-    step(msg: string, ...extras: unknown[]): this;
-    /**
-     * Logs an indented substep message (stateless).
-     *
-     * Adds a 2-space indent to the message without affecting the logger's
-     * indentation state. Useful for showing sub-items under a main step.
-     *
-     * @param msg - The substep message to log
-     * @param extras - Additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.log('Installing dependencies:')
-     * logger.substep('Installing react')
-     * logger.substep('Installing typescript')
-     * logger.substep('Installing eslint')
-     * // Output:
-     * // Installing dependencies:
-     * //   Installing react
-     * //   Installing typescript
-     * //   Installing eslint
-     * ```
-     */
-    substep(msg: string, ...extras: unknown[]): this;
-    /**
-     * Logs a success message with a green colored success symbol.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.success` (green ✔).
-     * Always outputs to stderr. If the message starts with an existing
-     * symbol, it will be stripped and replaced.
-     *
-     * @param args - Message and additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.success('Build completed')
-     * logger.success('Tests passed:', { total: 42, passed: 42 })
-     * logger.success('Deployment successful')
-     * ```
-     */
-    success(...args: unknown[]): this;
-    /**
-     * Displays data in a table format.
-     *
-     * Works like `console.table()`. Accepts arrays of objects or
-     * objects with nested objects. Optionally specify which properties
-     * to include in the table.
-     *
-     * @param tabularData - The data to display as a table
-     * @param properties - Optional array of property names to include
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * // Array of objects
-     * logger.table([
-     *   { name: 'Alice', age: 30 },
-     *   { name: 'Bob', age: 25 }
-     * ])
-     *
-     * // Specify properties to show
-     * logger.table(users, ['name', 'email'])
-     *
-     * // Object with nested objects
-     * logger.table({
-     *   user1: { name: 'Alice', age: 30 },
-     *   user2: { name: 'Bob', age: 25 }
-     * })
-     * ```
-     */
-    table(tabularData: unknown, properties?: readonly string[] | undefined): this;
-    /**
-     * Starts a timer for measuring elapsed time.
-     *
-     * Creates a timer with the given label. Use `timeEnd()` with the same
-     * label to stop the timer and log the elapsed time, or use `timeLog()`
-     * to check the time without stopping the timer.
-     *
-     * @param label - Optional label for the timer
-     * @default 'default'
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.time('operation')
-     * // ... do work ...
-     * logger.timeEnd('operation')
-     * // Logs: "operation: 123.456ms"
-     *
-     * logger.time()
-     * // ... do work ...
-     * logger.timeEnd()
-     * // Logs: "default: 123.456ms"
-     * ```
-     */
-    time(label?: string | undefined): this;
-    /**
-     * Ends a timer and logs the elapsed time.
-     *
-     * Logs the duration since `console.time()` or `logger.time()` was called
-     * with the same label. The timer is stopped and removed.
-     *
-     * @param label - Optional label for the timer
-     * @default 'default'
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.time('operation')
-     * // ... do work ...
-     * logger.timeEnd('operation')
-     * // Logs: "operation: 123.456ms"
-     *
-     * logger.time()
-     * // ... do work ...
-     * logger.timeEnd()
-     * // Logs: "default: 123.456ms"
-     * ```
-     */
-    timeEnd(label?: string | undefined): this;
-    /**
-     * Logs the current value of a timer without stopping it.
-     *
-     * Logs the duration since `console.time()` was called with the same
-     * label, but keeps the timer running. Can include additional data
-     * to log alongside the time.
-     *
-     * @param label - Optional label for the timer
-     * @param data - Additional data to log with the time
-     * @default 'default'
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * console.time('process')
-     * // ... partial work ...
-     * logger.timeLog('process', 'Checkpoint 1')
-     * // Logs: "process: 123.456ms Checkpoint 1"
-     * // ... more work ...
-     * logger.timeLog('process', 'Checkpoint 2')
-     * // Logs: "process: 234.567ms Checkpoint 2"
-     * console.timeEnd('process')
-     * ```
-     */
-    timeLog(label?: string | undefined, ...data: unknown[]): this;
-    /**
-     * Logs a stack trace to the console.
-     *
-     * Works like `console.trace()`. Shows the call stack leading to
-     * where this method was called. Useful for debugging.
-     *
-     * @param message - Optional message to display with the trace
-     * @param args - Additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * function debugFunction() {
-     *   logger.trace('Debug point reached')
-     * }
-     *
-     * logger.trace('Trace from here')
-     * logger.trace('Error context:', { userId: 123 })
-     * ```
-     */
-    trace(message?: unknown | undefined, ...args: unknown[]): this;
-    /**
-     * Logs a warning message with a yellow colored warning symbol.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.warn` (yellow ⚠).
-     * Always outputs to stderr. If the message starts with an existing
-     * symbol, it will be stripped and replaced.
-     *
-     * @param args - Message and additional arguments to log
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.warn('Deprecated API used')
-     * logger.warn('Low memory:', { available: '100MB' })
-     * logger.warn('Missing optional configuration')
-     * ```
-     */
-    warn(...args: unknown[]): this;
-    /**
-     * Writes text directly to stdout without a newline or indentation.
-     *
-     * Useful for progress indicators or custom formatting where you need
-     * low-level control. Does not apply any indentation or formatting.
-     *
-     * @param text - The text to write
-     * @returns The logger instance for chaining
-     *
-     * @example
-     * ```typescript
-     * logger.write('Processing... ')
-     * // ... do work ...
-     * logger.write('done\n')
-     *
-     * // Build a line incrementally
-     * logger.write('Step 1')
-     * logger.write('... Step 2')
-     * logger.write('... Step 3\n')
-     * ```
-     */
-    write(text: string): this;
-}
-/**
- * Get the default logger instance.
- * Lazily creates the logger to avoid circular dependencies during module initialization.
- * Reuses the same instance across calls.
- *
- * @returns Shared default logger instance
- *
- * @example
- * ```ts
- * import { getDefaultLogger } from '@socketsecurity/lib/logger'
- *
- * const logger = getDefaultLogger()
- * logger.log('Application started')
- * logger.success('Configuration loaded')
- * ```
- */
-export declare function getDefaultLogger(): Logger;